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 file COPYING.                     *
009 * COPYING can be found at the root of the source code distribution tree.    *
010 * If you do not have access to this file, you may request a copy from       *
011 * help@hdfgroup.org.                                                        *
012 ****************************************************************************/
013
014package hdf.object;
015
016import java.util.List;
017
018/**
019 * An interface that provides general I/O operations for read/write object data.
020 * For example, reading data content or data attribute from file into memory or
021 * writing data content or data attribute from memory into file.
022 * <p>
023 *
024 * @see hdf.object.HObject
025 *
026 * @version 1.1 9/4/2007
027 * @author Peter X. Cao
028 */
029@SuppressWarnings("rawtypes")
030public interface DataFormat {
031    /**
032     * Returns the full path of the file that contains this data object.
033     * <p>
034     * The file name is necessary because data objects are uniquely identified
035     * by object reference and file name when mutilple files are opened at the
036     * same time.
037     *
038     * @return the full path of the file.
039     */
040    public abstract String getFile();
041
042    /**
043     * Retrieves the metadata such as attributes from file.
044     * <p>
045     * Metadata such as attributes are stored in a List.
046     *
047     * @return the list of metadata objects.
048     *
049     * @throws Exception if the metadata can not be retrieved
050     */
051    public abstract List getMetadata() throws Exception;
052
053    /**
054     * Writes a specific metadata (such as attribute) into file.
055     *
056     * If an HDF(4&amp;5) attribute exists in file, the method updates its value.
057     * If the attribute does not exists in file, it creates the attribute in
058     * file and attaches it to the object.
059     * It will fail to write a new attribute to the object where an attribute
060     * with the same name already exists.
061     * To update the value of an existing attribute in file, one needs to get
062     * the instance of the attribute by getMetadata(), change its values,
063     * and use writeMetadata() to write the value.
064     *
065     * @param info
066     *            the metadata to write.
067     *
068     * @throws Exception if the metadata can not be written
069     */
070    public abstract void writeMetadata(Object info) throws Exception;
071
072    /**
073     * Deletes an existing metadata from this data object.
074     *
075     * @param info
076     *            the metadata to delete.
077     *
078     * @throws Exception if the metadata can not be removed
079     */
080    public abstract void removeMetadata(Object info) throws Exception;
081
082    /**
083     * Updates an existing metadata from this data object.
084     *
085     * @param info
086     *            the metadata to update.
087     *
088     * @throws Exception if the metadata can not be updated
089     */
090    public abstract void updateMetadata(Object info) throws Exception;
091
092    /**
093     * Check if the object has any attributes attached.
094     *
095     * @return true if it has any attribute(s), false otherwise.
096     */
097    public abstract boolean hasAttribute();
098
099}