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 http://hdfgroup.org/products/hdf-java/doc/Copyright.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 read/write object data.
021 * For example, reading data content or data attribute from file into memory or
022 * writing data content or data attribute from memory into file.
023 * <p>
024 * 
025 * @see hdf.object.HObject
026 * 
027 * @version 1.1 9/4/2007
028 * @author Peter X. Cao
029 */
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    public abstract String getFile();
039
040    /**
041     * Retrieves the metadata such as attributes from file.
042     * <p>
043     * Metadata such as attributes are stored in a List.
044     * 
045     * @return the list of metadata objects.
046     */
047    public abstract List getMetadata() throws Exception;
048    
049    /**
050     * Writes a specific metadata (such as attribute) into file.
051     * 
052     * <p>
053     * If an HDF(4&5) attribute exists in file, the method updates its value. 
054     * If the attribute does not exists in file, it creates the attribute in 
055     * file and attaches it to the object.
056     * It will fail to write a new attribute to the object where an attribute 
057     * with the same name already exists.  
058     * To update the value of an existing attribute in file, one needs to get 
059     * the instance of the attribute by getMetadata(), change its values, 
060     * and use writeMetadata() to write the value. 
061     * 
062     * @param info
063     *            the metadata to write.
064     */
065    public abstract void writeMetadata(Object info) throws Exception;
066
067    /**
068     * Deletes an existing metadata from this data object.
069     * 
070     * @param info
071     *            the metadata to delete.
072     */
073    public abstract void removeMetadata(Object info) throws Exception;
074
075    /**
076     * Updates an existing metadata from this data object.
077     * 
078     * @param info
079     *            the metadata to update.
080     */
081    public abstract void updateMetadata(Object info) throws Exception;
082
083    /**
084     * Check if the object has any attributes attached.
085     * 
086     * @return true if it has any attribute(s), false otherwise.
087     */
088    public abstract boolean hasAttribute();
089
090}