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