# 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