IDocumentHandler Interface

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 interfaceIDocumentHandler.IHandlerContext
           This interface is used by the resolveUnknownPriority method to share state information about the document being examined.
public static classIDocumentHandler.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.