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