    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    /**
    033     * Retrieves the object's metadata, such as attributes, from the file.
    034     *
    035     * Metadata, such as attributes, is stored in a List.
    036     *
    037     * @return the list of metadata objects.
    038     *
    039     * @throws Exception
    040     *             if the metadata can not be retrieved
    041     */
    042    List getMetadata() throws Exception;
    043
    044    /**
    045     * Writes a specific piece of metadata (such as an attribute) into the file.
    046     *
    047     * If an HDF(4&amp;5) attribute exists in the file, this method updates its
    048     * value. If the attribute does not exist in the file, it creates the
    049     * attribute in the file and attaches it to the object. It will fail to
    050     * write a new attribute to the object where an attribute with the same name
    051     * already exists. To update the value of an existing attribute in the file,
    052     * one needs to get the instance of the attribute by getMetadata(), change
    053     * its values, then use writeMetadata() to write the value.
    054     *
    055     * @param metadata
    056     *            the metadata to write.
    057     *
    058     * @throws Exception
    059     *             if the metadata can not be written
    060     */
    061    void writeMetadata(Object metadata) throws Exception;
    062
    063    /**
    064     * Deletes an existing piece of metadata from this object.
    065     *
    066     * @param metadata
    067     *            the metadata to delete.
    068     *
    069     * @throws Exception
    070     *             if the metadata can not be removed
    071     */
    072    void removeMetadata(Object metadata) throws Exception;
    073
    074    /**
    075     * Updates an existing piece of metadata attached to this object.
    076     *
    077     * @param metadata
    078     *            the metadata to update.
    079     *
    080     * @throws Exception
    081     *             if the metadata can not be updated
    082     */
    083    void updateMetadata(Object metadata) throws Exception;
    084
    085    /**
    086     * Check if the object has any attributes attached.
    087     *
    088     * @return true if it has any attributes, false otherwise.
    089     */
    090    boolean hasAttribute();
    091
    092    /**
    093     * Removes all of the elements from metadata list.
    094     * The list should be empty after this call returns.
    095     */
    096    void clear();
    097}