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
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. |
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.