Document Extension XML Reference

Describes a document extension, with which you add to the IDE support for new document types. As with JWS, JAVA, JSP, and other types, new types may require specific user interface (such as an icon) and behavior. The extension.xml file for a document extension specifies the class to use for handling this type of document, the document's file extension, and so on.

Note: The <extension-xml> element is the root for any extension descriptor. For this kind of extension, the <extension-xml> element's id attribute value must be "urn:com-bea-ide:document".

<extension-xml>
    <document-handler>
        <file-extension>
        <create-template>
            <description>
        <project-attributes>
            <requires>
    <file-extension>

See the DocumentSvc class for more information on implementing document extensions.

<document-handler> Element

Specifies a document handler.

<extension-xml>
<document-handler>

Syntax

<document-handler 
    class="handlerClassName" 
    icon="pathToIcon" 
    label="descriptiveTextForDocumentType"
>

Attributes

Attribute	Description
class	Required string. The fully-qualified name of the handler class for this document type. The specified class must implement the IDocumentHandler interface.
icon	Required string. Path to the image that should be used to represent this file type. This will be used, for example, to allow the Application window to display an image next to the file name.
label	Required string. A plain text description of this file type. This will be used as explanatory text where appropriate.

Remarks

The <document-handler> element may have one or more <file-extension> child elements. These are used to associate a document handler with a particular file-name pattern for parsing. Currently, the text inside this tag is expected to come at the end of the file following a ".".

Hierarchy

Parents: <extension-xml>.

Children: <file-extension>, <create-template>, <project-attributes>.

<file-extension> Element

Specifies the extension of a file for which this document handler may be used.

<extension-xml>
<document-handler>
<file-extension>

Syntax

<file-extension
    priority="prioritySetting"
    [handler="handlerName"] 
>

Attributes

Attribute	Description
priority	Required enumeration. The ranking of the handler for this file extension. Possible values are described below.
handler	Optional string.

Remarks

This priority attribute captures a relative ranking of how well the handler understands this particular extension. The document service uses this to find a default handler for a given file extension. It will choose the handler with the highest priority. In the event of a tie (this should be avoided), one of the handlers with the highest priority will be arbitrarily chosen. Valid priority values are (from lowest to highest priority):

You will most often implement "highest" priority handlers, but you may also have "low" and "medium" priority handlers. For example, the extension .java should have a high priority handler that handles JAVA files. However, the extension .jws is also a JAVA file. In the absence of a "highest" priority handler for it (in other words, the web services extension), the JAVA file handler should be able to also handle JWS files. Therefore, the JAVA file handler may declare itself to be a "low" priority handler for files with a .jws extension.

Finally, the "unknown" priority value indicates that the handler must actually inspect the contents of the file in order to determine what priority it actually has. An example here would be a Dialog editor that understands files JAVA files, but only if the class extends the JDialog class. If no "highest" handler is available for a file at run time, "unknown" handlers will be given the opportunity to inspect the file and return one of the six more specific priority values. The highest priority among the "unknown" type handlers and any remaining non-"highest" handlers will be designated as the default handler for a file.

For more information, see IDocumentHandler.Priority.

Hierarchy

Parents: <document-handler>.

Children: None.

<create-template> Element

Specifies information used in the right-click menu and New File dialog when creating a new file of this type.

<extension-xml>
<document-handler>
<create-template>

Syntax

<create-template
    [id="id"]
    priority="priorityNumber"
    [createCategories="fileCategories"]
    [label="descriptiveText"] 
>

Attributes

Attribute	Description
priority	Required int. A number indicating this handler's ranking for this file type.
label	Optional string. A plain text description of this file type. This will be used as explanatory text where appropriate.
createCategories	Optional string. Categories in the New File dialog under which this file type will appear. Make this value "ShortCut" to specify that the file type should appear on the right-click menu.
id	Optional string.

Hierarchy

Parents: <document-handler>.

Children: <description>.

<project-attributes> Element

<extension-xml>
<document-handler>
<project-attributes>

Syntax

<project-attributes>
    <requires name="attributeName" value="true | false"/>
</project-attributes>

Hierarchy

Parents: <document-handler>.

Children: <requires>.

<requires> Element

<extension-xml>
    <document-handler>
        <project-attributes>
            <requires>

Syntax

<requires name="attributeName" value="true | false"/>

Hierarchy

Parents: <project-attributes>.

Children: None.

<description> Element

Specifies the text that should appear for this file type in the New File dialog.

<extension-xml>
    <document-handler>
        <create-template>
            <description>

Syntax

<description>Description text that appears for file type in the New File dialog.</project-attributes>

Hierarchy

Parents: <create-template>.

Children: None.