001/*****************************************************************************
002 * Copyright by The HDF Group.                                               *
003 * Copyright by the Board of Trustees of the University of Illinois.         *
004 * All rights reserved.                                                      *
005 *                                                                           *
006 * This file is part of the HDF Java Products distribution.                  *
007 * The full copyright notice, including terms governing use, modification,   *
008 * and redistribution, is contained in the COPYING file, which can be found  *
009 * at the root of the source code distribution tree,                         *
010 * or in https://www.hdfgroup.org/licenses.                                  *
011 * If you do not have access to either file, you may request a copy from     *
012 * help@hdfgroup.org.                                                        *
013 ****************************************************************************/
014
015package hdf.object;
016
017import java.util.Collection;
018
019/**
020 * An interface that provides general attribute operations for object data. For
021 * example, reference to a parent object.
022 *
023 * @see hdf.object.HObject
024 */
025public interface Attribute {
026    /**
027     * Returns the HObject to which this Attribute is currently "attached".
028     *
029     * @return the HObject to which this Attribute is currently "attached".
030     */
031    HObject getParentObject();
032
033    /**
034     * Sets the HObject to which this Attribute is "attached".
035     *
036     * @param pObj
037     *            the new HObject to which this Attributet is "attached".
038     */
039    void setParentObject(HObject pObj);
040
041    /**
042     * set a property for the attribute.
043     *
044     * @param key the attribute Map key
045     * @param value the attribute Map value
046     */
047    void setProperty(String key, Object value);
048
049    /**
050     * get a property for a given key.
051     *
052     * @param key the attribute Map key
053     *
054     * @return the property
055     */
056    Object getProperty(String key);
057
058    /**
059     * get all property keys.
060     *
061     * @return the Collection of property keys
062     */
063    Collection<String> getPropertyKeys();
064
065    /**
066     * Returns the name of the attribute.
067     *
068     * @return The name of the attribute.
069     */
070    String getAttributeName();
071
072    /**
073     * Retrieves the attribute data from the file.
074     *
075     * @return the attribute data.
076     *
077     * @throws Exception
078     *             if the data can not be retrieved
079     */
080    Object getAttributeData() throws Exception, OutOfMemoryError;
081
082    /**
083     * Returns the datatype of the attribute.
084     *
085     * @return the datatype of the attribute.
086     */
087    Datatype getAttributeDatatype();
088
089    /**
090     * Returns the space type for the attribute. It returns a
091     * negative number if it failed to retrieve the type information from
092     * the file.
093     *
094     * @return the space type for the attribute.
095     */
096    int getAttributeSpaceType();
097
098    /**
099     * Returns the rank (number of dimensions) of the attribute. It returns a
100     * negative number if it failed to retrieve the dimension information from
101     * the file.
102     *
103     * @return the number of dimensions of the attribute.
104     */
105    int getAttributeRank();
106
107    /**
108     * Returns the array that contains the dimension sizes of the data value of
109     * the attribute. It returns null if it failed to retrieve the dimension
110     * information from the file.
111     *
112     * @return the dimension sizes of the attribute.
113     */
114    long[] getAttributeDims();
115
116    /**
117     * Returns the selected size of the rows and columns of the attribute. It returns a
118     * negative number if it failed to retrieve the size information from
119     * the file.
120     *
121     * @return the selected size of the rows and colums of the attribute.
122     */
123    int getAttributePlane();
124
125    /**
126     * @return true if the dataspace is a NULL; otherwise, returns false.
127     */
128    boolean isAttributeNULL();
129
130    /**
131     * @return true if the data is a single scalar point; otherwise, returns false.
132     */
133    boolean isAttributeScalar();
134
135    /**
136     * Not for public use in the future.
137     *
138     * setData() is not safe to use because it changes memory buffer
139     * of the dataset object. Dataset operations such as write/read
140     * will fail if the buffer type or size is changed.
141     *
142     * @param d  the object data -must be an array of Objects
143     */
144    void setAttributeData(Object d);
145
146    /**
147     * Writes the memory buffer of this dataset to file.
148     *
149     * @throws Exception if buffer can not be written
150     */
151    void writeAttribute() throws Exception;
152
153    /**
154     * Writes the given data buffer into this attribute in a file.
155     *
156     * The data buffer is a vector that contains the data values of compound fields. The data is written
157     * into file as one data blob.
158     *
159     * @param buf
160     *            The vector that contains the data values of compound fields.
161     *
162     * @throws Exception
163     *             If there is an error at the library level.
164     */
165    void writeAttribute(Object buf) throws Exception;
166
167    /**
168     * Returns a string representation of the data value. For
169     * example, "0, 255".
170     *
171     * For a compound datatype, it will be a 1D array of strings with field
172     * members separated by the delimiter. For example,
173     * "{0, 10.5}, {255, 20.0}, {512, 30.0}" is a compound attribute of {int,
174     * float} of three data points.
175     *
176     * @param delimiter
177     *            The delimiter used to separate individual data points. It
178     *            can be a comma, semicolon, tab or space. For example,
179     *            toString(",") will separate data by commas.
180     *
181     * @return the string representation of the data values.
182     */
183    String toAttributeString(String delimiter);
184
185    /**
186     * Returns a string representation of the data value. For
187     * example, "0, 255".
188     *
189     * For a compound datatype, it will be a 1D array of strings with field
190     * members separated by the delimiter. For example,
191     * "{0, 10.5}, {255, 20.0}, {512, 30.0}" is a compound attribute of {int,
192     * float} of three data points.
193     *
194     * @param delimiter
195     *            The delimiter used to separate individual data points. It
196     *            can be a comma, semicolon, tab or space. For example,
197     *            toString(",") will separate data by commas.
198     * @param maxItems
199     *            The maximum number of Array values to return
200     *
201     * @return the string representation of the data values.
202     */
203    String toAttributeString(String delimiter, int maxItems);
204}