File Type Integration 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:

Diagram.

In this tutorial, you create a module that installs a DataLoader for imaginary "Abc" files (.abc file extension). By default, a file with the "abc" extension 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 Abc 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 Abc 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.

Contents

Content on this page applies to NetBeans IDE 6.0

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:


Creating the Module Project

In this section, we use a wizard to create the source structure that every NetBeans module requires. The source structure consists of certain folders in specific places and a set of files that are always needed. For example, every NetBeans module requires a 'nbproject' folder, which holds the project's metadata, and a layer.xml file, for declarative registration of items such as toolbar buttons and windows.

  1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Modules. Under projects, select Module and click Next.
  2. In the Name and Location panel, type AbcFileType 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:

    Step 1 of New Project wizard.

    Click Next.

  3. In the Basic Module Configuration panel, replace yourorghere in Code Name Base with myorg, so that the whole code name base is org.myorg.abcfiletype. Add spaces to the default Module Display Name, so that it is changed to Abc 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/abcfiletype. The panel should now look as follows:

    Step 2 of New Project wizard.

  4. Click Finish.

The IDE creates the Abc 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:

Initial Projects window.

For basic information on each of the files above, see the Introduction to NetBeans Module Development.


Recognizing Abc Files

In this section, we use a wizard to create the classes necessary for recognizing Abc files as being distinct from all other files. As discussed at the start of this tutorial, we need a data object and a data loader, as well as a MIME type resolver, and registration entries in the layer.xml file, to do so. The New File Type wizard will create all of these for us.

  1. Right-click the project node and choose New > File Type.
  2. In the File Recognition panel, do the following:

    The File Recognition panel should now look as follows:

    Step 1 of New File wizard.

    Note the following about the fields in the File Recognition panel:

    Click Next.

  3. In the Name and Location panel, type Abc as the Class Name Prefix and browse to any 16x16 pixel image file as the new file type's icon, as shown below.

    Step 2 of New File wizard.

    Note:You can use any icon. If you like, you can click on this one and save it locally, and then specify it in the wizard step above: Datasource.gif

  4. Click Finish.

    The Projects window should now look as follows:

    Final Projects window.

Each of the newly generated files is briefly introduced:


Creating Features for Abc Files

Now that the NetBeans Platform is able to distinguish Abc files from all other types of files, it is time to add features specifically for these types of files. In this section, we add a menu item on the right-click contextual menu of the file's node in the explorer windows, such as in the Projects window, and we enable the file to open into a window, instead of into an editor.

Adding an Action

In this subsection, we use the New Action wizard to create a Java class that will perform an action for our file type. The wizard will also register the class in the layer.xml file such that the user will be able to invoke the action from the right-click contextual menu of the file type's node in an explorer window.

  1. Right-click the project node and choose New > Action.
  2. In the Action Type panel, click Conditionally Enabled. Type AbcDataObject, which is the name of the data object generated above by the New File Type wizard, as shown below:

    Step 1 of New Action wizard.

    Click Next.

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

    Step 2 of New Action wizard.

    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.

  4. 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.abcfiletype package.
  5. In the Source Editor, add some code to the action's performAction method:
    protected void performAction(Node[] activatedNodes) {
    	AbcDataObject d = (AbcDataObject) activatedNodes[0].getCookie(AbcDataObject.class);
    	FileObject f = d.getPrimaryFile();
    	String displayName = FileUtil.getFileDisplayName(f);
    	String msg = "I am " + displayName + ". Hear me roar!"; 
            NotifyDescriptor nd = new NotifyDescriptor.Message(msg);
            DialogDisplayer.getDefault().notify(nd);
    }

    Press Ctrl-Shift-I. 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 Ctrl-Shift-I again. The red underlining disappears because the IDE finds the required packages in the Dialogs API.

  6. In the Important Files node, expand XML Layer. The two nodes <this 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.
  7. Drag-and-drop My Action so that it appears below the Open action, as shown below:

    System Filesystem Browser.

    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.

Opening the File into a Window

By default, when the user opens a file of the type that we have defined in this tutorial, the file will open into a basic editor. However, sometimes you may want to create a visual representation of the file, and let the user drag and drop widgets onto the visual representation. The first step in creating such a user interface is to let the user open the file into a window. This subsection shows you how to do that.

  1. Use the Window Component wizard to create a TopComponent called AbcTopComponent.
  2. Change the data object to use OpenSupport instead of DataEditorSupport.

    public AbcDataObject(FileObject pf, AbcDataLoader loader) 
            throws DataObjectExistsException, IOException {
    
        super(pf, loader);
        CookieSet cookies = getCookieSet();
        //cookies.add((Node.Cookie) DataEditorSupport.create(this, getPrimaryEntry(), cookies));
        cookies.add((Node.Cookie) new AbcOpenSupport(getPrimaryEntry()));
                  
    }
  3. Create OpenSupport class:

    class AbcOpenSupport extends OpenSupport implements OpenCookie, CloseCookie {
    
        public AbcOpenSupport(AbcDataObject.Entry entry) {
            super(entry);
        }
    
        protected CloneableTopComponent createCloneableTopComponent() {
            AbcDataObject dobj = (AbcDataObject) entry.getDataObject();
            AbcTopComponent tc = new AbcTopComponent();
            tc.setDisplayName(dobj.getName());
            return tc;
        }
     
    }
  4. Tweak the TopComponent to extend CloneableTopComponent, instead of TopComponent. Set the TopComponent's class modifier, and its constructor's modifier, to public instead of private.

Now, when an Abc file is opened, the OpenSupport class handles the opening, such that it opens the file into the TopComponent instead of the basic editor that DataEditorSupport provides. The NetBeans Visual Library 6.0 Tutorial provides an example of what you can do to develop the TopComponent further.


Installing the Abc File Type 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 Module

Using the NetBeans Module

  1. Create any kind of application in the IDE.
  2. Right-click the application node and choose New > Other. In the Other category, a dummy template is available for the new file type:

    Dummy template.

    If you want to provide default code via the dummy template, add the code to the AbcTemplate.abc file that the New File Type wizard created for you.

  3. Right-click the file's node.

    Notice that the Abc 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:

    Final Projects window.

  4. Choose the new menu item, the Abc file's name and location are shown:

    Information.

Creating a Shareable Plug-in Binary

  1. In the Projects window, right-click the Abc File Type project and choose Create NBM.

    The NBM file is created and you can view it in the Files window (Ctrl-2):

    Shareable NBM.

  2. Make it available to others via, for example, e-mail. The recipient should use the Plugin Manager (Tools > Plugins) to install it.

Send Us Your Feedback

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.
7 17 November 2007
  • Updated the whole tutorial to 6.0, replaced all screenshots, and now [because the 6.0 IDE already provides support for manifest files], the tutorial focuses on imaginary Abc files.
  • To do:
    • Need to replace the download, which is the same as before, dealing with manifest files.
    • Same items as on 4 October still to be done.
    • Added OpenSupport into TopComponent, with a reference to Visual Library.
  • Changed title to File Type Integration Tutorial
  • Tweaked several places throughout tutorial, for 6.0