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     * Check if attribute's dataspace is a NULL
127     *
128     * @return true if the dataspace is a NULL; otherwise, returns false.
129     */
130    boolean isAttributeNULL();
131
132    /**
133     * Check if attribute is a single scalar point
134     *
135     * @return true if the data is a single scalar point; otherwise, returns false.
136     */
137    boolean isAttributeScalar();
138
139    /**
140     * Not for public use in the future.
141     *
142     * setAttributeData() is not safe to use because it changes memory buffer of the dataset object. Dataset
143     * operations such as write/read will fail if the buffer type or size is changed.
144     *
145     * @param d the object data -must be an array of Objects
146     */
147    void setAttributeData(Object d);
148
149    /**
150     * Writes the memory buffer of this dataset to file.
151     *
152     * @throws Exception if buffer can not be written
153     */
154    void writeAttribute() throws Exception;
155
156    /**
157     * Writes the given data buffer into this attribute in a file.
158     *
159     * The data buffer is a vector that contains the data values of compound fields. The data is written
160     * into file as one data blob.
161     *
162     * @param buf
163     *            The vector that contains the data values of compound fields.
164     *
165     * @throws Exception
166     *             If there is an error at the library level.
167     */
168    void writeAttribute(Object buf) throws Exception;
169
170    /**
171     * Returns a string representation of the data value. For
172     * example, "0, 255".
173     *
174     * For a compound datatype, it will be a 1D array of strings with field
175     * members separated by the delimiter. For example,
176     * "{0, 10.5}, {255, 20.0}, {512, 30.0}" is a compound attribute of {int,
177     * float} of three data points.
178     *
179     * @param delimiter
180     *            The delimiter used to separate individual data points. It
181     *            can be a comma, semicolon, tab or space. For example,
182     *            toString(",") will separate data by commas.
183     *
184     * @return the string representation of the data values.
185     */
186    String toAttributeString(String delimiter);
187
188    /**
189     * Returns a string representation of the data value. For
190     * example, "0, 255".
191     *
192     * For a compound datatype, it will be a 1D array of strings with field
193     * members separated by the delimiter. For example,
194     * "{0, 10.5}, {255, 20.0}, {512, 30.0}" is a compound attribute of {int,
195     * float} of three data points.
196     *
197     * @param delimiter
198     *            The delimiter used to separate individual data points. It
199     *            can be a comma, semicolon, tab or space. For example,
200     *            toString(",") will separate data by commas.
201     * @param maxItems
202     *            The maximum number of Array values to return
203     *
204     * @return the string representation of the data values.
205     */
206    String toAttributeString(String delimiter, int maxItems);
207}