Recognizing a File Type Tutorial
This tutorial shows you how to write a module that lets the IDE (or any other application built on the NetBeans Platform) recognize a new file type.
File types that are recognized in the IDE have their own icons, menu items, and behavior. The "files" being shown are FileObjects—wrappers
around java.io.File or, in the case of configuration files, typically wrappers around data stored in some other way,
such as inside XML files in modules. What you actually see are Nodes, which provide functionality like actions
and localized names to objects like files. In between Nodes and FileObjects are DataObjects.
A DataObject is like a FileObject, except that it knows what kind of file is being shown, and there are
usually different types of DataObject for files with different extensions and XML files with different namespaces.
Each DataObject is provided by a different module, each implementing support for one or more file types—for example,
the Image module makes it possible to recognize and open .gif and .png files.
A module that recognizes a file type installs a DataLoader—a factory for a file-type-specific DataObject.
When a folder is expanded, the IDE asks each known DataLoader, "Do you know what this is?" The first one that says
"Yes" creates the DataObject for the file. In order to actually display something for each file, the system calls
DataObject.getNodeDelegate() for each DataObject and the Nodes are what you actually see in the IDE.
Below, the diagram on the left shows what each item mentioned above makes available; the
diagram on the right shows the relationship between them:
In this tutorial, you create a module that installs a DataLoader for JAR manifest files
(.mf extension). By default, a manifest file is treated as any other file that
the IDE does not recognize—it is treated as a text file and, as a result, the IDE provides the same functionality for
manifest files as it does for text files. Once you have created the module, you will be shown how to enhance it
with functionality that will be available to manifest files only. When you complete the development cycle, you can easily let others make use of
your module—the IDE lets you create a binary that you can send to others, who can then install it through the
Update Center.
The following topics are covered below:
Once the software is installed, this tutorial can be completed in 30 minutes.
For more information on working with NetBeans modules, see the
NetBeans Development Project home on the NetBeans website. If you have questions, visit the
NetBeans Developer FAQ or use the feedback link
at the top of this page.
Installing the Software
Before you begin, you need to install the following software on your
computer:
Installing the Sample
Take the following steps to install the sample:
- Unzip the attached file.
- In the IDE, choose File > Open Project and browse to the folder that contains the unzipped file.
Open the module project. It should look as follows:
- Right-click the project node and choose Install/Reload in Target Platform. The target
platform opens and the module is installed.
- Use the New Project wizard (Ctrl-Shift-N) to create a Java application and notice that its
manifest file has a different icon and that its pop-up menu has a new item. Choose the pop-up menu item
and observe the result.
Creating the Module Project
- Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Plug-in Modules. Under projects,
select Module Project and click Next.
- In the Name and Location panel, type ManifestFileType in Project Name.
Change the
Project Location to any directory on your computer, such as c:\mymodules. Leave the Standalone Module radiobutton
selected. The panel should now look as follows:
Click Next.
- In the Basic Module Configuration panel, replace yourorghere in Code Name Base with myorg,
so that the whole code name base is org.myorg.manifestfiletype.
Add spaces to the default Module Display Name, so that it is changed to Manifest File Type.
Leave the location of the localizing bundle and XML layer, so that they will be stored in a
package with the name org/myorg/manifestfiletype. The panel should now look as follows:
- Click Finish.
The IDE creates the Manifest File Type
project. The project contains all of your sources and
project metadata, such as the project's Ant build script. The project
opens in the IDE. You can view its logical structure in the Projects window (Ctrl-1) and its
file structure in the Files window (Ctrl-2). For example, the Projects window should now look as follows:
For basic information on each of the files above, see the
Introduction to NetBeans Module Development.
Recognizing Manifest Files
- Right-click the project node and
choose New > File Type. Click Next.
- In the File Recognition panel, do the following:
- Type text/x-java-jar-manifest in the MIME Type edit box.
- Type .mf .MF in the by Filename Extension edit box.
The File Recognition panel should now look as follows:
Note the following about the fields in the File Recognition panel:
- MIME Type. Specifies the data object's unique MIME type.
- by
Click Next.
- In the Name and Location panel, type Manifest as the Class Name Prefix
and browse to any 16x16 pixel image file as the new file type's icon, as shown below.
Note that several
16x16 pixel image files are found within your NetBeans installation directory, for example, in this
location:
enterprise2\jakarta-tomcat-5.5.7\server\webapps\admin\images.
For purposes of this tutorial, the Datasource.gif image in the above directory is used.
This is what it looks like: 
- Click Finish.
The Projects window should now look as follows:
Each of the newly generated files is briefly introduced:
- ManifestDataLoader.java. Recognizes the text/x-java-jar-manifest MIME type. Functions as a factory for
ManifestDataObject.java. For more information, see What is a DataLoader?.
- ManifestResolver.xml. Maps the .mf and .MF extensions to the MIME type. The ManifestDataLoader only
recognizes the MIME type; it does not know about the file extension.
- ManifestDataObject.java. Wraps a FileObject. DataObjects are produced by DataLoaders.
For more information, see What is a DataObject?.
- ManifestDataNode.java. Provides what you see in the IDE—functionality like actions, icons, and localized names.
- ManifestDataLoaderBeanInfo.java. Controls the appearance of the loader in the Object Types section
of the Options window.
Adding Functionality for Manifest Files
Adding an Action
- Right-click the project node and
choose New > Action. Click Next.
- In the Action Type panel, click Conditionally Enabled. Type ManifestDataObject, which
is the name of the data object generated above by the New File Type wizard, as shown below:
Click Next.
- In the GUI Registration panel, select the 'Edit' category in the Category drop-down list.
The Category drop-down list controls where an action is shown in the Keyboard Shortcuts editor in the IDE.
Next, Unselect Global Menu Item and then select File Type Contect Menu Item.
In the Content Type drop-down list, select the MIME type you specified above in the New File Type
wizard, as shown below:
Notice that you can set the position of the menu item and that you
can separate the menu item from the item before it and after it. Click Next.
- In the Name and Location panel, type MyAction as the Class Name
and type My Action as the Display Name. Menu items provided by contextual menus
do not display icons. Therefore, click Finish and MyAction.java is added to the org.myorg.manifestfiletype package.
- In the Source Editor, add some code to the action's performAction method:
protected void performAction(Node[] activatedNodes) {
ManifestDataObject d = (ManifestDataObject) activatedNodes[0].getCookie(ManifestDataObject.class);
FileObject f = d.getPrimaryFile();
String displayName = FileUtil.getFileDisplayName(f);
String msg = "I am " + displayName + "!";
NotifyDescriptor nd = new NotifyDescriptor.Message(msg);
DialogDisplayer.getDefault().notify(nd);
}
Press Alt-Shift-F. The IDE automatically adds import statements to the top of the class. Some code
is still underlined in red, to indicate that not all of the required packages are on the classpath.
Right-click the project node, choose Properties, and click Libraries in the Project Properties dialog box.
Click add at the top of the Libraries pane and add the Dialogs API.
In the MyAction.java class, press Alt-Shift-F again. The red underlining disappears because
the IDE finds the required packages in the Dialogs API.
- In the Important Files node, expand XML Layer. The two nodes <xml layer> and <this layer in context>,
together with their subnodes, make up the System Filesystem Browser. Expand <this layer>, expand Loaders,
continue expanding nodes until you see the Action that you created above.
- Drag-and-drop My Action so that it appears below the Open action, as shown below:
As you can see from the last two steps, the System Filesystem Browser can be used to quickly reorganize
the sequence of the items that are registered in the System Filesystem.
Installing the Manifest File DataLoader Module
The IDE uses an Ant build script to build and install your module. The build script is created for you
when you create the project.
Installing the NetBeans Plug-in
Using the NetBeans Plug-in
- Create a new module project.
- Expand the Important Files node.
Notice that the Module Manifest file has the icon
you assigned to it in its module and that the list of actions defined in its layer.xml file
is available from the right-click contextual menu:
- Choose the new menu item, the manifest file's name and location are shown:
- Right-click the new module project node and choose New > File/Folder. In the Other
category, a dummy template is available for the new file type:
If you want to provide default code via the dummy template, add the code to the
ManifestTemplate.mf file that the New File Type wizard created for you.
Creating a Shareable Plug-in Binary
- In the Projects window, right-click the Manifest File Type project and choose Create NBM.
The NBM file is created and you can view it in the Files window (Ctrl-2):
- Make it available to others via, for example, e-mail. The recipient should
use the Update Center (Tools > Module Manager) to install it.
Further Enhancements
Some functionality you might want to add:
Next Steps
For more information about creating and developing NetBeans modules, see the following resources:
Versioning
|
Version
|
Date
|
Changes
|
|
1
|
25 August 2005
|
- Initial version.
- To do:
- Add post-creation customizations (i.e., the "Extending Support for the New File Type" section).
- Explain what the generated files are for (placeholders currently).
- Explain the layer file's entries.
- Explain the first File Type panel (placeholders currently).
- Maybe create a separate tutorial for recognizing XML files.
|
|
2
|
23 September 2005
|
- A lot of info added from the FAQ and added the Action wizard and System Filesystem Browser.
- To do:
- Explain LoaderBeanInfo.java and Resolver.xml (one line each)
- Maybe create a separate tutorial for recognizing XML files.
- Using Tomcat GIF maybe not good idea.
- Maybe the action should do something useful.
- Maybe direct links to FAQ not good idea.
- Probably more needed on layer.xml file.
- Maybe other useful apisupport functionality could be added to this scenario.
- More info needed on MIME types.
- The introductory paragraphs should be illustrated with a graphic. A diagram to
show relationship between node, dataobject, fileobject, dataloader, etc.
|
|
3
|
28 September 2005
|
- Integrated comments from Jesse Glick.
- To do:
- More info needed on MIME types.
- The introductory paragraphs should be illustrated with a graphic. A diagram to
show relationship between node, dataobject, fileobject, dataloader, etc.
- Many Javadoc links to be added (also for performAction.
- Info on cookies, cookie actions, cookie classes needed.
- Action ended up in text-html even though I chose my own mime type.
- Need to explain or link to explanation for instance, shadow, etc.
- Platform Manager needs to be mentioned in the context of installing
in target platform.
- Show how to add properties to the property sheet.
|
|
4
|
4 October 2005
|
- Added two diagrams in the introductory paragraphs, from Tim Boudreau's JavaOne presentation.
- To do:
- More info needed on MIME types.
- Many Javadoc links to be added (also for performAction).
- Need to create section near the start: "Related FAQs":
- Info on cookies, cookie actions, cookie classes needed.
- Need to explain or link to explanation for instance, shadow, etc.
- DataLoader, DataObject, etc.
- Platform Manager needs to be mentioned in the context of installing
in target platform.
- Show how to add properties to the property sheet.
- Mention the dummy template that you get, how to modify it,
and how to set the description in the New File wizard.
|
|
4
|
4 November 2005
|
- Added downloadable source code, new 'Installing the Sample' section, and link to
Syntax Highlighting tutorial at the end.
- To do:
- Same items as on 4 October still to be done.
|
|
5
|
29 November 2005
|
- Added links to brand new Component Palette tutorial.
- To do:
- Same items as on 4 October still to be done.
|
|
6
|
21 April 2006
|
- Changed the title from "DataLoader Module Tutorial" to "Recognizing a File Type Tutorial".
- To do:
- Same items as on 4 October still to be done.
|
|
|
