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.fits;
016
017import java.util.List;
018
019import hdf.object.FileFormat;
020import hdf.object.Group;
021
022/**
023 * An H5Group represents HDF5 group, inheriting from Group.
024 * Every HDF5 object has at least one name. An HDF5 group is used to store
025 * a set of the names together in one place, i.e. a group. The general
026 * structure of a group is similar to that of the UNIX file system in
027 * that the group may contain references to other groups or data objects
028 * just as the UNIX directory may contain subdirectories or files.
029 *
030 * @version 1.1 9/4/2007
031 * @author Peter X. Cao
032 */
033public class FitsGroup extends Group
034{
035    private static final long serialVersionUID = 4993155577664991838L;
036
037    /**
038     * The list of attributes of this data object. Members of the list are
039     * instance of AttributeDatset.
040     */
041    private List attributeList;
042
043    /** The default object ID for HDF5 objects */
044    private static final long[] DEFAULT_OID = {0};
045
046    /**
047     * Constructs an HDF5 group with specific name, path, and parent.
048     *
049     * @param fileFormat the file which containing the group.
050     * @param name the name of this group.
051     * @param path the full path of this group.
052     * @param parent the parent of this group.
053     * @param theID the unique identifier of this data object.
054     */
055    public FitsGroup(FileFormat fileFormat, String name, String path, Group parent, long[] theID) {
056        super (fileFormat, name, path, parent, ((theID == null) ? DEFAULT_OID : theID));
057    }
058
059    /*
060     * (non-Javadoc)
061     * @see hdf.object.DataFormat#hasAttribute()
062     */
063    public boolean hasAttribute () {
064        return false;
065    }
066
067    // Implementing DataFormat
068    /**
069     * Retrieves the object's metadata, such as attributes, from the file.
070     *
071     * Metadata, such as attributes, is stored in a List.
072     *
073     * @return the list of metadata objects.
074     *
075     * @throws Exception
076     *             if the metadata can not be retrieved
077     */
078    public List getMetadata() throws Exception {
079        if (!isRoot())
080            return null; // there is only one group in the file: the root
081
082        if (attributeList != null)
083            return attributeList;
084
085        return attributeList;
086    }
087
088    /**
089     * Writes a specific piece of metadata (such as an attribute) into the file.
090     *
091     * If an HDF(4&5) attribute exists in the file, this method updates its
092     * value. If the attribute does not exist in the file, it creates the
093     * attribute in the file and attaches it to the object. It will fail to
094     * write a new attribute to the object where an attribute with the same name
095     * already exists. To update the value of an existing attribute in the file,
096     * one needs to get the instance of the attribute by getMetadata(), change
097     * its values, then use writeMetadata() to write the value.
098     *
099     * @param info
100     *            the metadata to write.
101     *
102     * @throws Exception
103     *             if the metadata can not be written
104     */
105    public void writeMetadata(Object info) throws Exception {
106        // not supported
107        throw new UnsupportedOperationException("Unsupported operation for FITS.");
108    }
109
110    /**
111     * Deletes an existing piece of metadata from this object.
112     *
113     * @param info
114     *            the metadata to delete.
115     *
116     * @throws Exception
117     *             if the metadata can not be removed
118     */
119    public void removeMetadata(Object info) throws Exception {
120        // not supported
121        throw new UnsupportedOperationException("Unsupported operation for FITS.");
122    }
123
124    /**
125     * Updates an existing piece of metadata attached to this object.
126     *
127     * @param info
128     *            the metadata to update.
129     *
130     * @throws Exception
131     *             if the metadata can not be updated
132     */
133    public void updateMetadata(Object info) throws Exception {
134        // not supported
135        throw new UnsupportedOperationException("Unsupported operation for FITS.");
136    }
137
138    // Implementing DataFormat
139    @Override
140    public long open() {
141        // not supported
142        throw new UnsupportedOperationException("Unsupported operation for FITS.");
143    }
144
145    /**
146     *  close group access
147     *
148     * @param gid
149     *        the group identifier
150     */
151    @Override
152    public void close(long gid) {
153        // not supported
154        throw new UnsupportedOperationException("Unsupported operation for FITS.");
155    }
156
157    /**
158     * Creates a new group.
159     *
160     * @param name
161     *        the name of the group to create.
162     * @param pgroup
163     *        the parent group of the new group.
164     *
165     * @return the new group if successful. Otherwise returns null.
166     *
167     * @throws Exception
168     *            if there is an error
169     */
170    public static FitsGroup create(String name, Group pgroup) throws Exception {
171        // not supported
172        throw new UnsupportedOperationException("Unsupported operation for FITS.");
173    }
174
175    //Implementing DataFormat
176    /**
177     * Retrieves the object's metadata, such as attributes, from the file.
178     *
179     * Metadata, such as attributes, is stored in a List.
180     *
181     * @param attrPropList
182     *             the list of properties to get
183     *
184     * @return the list of metadata objects.
185     *
186     * @throws Exception
187     *             if the metadata can not be retrieved
188     */
189    public List getMetadata(int... attrPropList) throws Exception {
190        throw new UnsupportedOperationException("getMetadata(int... attrPropList) is not supported");
191    }
192
193}