001: /*BEGIN_COPYRIGHT_BLOCK
002: *
003: * Copyright (c) 2001-2007, JavaPLT group at Rice University (javaplt@rice.edu)
004: * All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions are met:
008: * * Redistributions of source code must retain the above copyright
009: * notice, this list of conditions and the following disclaimer.
010: * * Redistributions in binary form must reproduce the above copyright
011: * notice, this list of conditions and the following disclaimer in the
012: * documentation and/or other materials provided with the distribution.
013: * * Neither the names of DrJava, the JavaPLT group, Rice University, nor the
014: * names of its contributors may be used to endorse or promote products
015: * derived from this software without specific prior written permission.
016: *
017: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
018: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
019: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
020: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
021: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
022: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
023: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
024: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
025: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
026: * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
027: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
028: *
029: * This software is Open Source Initiative approved Open Source Software.
030: * Open Source Initative Approved is a trademark of the Open Source Initiative.
031: *
032: * This file is part of DrJava. Download the current version of this project
033: * from http://www.drjava.org/ or http://sourceforge.net/projects/drjava/
034: *
035: * END_COPYRIGHT_BLOCK*/
036:
037: package edu.rice.cs.drjava.model;
038:
039: import java.util.Vector;
040: import java.util.List;
041: import java.io.*;
042: import java.awt.print.*;
043: import javax.swing.event.DocumentListener;
044: import javax.swing.event.UndoableEditListener;
045: import javax.swing.text.BadLocationException;
046: import javax.swing.text.Position;
047:
048: import edu.rice.cs.util.FileOpenSelector;
049: import edu.rice.cs.drjava.model.FileSaveSelector;
050: import edu.rice.cs.util.docnavigation.*;
051: import edu.rice.cs.util.text.AbstractDocumentInterface;
052: import edu.rice.cs.drjava.model.debug.Breakpoint;
053: import edu.rice.cs.drjava.model.Finalizable;
054: import edu.rice.cs.drjava.model.definitions.*;
055:
056: /**
057: * Interface for the GlobalModel's handler of an open
058: * DefinitionsDocument. Provides a means to interact with
059: * the document.
060: *
061: * @version $Id: OpenDefinitionsDocument.java 4255 2007-08-28 19:17:37Z mgricken $
062: */
063: public interface OpenDefinitionsDocument extends DJDocument,
064: Finalizable<DefinitionsDocument>,
065: Comparable<OpenDefinitionsDocument>, INavigatorItem {
066:
067: //----- Forwarding Methods -----/
068:
069: /** The following methods are forwarding methods required by the rest of the program in order for the
070: * OpenDefinitionsDocument to handle DefinitionsDocuments */
071: public int id();
072:
073: public int commentLines(int selStart, int selEnd);
074:
075: public int uncommentLines(int selStart, int selEnd);
076:
077: public boolean getClassFileInSync();
078:
079: public void setClassFileInSync(boolean val);
080:
081: public int getCurrentLine();
082:
083: public int getCurrentCol();
084:
085: public int getOffset(int lineNum);
086:
087: public String getQualifiedClassName()
088: throws ClassNameNotFoundException;
089:
090: public String getQualifiedClassName(int pos)
091: throws ClassNameNotFoundException;
092:
093: public CompoundUndoManager getUndoManager();
094:
095: public void resetUndoManager();
096:
097: public File getCachedClassFile();
098:
099: public void setCachedClassFile(File f);
100:
101: public DocumentListener[] getDocumentListeners();
102:
103: public UndoableEditListener[] getUndoableEditListeners();
104:
105: //----- Regular methods -----/
106:
107: //----- Getters and Setters -----/
108:
109: /** Returns the file for this document; does not check whether the file exists. */
110: public File getRawFile();
111:
112: /** Returns the file for this document.
113: * @return the file for this document
114: * @throws FileMovedException if the document's file no longer exists
115: */
116: public File getFile() throws FileMovedException;
117:
118: /** Sets this document's file
119: * @param file the file that this OpenDefinitionsDocument is associated with
120: */
121: public void setFile(File file);
122:
123: /** Returns the name of this file, or "(Untitled)" if no file. */
124: public String getFileName();
125:
126: /** Returns canonical path for well-formed file, "(Untitled)" if no file exists, and absolute path if ill-formed. */
127: public String getCanonicalPath();
128:
129: /** Returns canonical path (as defined above) followed by " *" if modified. */
130: public String getCompletePath();
131:
132: /** Returns the parent directory of this file, null if it has none. */
133: public File getParentDirectory();
134:
135: public Pageable getPageable() throws IllegalStateException;
136:
137: //----- Simple Predicates -----//
138:
139: /** @return whether the undo manager can perform any undos. */
140: public boolean undoManagerCanUndo();
141:
142: /** @return whether the undo manager can perform any redos. */
143: public boolean undoManagerCanRedo();
144:
145: /** Determines if this document in the file system tree below the active project root. */
146: public boolean inProjectPath();
147:
148: /** Determines if this document in the file system tree below the specified root. */
149: public boolean inNewProjectPath(File root);
150:
151: /** Determines if the document is empty. */
152: public boolean isEmpty();
153:
154: /** @return true if the document's file is a project auxiliary file. */
155: public boolean isAuxiliaryFile();
156:
157: /** @return true if the document's filename ends with the extension ".java", ".dj0", "dj1", or "dj2". */
158: public boolean isSourceFile();
159:
160: /** @return true if the documents file is saved in the current project file. */
161: public boolean inProject();
162:
163: /** Returns whether this document is resident in memory. */
164: public boolean isReady();
165:
166: /** Returns whether this document is currently untitled (indicating whether it has a file yet or not).
167: * @return true if the document is untitled and has no file
168: */
169: public boolean isUntitled();
170:
171: /** Returns true if the file exists on disk, or if the user has located it on disk. Returns false if the
172: * file has been moved or deleted
173: */
174: public boolean fileExists();
175:
176: /** Determines if this definitions document has changed since the last save.
177: * @return true if the document has been modified
178: */
179: public boolean modifiedOnDisk();
180:
181: /** Resets the document to be unmodified. */
182: public void resetModification();
183:
184: /** Returns the date that this document was last modified. */
185: public long getTimestamp();
186:
187: //----- Major Operations -----//
188: /** Returns the name of the top level class, if any.
189: * @throws ClassNameNotFoundException if no top level class name found.
190: */
191: public String getFirstTopLevelClassName()
192: throws ClassNameNotFoundException;
193:
194: /** If the file exists, returns true. If it does not exist, prompts the user to look it up. If the user
195: * chooses a file, returns true, false otherwise. */
196: public boolean verifyExists();
197:
198: /** Saves the document with a FileWriter. If the file name is already set, the method will use that name
199: * instead of whatever selector is passed in.
200: * @param com a selector that picks the file name
201: * @exception IOException
202: * @return true if the file was saved, false if the operation was canceled
203: */
204: public boolean saveFile(FileSaveSelector com) throws IOException;
205:
206: /** Revert the document to the version saved on disk. */
207: public void revertFile() throws IOException;
208:
209: /** Saves the document with a FileWriter. The FileSaveSelector will either provide a file name or prompt
210: * the user for one. It is up to the caller to decide what needs to be done to choose a file to save to.
211: * Once the file has been saved succssfully, this method fires fileSave(File). If the save fails for any
212: * reason, the event is not fired.
213: * @param com a selector that picks the file name.
214: * @exception IOException
215: * @return true if the file was saved, false if the operation was canceled
216: */
217: public boolean saveFileAs(FileSaveSelector com) throws IOException;
218:
219: /** Starts compiling the source. Demands that the definitions be saved before proceeding with the compile.
220: * Fires the appropriate events as the compiliation proceeds and finishes.
221: * @exception IOException if a file with errors cannot be opened
222: */
223: public void startCompile() throws IOException;
224:
225: /** Runs the main method in this document in the interactions pane. Demands that the definitions be saved
226: * and compiled before proceeding. Fires an event to signal when execution is about to begin.
227: * @exception ClassNameNotFoundException propagated from getFirstTopLevelClass()
228: * @exception IOException propagated from GlobalModel.compileAll()
229: */
230: public void runMain() throws ClassNameNotFoundException,
231: IOException;
232:
233: /** Starts testing the source using JUnit. Demands that the definitions be saved and compiled before proceeding
234: * with testing. Fires the appropriate events as the testing proceeds and finishes.
235: * TODO: this method is redundant and should be deprecated
236: * @exception IOException if a file with errors cannot be opened
237: * @exception ClassNotFoundException when the class is compiled to a location not on the classpath.
238: */
239: public void startJUnit() throws ClassNotFoundException, IOException;
240:
241: /** Generates Javadoc for this document, saving the output to a temporary directory. The location is provided
242: * to the javadocEnded event on the given listener.
243: * @param saver FileSaveSelector for saving the file if it needs to be saved
244: */
245: public void generateJavadoc(FileSaveSelector saver)
246: throws IOException;
247:
248: /** Determines if this definitions document has changed since the last save.
249: * @return true if the document has been modified
250: */
251: public boolean isModifiedSinceSave();
252:
253: /** Asks the GlobalModel if it can revert current definitions to version on disk. If ok, it reverts the file
254: * to the version on disk.
255: * @return true if the document has been reverted
256: */
257: public boolean revertIfModifiedOnDisk() throws IOException;
258:
259: /** Returns whether the GlobalModel can abandon this document, asking listeners if isModifiedSinceSave() is true.
260: * @return true if this document can be abandoned
261: */
262: public boolean canAbandonFile();
263:
264: /** Saves file at user's discretion before quitting.
265: * @return true if quitting should continue, false if the user cancelled */
266: public boolean quitFile();
267:
268: /** Moves the definitions document to the given line, and returns the resulting character position.
269: * @param line Destination line number. If line exceeds the number of lines in the document, it is interpreted
270: * as the last line.
271: * @return Index into document of where it moved
272: */
273: public int gotoLine(int line);
274:
275: /** Finds the root directory of the source files.
276: * @return The root directory of the source files, based on the package statement.
277: * @throws InvalidPackageException If the package statement is invalid, or if it does not match
278: * up with the location of the source file.
279: */
280: public File getSourceRoot() throws InvalidPackageException;
281:
282: /** @return the name of the package currently embedded in document. Forwards to wrapped DefinitionsDocument. */
283: public String getPackageNameFromDocument();
284:
285: /** @return the name of the package at the time of the most recent save or load operation. */
286: public String getPackageName();
287:
288: /** Sets the cached package name returned by getPackageName(); */
289: public void setPackage(String s);
290:
291: /** Searching backwards finds the name of the enclosing named class or interface. NB: ignores comments.
292: * WARNING: In long source files and when contained in anonymous inner classes, this function might take a LONG time.
293: * @param pos Position to start from
294: * @param qual true to find the fully qualified class name
295: * @return name of the enclosing named class or interface
296: */
297: public String getEnclosingClassName(int pos, boolean qual)
298: throws BadLocationException, ClassNameNotFoundException;
299:
300: public void preparePrintJob() throws BadLocationException,
301: FileMovedException;
302:
303: public void print() throws PrinterException, BadLocationException,
304: FileMovedException;
305:
306: public void cleanUpPrintJob();
307:
308: /** Checks if the document is modified. If not, searches for the class file
309: * corresponding to this document and compares the timestamps of the
310: * class file to that of the source file.
311: * @return is the class file and this OpenDefinitionsDocument are in sync
312: */
313: public boolean checkIfClassFileInSync();
314:
315: /** Called when this document is saved so it can notify the cache. */
316: public void documentSaved();
317:
318: /** Called when this document is modified so it can notify the cache. */
319: public void documentModified();
320:
321: /** Called when this document is reset so it can notify the cache. */
322: public void documentReset();
323:
324: /** @return the breakpoint region manager. */
325: public RegionManager<Breakpoint> getBreakpointManager();
326:
327: /** @return the bookmark region manager. */
328: public RegionManager<DocumentRegion> getBookmarkManager();
329:
330: /** @return managers for find result regions. */
331: public List<RegionManager<MovingDocumentRegion>> getFindResultsManagers();
332:
333: /** Add a region manager for find results to this document.
334: * @param rm the global model's region manager */
335: public void addFindResultsManager(
336: RegionManager<MovingDocumentRegion> rm);
337:
338: /** Remove a manager for find results from this document.
339: * @param rm the global model's region manager. */
340: public void removeFindResultsManager(
341: RegionManager<MovingDocumentRegion> rm);
342:
343: /** @return manager for browser history regions. */
344: public RegionManager<DocumentRegion> getBrowserHistoryManager();
345:
346: /** Called when this document is being closed, removing related state from the debug manager. */
347: public void removeFromDebugger();
348:
349: /** Sets the document as modified. */
350: public void updateModifiedSinceSave();
351:
352: /** Should be called when closing an ODD to let the ODD clean up after itself. */
353: public void close();
354:
355: /** @return the initial vertical scroll the pane should use when initialized. */
356: public int getInitialVerticalScroll();
357:
358: /** @return the initial vertical scroll the pane should use when initialized. */
359: public int getInitialHorizontalScroll();
360:
361: /** @return the starting location of the cursor selection that should be set in the pane when initialized. */
362: public int getInitialSelectionStart();
363:
364: /** @return the final location of the cursor selection that should be set in the pane when it is initialized. */
365: public int getInitialSelectionEnd();
366:
367: /** @return the number of lines in this document. */
368: public int getNumberOfLines();
369:
370: /** Translates an offset into the components text to a line number.
371: * @param offset the offset >= 0
372: * @return the line number >= 0 */
373: public int getLineOfOffset(int offset);
374:
375: /** Translates a line number into an offset.
376: * @param line number >= 0
377: * @return offset >= 0
378: */
379: public int getOffsetOfLine(int line);
380:
381: /** @return the caret position as set by the view. */
382: public int getCaretPosition();
383:
384: /** Creates a WrappedPosition in the document. */
385: public Position createUnwrappedPosition(int offs)
386: throws BadLocationException;
387: }
|