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;
016
017import java.util.List;
018
019/**
020 * An interface that provides general I/O operations for object metadata
021 * attached to an object. For example, reading metadata content from the file
022 * into memory or writing metadata content from memory into the file.
023 *
024 * @see hdf.object.HObject
025 *
026 * @version 2.0 4/2/2018
027 * @author Peter X. Cao, Jordan T. Henderson
028 */
029@SuppressWarnings("rawtypes")
030public interface MetaDataContainer {
031    /**
032     * Retrieves the object's metadata, such as attributes, from the file.
033     *
034     * Metadata, such as attributes, is stored in a List.
035     *
036     * @return the list of metadata objects.
037     *
038     * @throws Exception
039     *             if the metadata can not be retrieved
040     */
041    List getMetadata() throws Exception;
042
043    /**
044     * Writes a specific piece of metadata (such as an attribute) into the file.
045     *
046     * If an HDF(4&5) attribute exists in the file, this method updates its
047     * value. If the attribute does not exist in the file, it creates the
048     * attribute in the file and attaches it to the object. It will fail to
049     * write a new attribute to the object where an attribute with the same name
050     * already exists. To update the value of an existing attribute in the file,
051     * one needs to get the instance of the attribute by getMetadata(), change
052     * its values, then use writeMetadata() to write the value.
053     *
054     * @param metadata
055     *            the metadata to write.
056     *
057     * @throws Exception
058     *             if the metadata can not be written
059     */
060    void writeMetadata(Object metadata) throws Exception;
061
062    /**
063     * Deletes an existing piece of metadata from this object.
064     *
065     * @param metadata
066     *            the metadata to delete.
067     *
068     * @throws Exception
069     *             if the metadata can not be removed
070     */
071    void removeMetadata(Object metadata) throws Exception;
072
073    /**
074     * Updates an existing piece of metadata attached to this object.
075     *
076     * @param metadata
077     *            the metadata to update.
078     *
079     * @throws Exception
080     *             if the metadata can not be updated
081     */
082    void updateMetadata(Object metadata) throws Exception;
083
084    /**
085     * Check if the object has any attributes attached.
086     *
087     * @return true if it has any attributes, false otherwise.
088     */
089    boolean hasAttribute();
090
091    /**
092     * Removes all of the elements from metadata list.
093     * The list should be empty after this call returns.
094     */
095    void clear();
096}