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.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 * <p>
024 *
025 * @see hdf.object.HObject
026 *
027 * @version 2.0 4/2/2018
028 * @author Peter X. Cao, Jordan T. Henderson
029 */
030@SuppressWarnings("rawtypes")
031public interface MetaDataContainer {
032    /**
033     * Retrieves the object's metadata, such as attributes, from the file.
034     * <p>
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    public abstract 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    public abstract 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    public abstract 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    public abstract 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    public abstract boolean hasAttribute();
091}