View Javadoc

1   /*
2    * $Id: ILibraryDescriptor.java,v 1.9 2005/05/31 16:04:12 jlerner Exp $
3    *
4    * Copyright (c) 1999-2004, BBN Technologies, LLC.
5    * All rights reserved.
6    * http://www.daml.org/legal/opensource/bbn_license.html
7    */
8    
9   package com.bbn.swede.core.libraries;
10  
11  import java.io.File;
12  import java.util.List;
13  import java.util.Properties;
14  
15  import org.eclipse.core.runtime.IPath;
16  import org.eclipse.core.runtime.IProgressMonitor;
17  import org.eclipse.core.runtime.IStatus;
18  
19  import com.bbn.swede.core.dom.IOWLAbstractSyntaxTree;
20  
21  /***
22   * Classes which implement this interface correspond to handles for 
23   * manipulation of SWeDE libraries.  They are the API interface 
24   * for all operations on libraries.
25   * 
26   * <code>ILibraryDescriptor</code>s also have an IConfiguration 
27   * object which manages their configuration. 
28   * 
29   * @author aperezlo
30   */
31  public interface ILibraryDescriptor
32  {
33     /***
34      * Retrieves the ILibrary with which this descriptor is associated.
35      * @return the associated library
36      */
37     ILibrary getLibrary();
38     
39     /***
40      * Retrieves the name of the library represented by this descriptor.
41      * @return The library name
42      */
43     String getName();
44     
45     
46     /***
47      * Attempts to reserve system resources required for the proper operation of 
48      * this ILibraryDescriptor's library.
49      * 
50      * @return true if the library was successfully opened, false otherwise
51      */
52     boolean open();
53     
54     
55     /***
56      * This method provides a way to export an entry of a library to a particular 
57      * directory, represented by the <code>exportPath</code> parameter.  The <code>iled</code> 
58      * represents the entry of the library that should be exported, optionally with the entry's 
59      * associated metadata.
60      * 
61      * 
62      * @param exportPath the path to which the desired entry should be exported
63      * @param iled the entry to be exported 
64      * @param progress an object which should be notified of the progress of this operation
65      * @return IStatus.OK if the operation was a success, IStatus.CANCEL if it was canceled, IStatus.ERROR otherwise.
66      */
67     IStatus export(IPath exportPath, ILibraryEntryDescriptor iled, IProgressMonitor progress);
68     
69     
70     /***
71      * Returns true if this library is available for operations, and false otherwise.  Some examples 
72      * of times when a library would be unavailable for operations include if the library is 
73      * currently in the process of being written to disk, or if the library is being 
74      * refreshed.
75      * 
76      * 
77      * @return true if this library is available for operations, false otherwise
78      */
79     boolean isAvailable();
80     
81     
82     
83     /***
84      *  Called when a library is deleted. 
85      */
86     void delete();
87     
88     /***
89      * Add a new entry to this library descriptor's library.  This is a temporary 
90      * add and will not be permanent until the library is written to disk 
91      * using either {@link #writeLibrary()} or {@link #writeLibrary(String)}. 
92      * 
93      * @param iled the {@link ILibraryEntryDescriptor} representing the
94      * entry to be added to this library descriptor's library
95      */
96     void addEntry(ILibraryEntryDescriptor iled);
97     /***
98      * Removes a library entry from this library.  This change is not 
99      * permanent until the library is written to disk using either
100     * {@link #writeLibrary()} or {@link #writeLibrary(String)}.
101     * 
102     * @param iled The entry top remove
103     */
104    void removeEntry(ILibraryEntryDescriptor iled);
105 
106    /***
107     * Associates this descriptor with a new library.
108     * @param l the new library
109     */
110    void setLibrary(Library l);
111    /***
112     * This method will create a new ILibraryEntry and add it to this object's 
113     * ILibrary, and return the descriptor associated with the 'Entry.
114     * 
115     * @param file the file representing the document to be added to the library 
116     * @param props a set of properties holding metadata about the file 
117     * @param oast a serialized version of the {@link IOWLAbstractSyntaxTree} 
118     *             associated with this ontology, or <code>null</code>
119     * @return a <code>ILibraryEntryDescriptor</code> that is associated witht the entry just created 
120     */
121    ILibraryEntryDescriptor createEntry(File file, Properties props, IOWLAbstractSyntaxTree oast);
122 
123    /***
124     * Retrieves the configuration object for this descriptor.
125     * @return this descriptor's {@link IConfiguration} object. 
126     */
127    IConfiguration getConfiguration();
128    
129    /***
130     * Writes the library to disk in the default library location.
131     */
132    void writeLibrary();
133    
134    /***
135     * Writes the library to disk in the specified path.
136     * @param path a String representing a location on disk
137     */
138    void writeLibrary(String path);
139    
140    /***
141     * Releases any system resources associated with the ILibrary that 
142     * are held by this ILibraryDescriptor.
143     * 
144     * @return true if there were no exceptions generated during this operation, false otherwise
145     */
146    boolean close();
147    
148    /***
149     * Retrieves the descriptors for all entries in this library.
150     * @return a List of ILibraryEntryDescriptor objects for the entries in 
151     *         this library
152     */
153    List getEntryDescriptors();
154    /***
155     * Checks whether this library contains a particular file.
156     * @param fileName the file name
157     * @return <code>true</code> if there is a ILibraryEntryDescriptor that 
158     *         matches <code>fileName</code>, <code>false</code> if not.
159     */
160    boolean contains(String fileName);
161    /***
162     * Retrieves the entry descriptor for a particular file within the library.
163     * @param fileName the file name of the desired entry
164     * @return the ILibraryEntryDescriptor associated with <code>fileName</code>, 
165     *         or <code>null</code> if one cannot be found 
166     */
167    ILibraryEntryDescriptor getDescriptorFor(String fileName);
168    /***
169     * Checks whether this library contains a file with a particular base URI.
170     * @param sUri The desired base URI
171     * @return <code>true</code> if a document contained in this library has the
172     *         specified base URI, <code>false</code> otherwise 
173     */
174    boolean containsURI(String sUri); 
175 
176    /***
177     * Registers an object for notifications of changes to this library.
178     * @param lcl The listener to register.  If <code>lcl</code> is already
179     *            registered as a change listener for this library, this method
180     *            has no effect.
181     */
182    void addLibraryChangeListener(ILibraryChangeListener lcl);
183    /***
184     * Unregisters an object from notifications of changes to this library.
185     * @param lcl The listener to unregister.  If <code>lcl</code> is not 
186     *            registered as a change listener for this library,
187     *            this method has no effect.
188     */
189    void removeLibraryChangeListener(ILibraryChangeListener lcl);
190    
191    /***
192     * Retrieves the entry descriptor for a particular URI within this library.
193     * @param sUri The base URI of the desired entry
194     * @return the ILibraryEntryDescriptor associated with <code>sUri</code>, 
195     *         or <code>null</code> if a matching entry cannot be found
196     */
197    ILibraryEntryDescriptor getDescriptorForURI(String sUri);
198 
199    /***
200     * Re-downloads each of the documents in the library which are 
201     * marked for automatic update and rebuilds the library with the 
202     * updated sources.
203     * 
204     * @param progress a progress monitor
205     * @return an IStatus object representing the result of the refresh operation attempt
206     */
207    IStatus refresh(IProgressMonitor progress);
208    
209    /***
210     * Performs an edit operation, encapsulated in the LibraryEdit 
211     * object upon this library and its descriptor.
212     * 
213     * @param edit the edit operation
214     * @param progress an object to be notified of the progress of this operation
215     * @return <code>IStatus.OK</code> if the operation was a success, 
216     *         <code>IStatus.CANCEL</code> if it was canceled, or 
217     *         <code>IStatus.ERROR</code> otherwise
218     */
219    IStatus edit(LibraryEdit edit, IProgressMonitor progress);
220    
221    
222 }