Eclipse Tip: Define Custom Content Types to Identify Your Data Files
In desktop environments, the typical approach for identifying a file's content is to check its extension. You're familiar with the myriad of three-letter extensions used by the ever-growing number of desktop applications you run across. You also know that at times, the extension "gets it wrong"—even though its name ends in a ".doc", it may not be the text document format you expect.
In the Eclipse Workbench, the traditional approach also has been to assign a unique extension to each unique file format. The editor used to view and edit these files is then bound to that extension. This approach becomes problematic when a generic extension is used to represent an entire family of file formats. For example, the preferred extension for XML files is ".xml" regardless of what kind of data they contain. This way, generic applications capable of viewing XML files can immediately recognize the file as XML. However, this does not work for specialized Eclipse editors built to handle a specific type of XML content.
Defining Content Types
Listing 1: Declaring a content type extension for XML files containing the "apples" element.
<extension point="org.eclipse.core.contenttype.contentTypes"> <content-type base-type="org.eclipse.core.runtime.xml" file-extensions="xml" id="ca.ecliptical.examples.contenttype.apples" name="Apples File" priority="normal"> <describer class="org.eclipse.core.runtime.content .XMLRootElementContentDescriber"> <parameter name="element" value="apples"> </parameter> </describer> </content-type> </extension>
Starting with version 3.0, Eclipse provides a mechanism to programmatically identify file types based on their actual content. The org. eclipse. core. contenttype. contentTypes extension point can be used to define a content type described by a "describer," which is a class capable of recognizing specific types of content given an input stream. Editors designed to work with a specific content type can be bound to it instead of a file extension.
Although it is possible to create and contribute custom content describers, the default ones often will do the job. Eclipse provides a BinarySignatureDescriber, which uses the file's binary signature to identify its content, and a XMLRootElementContentDescriber, which checks an XML document's root element (or its DTD). Both can be parameterized with application-specific values.
Listing 1 illustrates how to define a custom content type to represent XML files whose root element is "apples". See the Resources section for the entire source code for this example.
Note: The content type is narrowed to files whose extension is ".xml". This makes the identification process more efficient—it allows the platform to exclude this content type from consideration for files whose extensions don't match.
Binding Editors to Content Types
Listing 2: Declaring the "ApplesEditor" bound to the "apples" content type.
<extension point="org.eclipse.ui.editors"> <editor name="Apples Editor" icon="icons/sample.gif" contributorClass="org.eclipse.ui.texteditor .BasicTextEditorActionContributor" class="ca.ecliptical.examples.contenttype.apples .ApplesEditor" id="ca.ecliptical.examples.contenttype.apples .ApplesEditor"> <contentTypeBinding contentTypeId="ca.ecliptical.examples.contenttype .apples"> </contentTypeBinding> </editor> </extension>
Once you define a content type for your data format, you can bind the appropriate editor to it. In the attached example, you have two sample XML editors. The ApplesEditor is used for XML files whose root element is "apples"; the OrangesEditor handles XML files with "oranges" in their root. Listing 2 shows an extension declaring the ApplesEditor and binding it to the "apples" content type.
Note: As far as the editors are concerned, the file extension no longer matters. Any file extension binding is relegated to the content type rather than the editor.
When you run the example as an Eclipse application, use the New XML file wizard in the Sample Wizards category to create a new file with either "apples" or "oranges" as its root element. Based on this, the workbench then opens either the ApplesEditor or the OrangesEditor, respectively. Also, when you right-click an XML file in the Resource Navigator, you will see the appropriate default editor in the "Open With" sub-menu.
- Eclipse Platform Plug-in Developer Guide: Content types
- Documentation for the org.eclipse.core.runtime.contentTypes extension point
- Example plug-in source (Eclipse 3.2 project)
About the Author
Peter Nehrer is a software consultant specializing in Eclipse-based enterprise solutions and J2EE applications. He is the founder of Ecliptical Software Inc. and a contributor to several Eclipse-related Open Source projects. He holds an M.S. in Computer Science from the University of Massachusetts at Amherst, MA. Peter can be reached at pnehrer AT eclipticalsoftware DOT com.