OpenDefinitionsDocument


1   /*BEGIN_COPYRIGHT_BLOCK
2    *
3    * This file is part of DrJava.  Download the current version of this project from http://www.drjava.org/
4    * or http://sourceforge.net/projects/drjava/
5    *
6    * DrJava Open Source License
7    * 
8    * Copyright (C) 2001-2005 JavaPLT group at Rice University (javaplt@rice.edu).  All rights reserved.
9    *
10   * Developed by:   Java Programming Languages Team, Rice University, http://www.cs.rice.edu/~javaplt/
11   * 
12   * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated 
13   * documentation files (the "Software"), to deal with the Software without restriction, including without limitation
14   * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and 
15   * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
16   * 
17   *     - Redistributions of source code must retain the above copyright notice, this list of conditions and the 
18   *       following disclaimers.
19   *     - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the 
20   *       following disclaimers in the documentation and/or other materials provided with the distribution.
21   *     - Neither the names of DrJava, the JavaPLT, Rice University, nor the names of its contributors may be used to 
22   *       endorse or promote products derived from this Software without specific prior written permission.
23   *     - Products derived from this software may not be called "DrJava" nor use the term "DrJava" as part of their 
24   *       names without prior written permission from the JavaPLT group.  For permission, write to javaplt@rice.edu.
25   * 
26   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
27   * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
28   * CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 
29   * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 
30   * WITH THE SOFTWARE.
31   * 
32   *END_COPYRIGHT_BLOCK*/
33  
34  package edu.rice.cs.drjava.model;
35  
36  
37  import java.util.Vector  ;
38  import java.util.List  ;
39  import java.io.*;
40  import java.awt.print.*;
41  import javax.swing.event.DocumentListener  ;
42  import javax.swing.event.UndoableEditListener  ;
43  import javax.swing.text.BadLocationException  ;
44  import javax.swing.text.Position  ;
45  
46  import edu.rice.cs.util.FileOpenSelector;
47  import edu.rice.cs.drjava.model.FileSaveSelector;
48  import edu.rice.cs.util.docnavigation.*;
49  import edu.rice.cs.util.text.AbstractDocumentInterface;
50  import edu.rice.cs.drjava.model.debug.Breakpoint;
51  import edu.rice.cs.drjava.model.Finalizable;
52  import edu.rice.cs.drjava.model.definitions.*;
53  
54  /**
55   * Interface for the GlobalModel's handler of an open
56   * DefinitionsDocument.  Provides a means to interact with
57   * the document.
58   *
59   * @version $Id: OpenDefinitionsDocument.java 4038 2006-11-22 16:20:42Z rcartwright $
60   */
61  public interface OpenDefinitionsDocument extends DJDocument, Finalizable<DefinitionsDocument>,
62    Comparable  <OpenDefinitionsDocument>, INavigatorItem {
63    
64    //----- Forwarding Methods -----/
65  
66    /** The following methods are forwarding methods required by the rest of the program in order for the 
67     *  OpenDefinitionsDocument to handle DefinitionsDocuments */
68    public int id();
69    public int commentLines(int selStart, int selEnd);
70    public int uncommentLines(int selStart, int selEnd);
71    public boolean getClassFileInSync();
72    public int getCurrentLine();
73    public int getCurrentCol();
74    public int getOffset(int lineNum);
75    public String   getQualifiedClassName() throws ClassNameNotFoundException;
76    public String   getQualifiedClassName(int pos) throws ClassNameNotFoundException;
77    public CompoundUndoManager getUndoManager();
78    public void resetUndoManager();
79    public File getCachedClassFile();
80    public void setCachedClassFile(File f);
81    public DocumentListener  [] getDocumentListeners();
82    public UndoableEditListener  [] getUndoableEditListeners();
83    
84    //----- Regular methods -----/
85    
86    //----- Getters and Setters -----/
87    
88    /** Returns the file for this document; does not check whether the file exists. */
89    public File getRawFile();
90    
91    /** Returns the file for this document. 
92     *  @return the file for this document
93     *  @throws FileMovedException if the document's file no longer exists
94     */
95    public File getFile() throws FileMovedException;
96  
97    /** Sets this document's file
98     *  @param file the file that this OpenDefinitionsDocument is associated with
99     */
100   public void setFile(File file);
101   
102   /** Returns the name of this file, or "(Untitled)" if no file. */
103   public String   getFileName();
104   
105   /** Returns canonical path for well-formed file, "(Untitled)" if no file exists, and absolute path if ill-formed. */
106   public String   getCanonicalPath(); 
107 
108   /** Returns canonical path (as defined above) followed by " *" if modified. */
109   public String   getCompletePath(); 
110 
111   /** Returns the parent directory of this file, null if it has none. */
112   public File getParentDirectory();
113 
114   public Pageable getPageable() throws IllegalStateException  ;
115   
116   //----- Simple Predicates -----//
117   
118   /** @return whether the undo manager can perform any undos. */
119   public boolean undoManagerCanUndo();
120   
121   /** @return whether the undo manager can perform any redos. */
122   public boolean undoManagerCanRedo();
123   
124   /** Determines if this document in the file system tree below the active project root. */
125   public boolean inProjectPath();
126   
127   /** Determines if this document in the file system tree below the specified root. */
128   public boolean inNewProjectPath(File root);
129   
130   /** @return true if the document's file is a project auxiliary file. */
131   public boolean isAuxiliaryFile();
132   
133   /** @return true if the document's filename ends with the extension ".java", ".dj0", "dj1", or "dj2". */
134   public boolean isSourceFile();
135   
136   /** @return true if the documents file is saved in the current project file. */
137   public boolean inProject();
138   
139   /** Returns whether this document is currently untitled (indicating whether it has a file yet or not).
140    *  @return true if the document is untitled and has no file
141    */
142   public boolean isUntitled();
143  
144   /** Returns true if the file exists on disk, or if the user has located it on disk. Returns false if the 
145    *  file has been moved or deleted
146    */
147   public boolean fileExists();
148   
149   /** Determines if this definitions document has changed since the last save.
150    *  @return true if the document has been modified
151    */
152   public boolean modifiedOnDisk();
153   
154   /** Resets the document to be unmodified. */
155   public void resetModification();
156   
157   /** Returns the date that this document was last modified. */
158   public long getTimestamp();
159   
160   
161   //----- Major Operations -----//
162   /** Returns the name of the top level class, if any.
163    *  @throws ClassNameNotFoundException if no top level class name found.
164    */
165   public String   getFirstTopLevelClassName() throws ClassNameNotFoundException;
166   
167   /** If the file exists, returns true. If it does not exist, prompts the user to look it up.  If the user
168    *  chooses a file, returns true, false otherwise. */
169   public boolean verifyExists();  
170   
171   /** Saves the document with a FileWriter.  If the file name is already set, the method will use that name 
172    *  instead of whatever selector is passed in.
173    *  @param com a selector that picks the file name
174    *  @exception IOException
175    *  @return true if the file was saved, false if the operation was canceled
176    */
177   public boolean saveFile(FileSaveSelector com) throws IOException;
178 
179   /** Revert the document to the version saved on disk. */
180   public void revertFile() throws IOException;
181 
182   /** Saves the document with a FileWriter.  The FileSaveSelector will either provide a file name or prompt 
183    *  the user for one.  It is up to the caller to decide what needs to be done to choose a file to save to.  
184    *  Once the file has been saved succssfully, this method fires fileSave(File).  If the save fails for any
185    *  reason, the event is not fired.
186    *  @param com a selector that picks the file name.
187    *  @exception IOException
188    *  @return true if the file was saved, false if the operation was canceled
189    */
190   public boolean saveFileAs(FileSaveSelector com) throws IOException;
191 
192   /** Starts compiling the source.  Demands that the definitions be saved before proceeding with the compile.  
193    *  Fires the appropriate events as the compiliation proceeds and finishes.
194    *  @exception IOException if a file with errors cannot be opened
195    */
196   public void startCompile() throws IOException;
197 
198   /** Runs the main method in this document in the interactions pane. Demands that the definitions be saved 
199    *  and compiled before proceeding. Fires an event to signal when execution is about to begin.
200    *  @exception ClassNameNotFoundException propagated from getFirstTopLevelClass()
201    *  @exception IOException propagated from GlobalModel.compileAll()
202    */
203   public void runMain() throws ClassNameNotFoundException, IOException;
204 
205   /** Starts testing the source using JUnit.  Demands that the definitions be saved and compiled before proceeding
206    *  with testing.  Fires the appropriate events as the testing proceeds and finishes.
207    *  TODO: this method is redundant and should be deprecated
208    *  @exception IOException if a file with errors cannot be opened
209    *  @exception ClassNotFoundException when the class is compiled to a location not on the classpath.
210    */
211   public void startJUnit() throws ClassNotFoundException  , IOException;
212 
213   /** Generates Javadoc for this document, saving the output to a temporary directory.  The location is provided
214    *  to the javadocEnded event on the given listener.
215    *  @param saver FileSaveSelector for saving the file if it needs to be saved
216    */
217   public void generateJavadoc(FileSaveSelector saver) throws IOException;
218 
219   /** Determines if this definitions document has changed since the last save.
220    *  @return true if the document has been modified
221    */
222   public boolean isModifiedSinceSave();
223 
224   /** Asks the GlobalModel if it can revert current definitions to version on disk. If ok, it reverts the file 
225    *  to the version on disk.
226    *  @return true if the document has been reverted
227    */
228   public boolean revertIfModifiedOnDisk() throws IOException;
229 
230   /** Returns whether the GlobalModel can abandon this document, asking listeners if isModifiedSinceSave() is true.
231    *  @return true if this document can be abandoned
232    */
233   public boolean canAbandonFile();
234   
235   /** Saves file at user's discretion before quitting.
236    *  @return true if quitting should continue, false if the user cancelled */
237   public boolean quitFile();
238 
239   /** Moves the definitions document to the given line, and returns the resulting character position.
240    *  @param line Destination line number. If line exceeds the number of lines in the document, it is interpreted 
241    *         as the last line.
242    *  @return Index into document of where it moved
243    */
244   public int gotoLine(int line);
245 
246   /** Finds the root directory of the source files.
247    *  @return The root directory of the source files, based on the package statement.
248    *  @throws InvalidPackageException If the package statement is invalid, or if it does not match
249    *          up with the location of the source file.
250    */
251   public File getSourceRoot() throws InvalidPackageException;
252   
253   /**  @return the name of the package currently embedded in document. Forwards to wrapped DefinitionsDocument. */
254   public String   getPackageNameFromDocument();
255 
256   /**  @return the name of the package at the time of the most recent save or load operation. */
257   public String   getPackageName();
258   
259   /** Sets the cached package name returned by getPackageName(); */
260   public void setPackage(String   s);
261   
262   /** Searching backwards finds the name of the enclosing named class or interface. NB: ignores comments.
263    *  WARNING: In long source files and when contained in anonymous inner classes, this function might take a LONG time.
264    *  @param pos Position to start from
265    *  @param qual true to find the fully qualified class name
266    *  @return name of the enclosing named class or interface
267    */
268   public String   getEnclosingClassName(int pos, boolean qual) throws BadLocationException  , ClassNameNotFoundException;
269 
270   public void preparePrintJob() throws BadLocationException  , FileMovedException;
271 
272   public void print() throws PrinterException, BadLocationException  , FileMovedException;
273 
274   public void cleanUpPrintJob();
275 
276   /** Checks if the document is modified. If not, searches for the class file
277    *  corresponding to this document and compares the timestamps of the
278    *  class file to that of the source file.
279    *  @return is the class file and this OpenDefinitionsDocument are in sync
280    */
281   public boolean checkIfClassFileInSync();
282 
283   /** Called when this document is saved so it can notify the cache. */
284   public void documentSaved();
285   
286    /** Called when this document is modified so it can notify the cache. */
287   public void documentModified();
288   
289   /** Called when this document is reset so it can notify the cache. */
290   public void documentReset();
291     
292   /** @return the breakpoint region manager. */
293   public RegionManager<Breakpoint> getBreakpointManager();
294     
295   /** @return the bookmark region manager. */
296   public RegionManager<DocumentRegion> getBookmarkManager();
297     
298   /** @return managers for find result regions. */
299   public List  <RegionManager<MovingDocumentRegion>> getFindResultsManagers();
300   
301   /** Add a region manager for find results to this document.
302    *  @param rm the global model's region manager */
303   public void addFindResultsManager(RegionManager<MovingDocumentRegion> rm);
304   
305   /** Remove a manager for find results from this document.
306    *  @param rm the global model's region manager. */
307   public void removeFindResultsManager(RegionManager<MovingDocumentRegion> rm);
308   
309   /** @return manager for browser history regions. */
310   public RegionManager<DocumentRegion> getBrowserHistoryManager();
311 
312   /** Called when this document is being closed, removing related state from the debug manager. */
313   public void removeFromDebugger();
314   
315   /** Sets the document as modified. */
316   public void updateModifiedSinceSave();
317 
318   /** Should be called when closing an ODD to let the ODD clean up after itself. */
319   public void close();
320   
321   /** @return the initial vertical scroll the pane should use when initialized. */
322   public int getInitialVerticalScroll();
323   
324   /** @return the initial vertical scroll the pane should use when initialized. */
325   public int getInitialHorizontalScroll();
326   
327   /** @return the starting location of the cursor selection that should be set in the pane when initialized. */
328   public int getInitialSelectionStart();
329   
330   /** @return the final location of the cursor selection that should be set in the pane when it is initialized. */
331   public int getInitialSelectionEnd();
332   
333   /** @return the number of lines in this document. */
334   public int getNumberOfLines();
335   
336   /** Translates an offset into the components text to a line number.
337    *  @param offset the offset >= 0
338    *  @return the line number >= 0 */
339   public int getLineOfOffset(int offset);
340   
341   /** @return the caret position as set by the view. */
342   public int getCaretPosition();
343   
344   /** Creates a WrappedPosition in the document. */
345   public Position   createUnwrappedPosition(int offs) throws BadLocationException  ;
346 }
347
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags