    001/*****************************************************************************
    002 * Copyright by The HDF Group.                                               *
    003 * All rights reserved.                                                      *
    004 *                                                                           *
    005 * This file is part of the HDF Java Products distribution.                  *
    006 * The full copyright notice, including terms governing use, modification,   *
    007 * and redistribution, is contained in the COPYING file, which can be found  *
    008 * at the root of the source code distribution tree,                         *
    009 * or in https://www.hdfgroup.org/licenses.                                  *
    010 * If you do not have access to either file, you may request a copy from     *
    011 * help@hdfgroup.org.                                                        *
    012 ****************************************************************************/
    013
    014package hdf.object;
    015
    016/**
    017 * An interface that provides general operations for data with a Compound
    018 * datatype. For example, getting the names, dataspaces or datatypes of the
    019 * members of the Compound datatype.
    020 *
    021 * @see hdf.object.HObject
    022 *
    023 * @version 1.0 5/3/2018
    024 * @author Jordan T. Henderson
    025 */
    026public interface CompoundDataFormat extends DataFormat
    027{
    028    /**
    029     * Returns the number of members of the compound data object.
    030     *
    031     * @return the number of members of the compound data object.
    032     */
    033    int getMemberCount();
    034
    035    /**
    036     * Returns the number of selected members of the compound data object.
    037     *
    038     * Selected members are the compound fields which are selected for read/write.
    039     *
    040     * For example, in a compound datatype of {int A, float B, char[] C}, users can
    041     * choose to retrieve only {A, C} from the data object. In this case,
    042     * getSelectedMemberCount() returns two.
    043     *
    044     * @return the number of selected members.
    045     */
    046    int getSelectedMemberCount();
    047
    048    /**
    049     * Returns the names of the members of the compound data object. The names of
    050     * compound members are stored in an array of Strings.
    051     *
    052     * For example, for a compound datatype of {int A, float B, char[] C}
    053     * getMemberNames() returns ["A", "B", "C"}.
    054     *
    055     * @return the names of compound members.
    056     */
    057    String[] getMemberNames();
    058
    059    /**
    060     * Returns an array of the names of the selected compound members.
    061     *
    062     * @return an array of the names of the selected compound members.
    063     */
    064    String[] getSelectedMemberNames();
    065
    066    /**
    067     * Checks if a member of the compound data object is selected for read/write.
    068     *
    069     * @param idx
    070     *            the index of compound member.
    071     *
    072     * @return true if the i-th memeber is selected; otherwise returns false.
    073     */
    074    boolean isMemberSelected(int idx);
    075
    076    /**
    077     * Selects the i-th member for read/write.
    078     *
    079     * @param idx
    080     *            the index of compound member.
    081     */
    082    void selectMember(int idx);
    083
    084    /**
    085     * Selects/deselects all members.
    086     *
    087     * @param selectAll
    088     *            The indicator to select or deselect all members. If true, all
    089     *            members are selected for read/write. If false, no member is
    090     *            selected for read/write.
    091     */
    092    void setAllMemberSelection(boolean selectAll);
    093
    094    /**
    095     * Returns array containing the total number of elements of the members of the
    096     * compound data object.
    097     *
    098     * For example, a compound dataset COMP has members of A, B and C as
    099     *
    100     * <pre>
    101     *     COMP {
    102     *         int A;
    103     *         float B[5];
    104     *         double C[2][3];
    105     *     }
    106     * </pre>
    107     *
    108     * getMemberOrders() will return an integer array of {1, 5, 6} to indicate that
    109     * member A has one element, member B has 5 elements, and member C has 6
    110     * elements.
    111     *
    112     * @return the array containing the total number of elements of the members of
    113     *         the compound data object.
    114     */
    115    int[] getMemberOrders();
    116
    117    /**
    118     * Returns array containing the total number of elements of the selected members
    119     * of the compound data object.
    120     *
    121     * For example, a compound dataset COMP has members of A, B and C as
    122     *
    123     * <pre>
    124     *     COMP {
    125     *         int A;
    126     *         float B[5];
    127     *         double C[2][3];
    128     *     }
    129     * </pre>
    130     *
    131     * If A and B are selected, getSelectedMemberOrders() returns an array of {1, 5}
    132     *
    133     * @return array containing the total number of elements of the selected members
    134     *         of the compound data object.
    135     */
    136    int[] getSelectedMemberOrders();
    137
    138    /**
    139     * Returns the dimension sizes of the i-th member.
    140     *
    141     * For example, a compound dataset COMP has members of A, B and C as
    142     *
    143     * <pre>
    144     *     COMP {
    145     *         int A;
    146     *         float B[5];
    147     *         double C[2][3];
    148     *     }
    149     * </pre>
    150     *
    151     * getMemberDims(2) returns an array of {2, 3}, while getMemberDims(1) returns
    152     * an array of {5}, and getMemberDims(0) returns null.
    153     *
    154     * @param i
    155     *            the i-th member
    156     *
    157     * @return the dimension sizes of the i-th member, null if the compound member
    158     *         is not an array.
    159     */
    160    int[] getMemberDims(int i);
    161
    162    /**
    163     * Returns an array of datatype objects of the compound members.
    164     *
    165     * Each member of a compound data object has its own datatype. The datatype of a
    166     * member can be atomic or other compound datatype (nested compound). The
    167     * datatype objects are setup at init().
    168     *
    169     * @return the array of datatype objects of the compound members.
    170     */
    171    Datatype[] getMemberTypes();
    172
    173    /**
    174     * Returns an array of datatype objects of the selected compound members.
    175     *
    176     * @return an array of datatype objects of the selected compound members.
    177     */
    178    Datatype[] getSelectedMemberTypes();
    179
    180}