# com.bea.ide.document
IDocumentHandler Interface

public interface IDocumentHandler

This is the basic interface that the document service uses to map a URI to an IDocument interface. Handlers are registered with the IDE at startup using extension xml. See `DocumentSvc``` for more information about the XML to register a document handler. The extension XML used allows the specification of a set or project attributes that can be used to limit the scope of a document handler to specific sets of projects. Attributes may be required by the handler on the project that contains a document it opens. If those attributes are not present, the document handler will not be asked to open the document. For more info on project attributes see `IProject.getProperty(String)``` If there are no project attributes specified, the document handler may be used by any project and also when there is no project specified

All Known Implementing Classes
  `DefaultDocumentHandler`, `ControlDocumentFactory`, `JavaDocumentFactory`

All Known Subinterfaces
  `IRelatedDocumentHandler`, `IVersionedDocumentHandler`

## Nested Class Summary

`public static interface` | `IDocumentHandler.IHandlerContext` This interface is used by the resolveUnknownPriority method to share state information about the document being examined.
`public static class` | `IDocumentHandler.Priority` This class provides a ranking mechanism to allow multiple handlers to negotiate for precedence in opening documents.

## Method Summary

`public `URI`` | `createNewFile`(`URI` uriFile, `String` sTemplateId) Create a new file with the given URI and template id that can be opened by this handler
`public `String`` | `getBaseName`(`String` sFile) Derives the base name for the given file, stripping away all extension and name suffix information.
`public `String`` | `getDefaultExtension`() Returns the default file extension associated with this handler.
`public `String`` | `getHandlerId`() Identifies this handler to the IDE.
`public `String`` | `invalidNameCheck`(`String` sFile) Checks the given filename to see if it is a valid name for this handler.
`public `IDocument`` | `openDocument`(`URI` uriFile) Create a document object representing the given, pre-existing, URI.
`public int` | `resolveUnknownPriority`(`IDocumentHandler.IHandlerContext` hc) This method is called to dynamically resolve the priority of the given file.
`public `String`` | `suggestValidName`(`String` sFile) Examine the given filename and derive a valid filename from it.

## Method Detail

### createNewFile(URI, String) Method

    public URI createNewFile(URI uriFile,
                             String sTemplateId)

Create a new file with the given URI and template id that can be opened by this handler

#### Parameters

uriFile
  The URI that should be given to the new document or, if the template supports a wizard this is simply a hint of a directory in which to create the file. The wizard is responsible for determining the final path and filename.

sTemplateId
  This value is used to hint to the handler what, if any, initial contents the file should have. These are typically values defined in the extension XML for the handler. A null value for sTemplateId is always valid and is considered the default template.

#### Returns

The uri of the file that should be displayed to the user. Note that in some cases multiple files may actually be created, but the URI returned should be the one that should be displayed to the user. If any error occurs, a dialog should be displayed to the user and the null value should be returned.

### getBaseName(String) Method

    public String getBaseName(String sFile)

Derives the base name for the given file, stripping away all extension and name suffix information. Generally, it simply removes the extension, but some handlers may also add a pre-extension suffix to a file. This method strips all of that out to determine the original name.

#### Parameters

sFile
  The filename that should be examined to find the original name. This should not contain any path information (i.e. directory or separators)

#### Returns

The base name that the given name was derived from.

### getDefaultExtension() Method

    public String getDefaultExtension()

Returns the default file extension associated with this handler. This is the file extension that will be used when creating new files for this handler. Although a handler may be associated with multiple extensions, it may have only one default and therefore create only a single extension. Multiple creation extensions require separate document handlers (although they may certainly be trivial derivations of the same base class).

#### Returns

String representing the default extension for this handler. It should not contain the leading "."

### getHandlerId() Method

    public String getHandlerId()

Identifies this handler to the IDE.

#### Returns

The string handler id associated with this handler. This should be the fully-qualified class name of the object that implements the interface as declared in the XML.

### invalidNameCheck(String) Method

    public String invalidNameCheck(String sFile)

Checks the given filename to see if it is a valid name for this handler. This check may include verification of the extension and any other requirements on the filename. For example, the java handler can require that the filename be a valid java identifier.

#### Parameters

sFile
  The filename that should be examined for validity. This should not contain any path information (i.e. directory or separators).

#### Returns

String value indicating the error message that should be shown to the user or null if the name is valid.

### openDocument(URI) Method

    public IDocument openDocument(URI uriFile)

Create a document object representing the given, pre-existing, URI.

#### Parameters

uriFile
  The URI describing the location of the data for the document to be instatiated.

#### Returns

A new instance of a document object representing the existing file. If the file does not exist, cannot be read or is otherwise invalid, a dialog should be displayed to the user and the null value should be returned.

### resolveUnknownPriority(IDocumentHandler.IHandlerContext) Method

    public int resolveUnknownPriority(IDocumentHandler.IHandlerContext hc)

This method is called to dynamically resolve the priority of the given file. Only file extensions registered as priority="unknown" will cause this method to be invoked.

#### Parameters

hc
  the handler context for caching information about the file

#### Returns

an integer value from the class `IDocumentHandler.Priority``` other than UNKNOWN. For this method, returning the value UNKNOWN is an error since no resolution has occurred.

### suggestValidName(String) Method

    public String suggestValidName(String sFile)

Examine the given filename and derive a valid filename from it. This method differs from `IDocumentHandler.invalidNameCheck(String)``` in that rather than returning an error, it will attempt to address any invalid characters in the name and correct them. An example is an implementation that replaces spaces with '_' in a handler that does not allow spaces.

#### Parameters

sFile
  The filename that should be examined for validity. This should not contain any path information (i.e. directory or separators).

#### Returns

A valid filename for which invalidNameCheck will return null, indicating a valid name.