DocumentSvc.I Interface

com.bea.ide.document
DocumentSvc.I Interface

public static interface DocumentSvc.I
Enclosing class

DocumentSvc

Method Summary

public IDocumentView
displayDocument(IDocument doc, boolean fActivate)
Displays the given document to the user.
public IDocumentView
displayDocument(IDocument doc)
Displays the given document to the user.
public IDocumentView
displayDocument(IDocument doc, String viewName)
Makes the requested document view object active.
public IDocumentView
displayDocument(IDocument doc, String viewName, INavigationPoint navPoint)
Makes the requested document view active, and select the follow to the requested navigation point.
public IDocumentView
displayDocument(URI uriFile)
Displays the given file to the user.
public URI[]
getDisplayedDocuments()
Obtains an array of all currently open documents.
public URI[]
getDisplayedDocumentsZorder()
Obtains an array of all currently open documents.
public IDocumentInfo
getDocInfo(URI uriFile)
Gets the IDocumentInfo for the given file.
public IDocumentInfo
getDocInfo(String sHandlerId)
Gets the IDocumentInfo for the given document handler.
public IDocument
getDocument(URI uriFile, String sHandlerId)
Opens a file using the specified document handler.
public IDocument
getDocument(URI uriFile)
Opens a file using the default document handler for the file.
public String
getDocumentViewName(IDocument doc, IDocumentView view)
Finds the string name of the given document view.
public IDocument
getExistingDocument(URI uriFile)
Obtains an already existing document for a file.
public IDocumentView
getExistingDocumentView(IDocument doc, String viewName)
Gets a reference to a document view by name.
public URI[]
getOpenDocuments()
Obtains an array of all currently open documents.
public void
hideDocument(IDocument doc)
Closes the document so that it is no longer visible to the user.
public boolean
hideDocumentDialog(IDocument doc)
Closes the document so that it is no longer visible to the user.
public void
hideDocuments(URI[] rguri)
Closes the provided documents so that they are no longer visible to the user.
public void
hideDocumentsDialog(URI[] rguri)
Closes the provided documents so that they are no longer visible to the user.
public boolean
isActiveDocumentView(IDocument doc, String viewName)
Determines if a document view is the currently active view.
public boolean
isDisplayed(IDocument doc)
Determines whether or not a specified document is currently displayed.
public boolean
isDisplayed(URI uriFile)
Determines whether or not a specified URI is currently displayed.
public boolean
isLoaded(URI uriFile)
Returns true if the document is actually loaded in memory.
public boolean
isModified(URI uriFile)
Determines whether or not a specified URI is modified.
public boolean
isValidExtension(String sHandlerId, String sFileExt)
Returns a boolean indicating whether the given extension is valid for the given handler.
public IDocument
newDocument(URI uriName, String sHandlerId)
Creates a new document using the specified handler.
public IDocument
newDocument(URI uriName, String sHandlerId, String sTemplateId)
Creates a new document using the specified handler.
public void
refreshUndoState()
Refreshes the undo state for the currently active view.
public void
replaceDocument(IDocument docOld, IDocument docNew)
Replaces a particular document in the document panel with another document.
public boolean
saveAllDialog()
Saves all documents that have unsaved modifications.
public boolean
saveDocument(IDocument doc)
Saves the document.
public boolean
saveDocumentDialog(IDocument doc)
Saves the document.

Method Detail

displayDocument(IDocument, boolean) Method

public IDocumentView displayDocument(IDocument doc, 
                                     boolean fActivate)
Displays the given document to the user. This document should have been previously opened by a call to DocumentSvc.I.getDocument(URI, String). The document service will instantiate the views of the document if it is not currently visible. The currently active view for the document will either be the last view shown, the first view in it's list (if it was previously not visible). Furthermore, if fActivate is true, it will bring the view to the front and give it the keyboard focus. Note that if this is the only visible document, the fActivate parameter is ignored.

Parameters

doc
Document to display.
fActivate
Boolean indicating whether or not the document view should become the currently active view

Returns

The document being displayed.

displayDocument(IDocument) Method

public IDocumentView displayDocument(IDocument doc)
Displays the given document to the user. This document should have been previously opened by a call to DocumentSvc.I.getDocument(URI, String). The document service will instantiate the views of the document if it is not currently visible. The currently active view for the document will either be the last view shown, the first view in it's list (if it was previously not visible). The view will be brought to the front and given the keyboard focus. This method is equivalent to calling DocumentSvc.I.displayDocument(IDocument, boolean) with fActivate = true.

Parameters

doc
Document to display.

Returns

The document being displayed.

displayDocument(IDocument, String) Method

public IDocumentView displayDocument(IDocument doc, 
                                     String viewName)
Makes the requested document view object active. If there are multiple instances of this view open there is a hierarchy to determine which one is activated and returned -- An instance of the currently active view in the active document panel -- An instance of the currently active view in the non-active document panel -- An instance of an non-active view in the active document panel -- An instance of an non-active view in the non-active document panel

Parameters

doc
Document to display.
viewName
String name of the document view to display

Returns

The document view requested, or null if it does not exist

displayDocument(IDocument, String, INavigationPoint) Method

public IDocumentView displayDocument(IDocument doc, 
                                     String viewName, 
                                     INavigationPoint navPoint)
Makes the requested document view active, and select the follow to the requested navigation point. The navpoint can be anything that the view understands. Also, it doesn't necessarily have to know about the view, since the code tells the view to act on the navpoint. If there are multiple instances of this view open there is a hierarchy to determine which one is activated and returned. See above.

Parameters

doc
Document to display.
viewName
String name of the document view to display
navPoint
is a navigation point appropriate for when the caller doesn't yet have a view pointer.

Returns

The document view requested, or null if it does not exist

displayDocument(URI) Method

public IDocumentView displayDocument(URI uriFile)
Displays the given file to the user. The file will first be opened by the default document handler and then displayed. This is equivalent to first calling DocumentSvc.I.getDocument(URI) and then calling DocumentSvc.I.displayDocument(IDocument). If the file cannot be opened, nothing will be displayed and the method will return null. The document service will obtain the views for the document and either reshow the last view for the document, or show the first view in it's list. If the document is already visible, this will simply bring it to the front and give it the keyboard focus.

Parameters

uriFile
The file that should be opened and displayed.

Returns

The document being displayed or null if the file could not be opened.

getDisplayedDocuments() Method

public URI[] getDisplayedDocuments()
Obtains an array of all currently open documents. This method allows you to obtain all document interfaces that are currently visible in the document panels. The array returned is a snapshot of the system at the time of the call and may change. The array is ordered in the order the documents were opened by the user.

Returns

An Array containing the IDocument interface for each file that is displayed.

getDisplayedDocumentsZorder() Method

public URI[] getDisplayedDocumentsZorder()
Obtains an array of all currently open documents. This method allows you to obtain all document interfaces that are currently visible in the document panels. The array returned is a snapshot of the system at the time of the call and may change. The array is ordered in a most recently used order.

Returns

An Array containing the IDocument interface for each file that is displayed.

getDocInfo(URI) Method

public IDocumentInfo getDocInfo(URI uriFile)
Gets the IDocumentInfo for the given file. This method looks up the handler for the given file and returns its IDocumentInfo interface. If there is no handler registered for the specified file, null is returned.

Parameters

uriFile
The URI for the file to look up

Returns

An IDocumentInfo interface for the specified file or null if there is no handler registered for the file.

getDocInfo(String) Method

public IDocumentInfo getDocInfo(String sHandlerId)
Gets the IDocumentInfo for the given document handler.

Parameters

sHandlerId
The string name of the document handler

Returns

An IDocumentInfo interface for the specified handler.

getDocument(URI, String) Method

public IDocument getDocument(URI uriFile, 
                             String sHandlerId)
Opens a file using the specified document handler. The document handler will be used to create the document interface for the given file. If a document has already been opened, that document is simply returned. Note that a document interface simply creates a programmatic interface to the file. To display a document to the user use DocumentSvc.I.displayDocument(URI).

Parameters

uriFile
The uri for the file to be opened
sHandlerId
The string name of the document handler that should be used to open the file.

Returns

The IDocument interface of the opened document or null if the handler cannot be found or is unable to open the file

getDocument(URI) Method

public IDocument getDocument(URI uriFile)
Opens a file using the default document handler for the file. The document handler will be used to create the document interface for the given file. If a document has already been opened, that document is simply returned. Note that a document interface simply creates a programmatic inteface to the file. To display a document to the user use DocumentSvc.I.displayDocument(URI).

Parameters

uriFile
The uri for the file to be opened

Returns

The IDocument interface of the opened document or null if a handler cannot be found or is unable to open the file

getDocumentViewName(IDocument, IDocumentView) Method

public String getDocumentViewName(IDocument doc, 
                                  IDocumentView view)
Finds the string name of the given document view. One should be able to use this to retrieve the view for a particular document, regardless of whether the document has remained in memory or not.


getExistingDocument(URI) Method

public IDocument getExistingDocument(URI uriFile)
Obtains an already existing document for a file. This method allows you to obtain a document interface for a file only if that file has already been opened. For files that have not been opened, or were garbage collected, this method will return null.

Parameters

uriFile
The uri for the file for which the existing document should be located.

Returns

The IDocument interface of the existing document or null there is no open document.

getExistingDocumentView(IDocument, String) Method

public IDocumentView getExistingDocumentView(IDocument doc, 
                                             String viewName)
Gets a reference to a document view by name. This method will find an existing IDocumentView using the same algorithm outlined above for displayDocument. It will then return the view. This method does not alter the visible state of the document. If the document is not currently displayed, this method will return null.

Parameters

doc
Document to retrieve the view for
viewName
The name of the view, as it is listed in the IDocumentViewInfo of the document

Returns

IDocumentView interface to the specified view, or null if the view name does not exist or the document or the document is not displayed

getOpenDocuments() Method

public URI[] getOpenDocuments()
Obtains an array of all currently open documents. This method allows you to obtain all document interfaces that are currently open within the system. Note that documents may be open even if they are not visible to the user. If you want to get a list of all user visible documents, use DocumentSvc.I.getDisplayedDocuments().

Returns

An Array containing the IDocument interface for each file that is open.

hideDocument(IDocument) Method

public void hideDocument(IDocument doc)
Closes the document so that it is no longer visible to the user. If the document has unsaved modifications, this method will discard the changes. Note that this method does not cause the document object to become unavailable. It simply removes the views from the IDE. When there are no further references to the IDocument, it will be garbage collected automatically. If the given document is not currently visible, this method will simply return.

Parameters

doc
The document to hide

hideDocumentDialog(IDocument) Method

public boolean hideDocumentDialog(IDocument doc)
Closes the document so that it is no longer visible to the user. If the document has unsaved modifications, this method will pop up a dialog requesting action from the user on whether the changes should be discarded. Note that this method does not cause the document object to become unavailable. It simply removes the views from the IDE. When there are no further references to the IDocument, it will be garbage collected automatically. If the given document is not currently visible, this method will simply return.

Parameters

doc
The document to hide

Returns

true to indicate that the file was closed. false if the user cancelled the close.

hideDocuments(URI[]) Method

public void hideDocuments(URI[] rguri)
Closes the provided documents so that they are no longer visible to the user. If the documents have unsaved modifications, this method will discard the changes after hiding the views. Note that this method does not cause the document objects to become unavailable. It simply removes the views from the IDE. When there are no further references to the IDocuments, they will be garbage collected automatically.

Parameters

rguri
Array of uris for the documents that should be hidden

hideDocumentsDialog(URI[]) Method

public void hideDocumentsDialog(URI[] rguri)
Closes the provided documents so that they are no longer visible to the user. If the documents have unsaved modifications, this method will pop up a dialog requesting action from the user on whether the changes should be discarded. Note that this method does not cause the document objects to become unavailable. It simply removes the views from the IDE. When there are no further references to the IDocuments, they will be garbage collected automatically.

Parameters

rguri
Array of uris for the documents that should be hidden

isActiveDocumentView(IDocument, String) Method

public boolean isActiveDocumentView(IDocument doc, 
                                    String viewName)
Determines if a document view is the currently active view. This has the benefit of not forcing the view to be instantiated.

Parameters

doc
The document itself
viewName
The name of the view, as it appears to the user

Returns

Boolean indicating whether the specified view is active

isDisplayed(IDocument) Method

public boolean isDisplayed(IDocument doc)
Determines whether or not a specified document is currently displayed. This method returns the state at the instance of the call. Note that display does not mean it is currently visible, merely that it is in the list of open documents that are visible to the user.

Returns

True if the given document is currently displayed to the user, false otherwise.

isDisplayed(URI) Method

public boolean isDisplayed(URI uriFile)
Determines whether or not a specified URI is currently displayed. This method returns the state at the instance of the call. Note that display does not mean it is currently visible, merely that it is in the list of open documents that are visible to the user.

Returns

True if the given document is displayed to the user, false otherwise.

isLoaded(URI) Method

public boolean isLoaded(URI uriFile)
Returns true if the document is actually loaded in memory. The set of documents that are loaded is a subset of the documents that are open. The document may or may not also be in the visible set. Documents are open but not loaded when they are lazily loaded on startup. They appear in the UI and in lists, but are not physically loaded. Note that it is impossible for a non-loaded document to be dirty. They are by definition unmodified. This method may be used to avoid bringing in a lazily loaded document if the operation on the document can be avoided until the document is in memory.

Parameters

uriFile
The uri for the file that should be checked

Returns

true if the given URI represents an in memory document (obtain via getDocument or getExistingDocument) false if the URI is either not open, or is open, but not yet loaded int memory.

isModified(URI) Method

public boolean isModified(URI uriFile)
Determines whether or not a specified URI is modified. This allows someone to check a file obtained through getDisplayedDocuments(). This method will always return false if the document is not currently in memory.

Parameters

uriFile
The URI of the document to check

Returns

boolean indicating whether or not the URI's in-memory image has changed compared to its backing store

isValidExtension(String, String) Method

public boolean isValidExtension(String sHandlerId, 
                                String sFileExt)
Returns a boolean indicating whether the given extension is valid for the given handler. A true return value does not mean that the given handler is the canonical handler for the extension, merely that it is registered as able to open it.

Parameters

sHandlerId
ID of the handler to check
sFileExt
String representing the file extension (trailing characters after the last .)

Returns

true if the given extension is registered as a valid extension for the given handler, false otherwise.

newDocument(URI, String) Method

public IDocument newDocument(URI uriName, 
                             String sHandlerId)
Creates a new document using the specified handler. This allows the user to create a new file of a specific type. This is identical to calling the three parameter version with null as the sTemplateId value.

Parameters

uriName
The string name of the document handler.

Returns

A new document interface created by the specified handler or null if there was an error.

newDocument(URI, String, String) Method

public IDocument newDocument(URI uriName, 
                             String sHandlerId, 
                             String sTemplateId)
Creates a new document using the specified handler. This allows the user to create a new file of a specific type. The template string is an id that is used to identify to the document any sub-category. The null value may be used for the template ID to indicate the default.

Parameters

uriName
The path to the new file.
sHandlerId
The string name of the document handler.
sTemplateId
A template name known to the handler for specifying template contents

Returns

A new document interface created by the specified handler or null if there was an error.

refreshUndoState() Method

public void refreshUndoState()
Refreshes the undo state for the currently active view. This will force the undo and redo actions to be updated in accordance with the state of the undo manager on the current document.


replaceDocument(IDocument, IDocument) Method

public void replaceDocument(IDocument docOld, 
                            IDocument docNew)
Replaces a particular document in the document panel with another document. Used for save and rename operations where the URI the user is operating on changes

Parameters

docOld
The old document that is being replaced
docNew
The new instance of the document that should be used

saveAllDialog() Method

public boolean saveAllDialog()
Saves all documents that have unsaved modifications. This is an extension of saveDocumentDialog that will attempt to save all documents for which IDocument.isModified() returns true. Note that if the user cancels this operation some of the documents may be saved and some may not.

Returns

Boolean indicating whether all documents were saved.

saveDocument(IDocument) Method

public boolean saveDocument(IDocument doc)
Saves the document. The document's onSave method will be called to verify that it is currently in a state that it may be saved.

Parameters

doc
The document to save

Returns

Boolean indicating whether the document was actually saved. The document may override the save.

saveDocumentDialog(IDocument) Method

public boolean saveDocumentDialog(IDocument doc)
Saves the document. This method differs from DocumentSvc.I.saveDocument(IDocument) in that it may interact with the user if the document cannot be saved. It is intended to be used to respond to user input that indicates the document should be saved.

Parameters

doc
The document to save

Returns

Boolean indicating whether the document was actually saved. The user may cancel the save in some manner