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.Iterator;
018import java.util.LinkedList;
019import java.util.List;
020import java.util.Queue;
021import java.util.Stack;
022import java.util.Vector;
023
024/**
025 * Group is an abstract class. Current implementing classes are the H4Group and
026 * H5Group. This class includes general information of a group object such as
027 * members of a group and common operations on groups.
028 * <p>
029 * Members of a group may include other groups, datasets or links.
030 *
031 * @version 1.1 9/4/2007
032 * @author Peter X. Cao
033 */
034public abstract class Group extends HObject implements MetaDataContainer {
035
036    private static final long serialVersionUID = 3913174542591568052L;
037
038    /**
039     * The list of members (Groups and Datasets) of this group in memory.
040     */
041    private List<HObject> memberList;
042
043    /**
044     * The parent group where this group is located. The parent of the root
045     * group is null.
046     */
047    protected Group parent;
048
049    /**
050     * Total number of members of this group in file.
051     */
052    protected int nMembersInFile;
053
054    public static final int LINK_TYPE_HARD = 0;
055
056    public static final int LINK_TYPE_SOFT = 1;
057
058    public static final int LINK_TYPE_EXTERNAL = 64;
059
060    public static final int CRT_ORDER_TRACKED = 1;
061
062    public static final int CRT_ORDER_INDEXED = 2;
063
064
065    /**
066     * Constructs an instance of the group with specific name, path and parent
067     * group. An HDF data object must have a name. The path is the group path
068     * starting from the root. The parent group is the group where this group is
069     * located.
070     * <p>
071     * For example, in H5Group(h5file, "grp", "/groups/", pgroup), "grp" is the
072     * name of the group, "/groups/" is the group path of the group, and pgroup
073     * is the group where "grp" is located.
074     *
075     * @param theFile
076     *            the file containing the group.
077     * @param grpName
078     *            the name of this group, e.g. "grp01".
079     * @param grpPath
080     *            the full path of this group, e.g. "/groups/".
081     * @param grpParent
082     *            the parent of this group.
083     */
084    public Group(FileFormat theFile, String grpName, String grpPath, Group grpParent) {
085        this(theFile, grpName, grpPath, grpParent, null);
086    }
087
088    /**
089     * @deprecated Not for public use in the future.<br>
090     *             Using {@link #Group(FileFormat, String, String, Group)}
091     *
092     * @param theFile
093     *            the file containing the group.
094     * @param grpName
095     *            the name of this group, e.g. "grp01".
096     * @param grpPath
097     *            the full path of this group, e.g. "/groups/".
098     * @param grpParent
099     *            the parent of this group.
100     * @param oid
101     *            the oid of this group.
102     */
103    @Deprecated
104    public Group(FileFormat theFile, String grpName, String grpPath, Group grpParent, long[] oid) {
105        super(theFile, grpName, grpPath, oid);
106
107        this.parent = grpParent;
108    }
109
110    /**
111     * Clears up member list and other resources in memory for the group. Since
112     * the destructor will clear memory space, the function is usually not
113     * needed.
114     */
115    public void clear() {
116        if (memberList != null) {
117            ((Vector<HObject>) memberList).setSize(0);
118        }
119    }
120
121    /**
122     * Adds an object to the member list of this group in memory.
123     *
124     * @param object
125     *            the HObject to be added to the member list.
126     */
127    public void addToMemberList(HObject object) {
128        if (memberList == null) {
129            int size = Math.min(getNumberOfMembersInFile(), this
130                    .getFileFormat().getMaxMembers());
131            memberList = new Vector<>(size + 5);
132        }
133
134        if ((object != null) && !memberList.contains(object)) {
135            memberList.add(object);
136        }
137    }
138
139    /**
140     * Removes an object from the member list of this group in memory.
141     *
142     * @param object
143     *            the HObject (Group or Dataset) to be removed from the member
144     *            list.
145     */
146    public void removeFromMemberList(HObject object) {
147        if (memberList != null) {
148            memberList.remove(object);
149        }
150    }
151
152    /**
153     * Returns the list of members of this group. The list is an java.util.List
154     * containing HObjects.
155     *
156     * @return the list of members of this group.
157     */
158    public List<HObject> getMemberList() {
159        FileFormat theFile = this.getFileFormat();
160
161        if ((memberList == null) && (theFile != null)) {
162            int size = Math.min(getNumberOfMembersInFile(), this.getFileFormat().getMaxMembers());
163            memberList = new Vector<>(size + 5); // avoid infinite loop search for groups without members
164
165            // find the memberList from the file by checking the group path and
166            // name. group may be created out of the structure tree
167            // (H4/5File.loadTree()).
168            if (theFile.getFID() < 0) {
169                try {
170                    theFile.open();
171                } // load the file structure;
172                catch (Exception ex) {
173                    ;
174                }
175            }
176
177            HObject root = theFile.getRootObject();
178            if (root == null) return memberList;
179
180            Iterator<HObject> it = ((Group) root).depthFirstMemberList().iterator();
181            Group g = null;
182            Object uObj = null;
183            while (it.hasNext()) {
184                uObj = it.next();
185
186                if (uObj instanceof Group) {
187                    g = (Group) uObj;
188                    if (g.getPath() != null) // add this check to get rid of null exception
189                    {
190                        if ((this.isRoot() && g.isRoot())
191                                || (this.getPath().equals(g.getPath()) &&
192                                        g.getName().endsWith(this.getName()))) {
193                            memberList = g.getMemberList();
194                            break;
195                        }
196                    }
197                }
198            }
199        }
200
201        return memberList;
202    }
203
204    /**
205     * @return the members of this Group in breadth-first order.
206     */
207    public List<HObject> breadthFirstMemberList() {
208        Vector<HObject> members = new Vector<>();
209        Queue<HObject> queue = new LinkedList<>();
210        HObject currentObj = this;
211
212        queue.addAll(((Group) currentObj).getMemberList());
213
214        while(!queue.isEmpty()) {
215            currentObj = queue.remove();
216            members.add(currentObj);
217
218            if(currentObj instanceof Group && ((Group) currentObj).getNumberOfMembersInFile() > 0) {
219                queue.addAll(((Group) currentObj).getMemberList());
220            }
221        }
222
223        return members;
224    }
225
226    /**
227     * @return the members of this Group in depth-first order.
228     */
229    public List<HObject> depthFirstMemberList() {
230        Vector<HObject> members = new Vector<>();
231        Stack<HObject> stack = new Stack<>();
232        HObject currentObj = this;
233
234        // Push elements onto the stack in reverse order
235        List<HObject> list = ((Group) currentObj).getMemberList();
236        for(int i = list.size() - 1; i >= 0; i--) {
237            stack.push(list.get(i));
238        }
239
240        while(!stack.empty()) {
241            currentObj = stack.pop();
242            members.add(currentObj);
243
244            if(currentObj instanceof Group && ((Group) currentObj).getNumberOfMembersInFile() > 0) {
245                list = ((Group) currentObj).getMemberList();
246                for(int i = list.size() - 1; i >= 0; i--) {
247                    stack.push(list.get(i));
248                }
249            }
250        }
251
252        return members;
253    }
254
255    /**
256     * Sets the name of the group.
257     * <p>
258     * setName (String newName) changes the name of the group in memory and
259     * file.
260     * <p>
261     * setName() updates the path in memory for all the objects that are under
262     * the group with the new name.
263     *
264     * @param newName
265     *            The new name of the group.
266     *
267     * @throws Exception if the name can not be set
268     */
269    @Override
270    public void setName(String newName) throws Exception {
271        super.setName(newName);
272
273        if (memberList != null) {
274            int n = memberList.size();
275            HObject theObj = null;
276            for (int i = 0; i < n; i++) {
277                theObj = memberList.get(i);
278                theObj.setPath(this.getPath() + newName + HObject.SEPARATOR);
279            }
280        }
281    }
282
283    /** @return the parent group. */
284    public final Group getParent() {
285        return parent;
286    }
287
288    /**
289     * Checks if it is a root group.
290     *
291     * @return true if the group is a root group; otherwise, returns false.
292     */
293    public final boolean isRoot() {
294        return (parent == null);
295    }
296
297    /**
298     * Returns the total number of members of this group in file.
299     *
300     * Current Java applications such as HDFView cannot handle files with large
301     * numbers of objects (1,000,000 or more objects) due to JVM memory
302     * limitation. The max_members is used so that applications such as HDFView
303     * will load up to <i>max_members</i> number of objects. If the number of
304     * objects in file is larger than <i>max_members</i>, only
305     * <i>max_members</i> are loaded in memory.
306     * <p>
307     * getNumberOfMembersInFile() returns the number of objects in this group.
308     * The number of objects in memory is obtained by getMemberList().size().
309     *
310     * @return Total number of members of this group in the file.
311     */
312    public int getNumberOfMembersInFile() {
313        return nMembersInFile;
314    }
315
316    /**
317     * Get the HObject at the specified index in this Group's member list.
318     * @param idx The index of the HObject to get.
319     * @return The HObject at the specified index.
320     */
321    public HObject getMember(int idx) {
322        if(memberList.size() <= 0 || idx >= memberList.size()) return null;
323
324        return memberList.get(idx);
325    }
326}