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