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}