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.view;
016
017import java.util.List;
018
019import javax.swing.JTree;
020import javax.swing.tree.TreeNode;
021
022import hdf.object.FileFormat;
023import hdf.object.Group;
024import hdf.object.HObject;
025
026/**
027 *
028 * <p>
029 * TreeView defines APIs for opening a file and displaying the file structure in
030 * a tree structure.
031 * </p>
032 *
033 * <p>
034 * TreeView uses folders and leaf nodes to represent groups and data objects in
035 * the file. You can expand or collapse folders to navigate data objects in the
036 * file.
037 * </p>
038 *
039 * <p>
040 * From the TreeView, you can open the data content or metadata of the selected
041 * object. You can select object(s) to delete or add new objects to the file.
042 * </p>
043 *
044 * @author Peter X. Cao
045 * @version 2.4 9/6/2007
046 */
047public abstract interface TreeView {
048    /**
049     * Opens a file and retrieves the file structure of the file. It also can be
050     * used to create a new file by setting the accessID to FileFormat.CREATE.
051     *
052     * <p>
053     * Subclasses must implement this function to take appropriate steps to open
054     * a file.
055     * </p>
056     *
057     * @param filename
058     *            the name of the file to open.
059     * @param accessID
060     *            identifier for the file access. Valid value of accessID is:
061     *            <ul>
062     *            <li>FileFormat.READ --- allow read-only access to file.</li>
063     *            <li>FileFormat.WRITE --- allow read and write access to file.</li>
064     *            <li>FileFormat.CREATE --- create a new file.</li>
065     *            </ul>
066     *
067     * @return the FileFormat of this file if successful; otherwise returns
068     *         null.
069     *
070     * @throws Exception if a failure occurred
071     */
072    public abstract FileFormat openFile(String filename, int accessID) throws Exception;
073    public abstract FileFormat reopenFile(FileFormat theFile) throws Exception;
074
075    /**
076     * close a file
077     *
078     * @param file
079     *            the file to close
080     *
081     * @throws Exception if a failure occurred
082     */
083    public abstract void closeFile(FileFormat file) throws Exception;
084
085    /**
086     * save a file
087     *
088     * @param file
089     *            the file to save
090     *
091     * @throws Exception if a failure occurred
092     */
093    public abstract void saveFile(FileFormat file) throws Exception;
094
095    /**
096     * Gets the selected the file. When multiple files are open, we need to know
097     * which file is currently selected.
098     *
099     * @return the FileFormat of the selected file.
100     */
101    public abstract FileFormat getSelectedFile();
102
103    /**
104     * Gets a list of selected objects in the tree. Obtaining a list of current
105     * selected objects is necessary for copy/paste/delete objects.
106     * 
107     * @return a list of selected object in the tree.
108     */
109    public abstract List<?> getSelectedObjects();
110
111    /**
112     * @return the current selected object in the tree.
113     */
114    public abstract HObject getCurrentObject();
115
116    /**
117     * Display the content of a data object.
118     *
119     * @param dataObject
120     *            the data object
121     *
122     * @return the dataview that displays the data content
123     *
124     * @throws Exception if a failure occurred
125     */
126    public abstract DataView showDataContent(HObject dataObject)
127            throws Exception;
128
129    /**
130     * Displays the meta data of a data object.
131     *
132     * @param dataObject
133     *            the data object
134     *
135     * @return the MetaDataView that displays the MetaData of the data object
136     *
137     * @throws Exception if a failure occurred
138     */
139    public abstract MetaDataView showMetaData(HObject dataObject)
140            throws Exception;
141
142    /**
143     * Adds a new data object to the file.
144     * 
145     * @param newObject
146     *            the new object to add.
147     * @param parentGroup
148     *            the parent group the object is to add to.
149     * @throws Exception if an exception occurs while adding a new data object to the file
150     */
151    public abstract void addObject(HObject newObject, Group parentGroup)
152            throws Exception;
153
154    /**
155     * Returns the JTree which holds the file structure.
156     * 
157     * @return the JTree which holds the file structure.
158     */
159    public abstract JTree getTree();
160
161    /**
162     * @return the list of currently open files.
163     */
164    public abstract List<FileFormat> getCurrentFiles();
165
166    /**
167     * @param obj the object to find
168     *
169     * @return the tree node that contains the given data object.
170     */
171    public abstract TreeNode findTreeNode(HObject obj);
172
173}