    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}