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     * Returns an array of the names of the selected compound members.
063     *
064     * @return an array of the names of the selected compound members.
065     */
066    public abstract String[] getSelectedMemberNames();
067
068    /**
069     * Checks if a member of the compound data object is selected for read/write.
070     *
071     * @param idx
072     *            the index of compound member.
073     *
074     * @return true if the i-th memeber is selected; otherwise returns false.
075     */
076    public abstract boolean isMemberSelected(int idx);
077
078    /**
079     * Selects the i-th member for read/write.
080     *
081     * @param idx
082     *            the index of compound member.
083     */
084    public abstract void selectMember(int idx);
085
086    /**
087     * Selects/deselects all members.
088     *
089     * @param selectAll
090     *            The indicator to select or deselect all members. If true, all
091     *            members are selected for read/write. If false, no member is
092     *            selected for read/write.
093     */
094    public abstract void setAllMemberSelection(boolean selectAll);
095
096    /**
097     * Returns array containing the total number of elements of the members of the
098     * compound data object.
099     * <p>
100     * For example, a compound dataset COMP has members of A, B and C as
101     *
102     * <pre>
103     *     COMP {
104     *         int A;
105     *         float B[5];
106     *         double C[2][3];
107     *     }
108     * </pre>
109     *
110     * getMemberOrders() will return an integer array of {1, 5, 6} to indicate that
111     * member A has one element, member B has 5 elements, and member C has 6
112     * elements.
113     *
114     * @return the array containing the total number of elements of the members of
115     *         the compound data object.
116     */
117    public abstract int[] getMemberOrders();
118
119    /**
120     * Returns array containing the total number of elements of the selected members
121     * of the compound data object.
122     *
123     * <p>
124     * For example, a compound dataset COMP has members of A, B and C as
125     *
126     * <pre>
127     *     COMP {
128     *         int A;
129     *         float B[5];
130     *         double C[2][3];
131     *     }
132     * </pre>
133     *
134     * If A and B are selected, getSelectedMemberOrders() returns an array of {1, 5}
135     *
136     * @return array containing the total number of elements of the selected members
137     *         of the compound data object.
138     */
139    public abstract int[] getSelectedMemberOrders();
140
141    /**
142     * Returns the dimension sizes of the i-th member.
143     * <p>
144     * For example, a compound dataset COMP has members of A, B and C as
145     *
146     * <pre>
147     *     COMP {
148     *         int A;
149     *         float B[5];
150     *         double C[2][3];
151     *     }
152     * </pre>
153     *
154     * getMemberDims(2) returns an array of {2, 3}, while getMemberDims(1) returns
155     * an array of {5}, and getMemberDims(0) returns null.
156     *
157     * @param i
158     *            the i-th member
159     *
160     * @return the dimension sizes of the i-th member, null if the compound member
161     *         is not an array.
162     */
163    public abstract int[] getMemberDims(int i);
164
165    /**
166     * Returns an array of datatype objects of the compound members.
167     * <p>
168     * Each member of a compound data object has its own datatype. The datatype of a
169     * member can be atomic or other compound datatype (nested compound). The
170     * datatype objects are setup at init().
171     * <p>
172     *
173     * @return the array of datatype objects of the compound members.
174     */
175    public abstract Datatype[] getMemberTypes();
176
177    /**
178     * Returns an array of datatype objects of the selected compound members.
179     *
180     * @return an array of datatype objects of the selected compound members.
181     */
182    public abstract Datatype[] getSelectedMemberTypes();
183
184}