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