netbeans.apache.org/src/old_content/content/tutorials/60/nbm-filetype.adoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= File Type Integration Tutorial
:jbake-type: platform_tutorial
:jbake-tags: tutorials 
:jbake-status: published
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:icons: font
:experimental:
:description: File Type Integration Tutorial - Apache NetBeans
:keywords: Apache NetBeans Platform, Platform Tutorials, 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.

NOTE: This is not the latest version of this document. It applies to NetBeans IDE 6.0/6.1 only.  link:../nbm-filetype.html[Click here] to see the most up to date version.









== Introduction to File Type Integration

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:


image::images/filetype_diagram-dataobject2.png[]

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.


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


[start=1]
1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Modules. Under projects, select Module and click Next.

[start=2]
1. 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:


image::images/filetype_60-projectwizard1.png[]

Click Next.


[start=3]
1. 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:


image::images/filetype_60-projectwizard2.png[]


[start=4]
1. 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:


image::images/filetype_60-projectswindow1.png[] 


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


[start=1]
1. Right-click the project node and choose New > File Type.

[start=2]
1. In the File Recognition panel, do the following:

* Type  ``text/x-abc``  in the MIME Type edit box.
* Type  ``.abc .ABC``  in the by Filename Extension edit box.

The File Recognition panel should now look as follows:


image::images/filetype_60-filewizard1.png[]

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

* *MIME Type.* Specifies the data object's unique MIME type.
* by
* *Filename Extension.* Specifies one or more file extensions that the IDE will recognize as belonging to the specified MIME type. The file extension can optionally be preceded by a dot. Separators are commas, spaces, or both. Therefore, all of the following are valid:

*  ``.abc,.def`` 
*  ``.abc .def`` 
*  ``abc def`` 
*  ``abc,.def ghi, .wow`` 

Let's imagine that Abc files be case-sensitive. For this reason, you specify _two_ MIME types in this tutorial— ``.abc``  and  ``.ABC`` .

* *XML Root Element.* Specifies a unique namespace that distinguishes the XML file type from all other XML file types. Since many XML files have the same extension ( ``xml`` ), the IDE distinguishes between XML files via their XML root elements. More specifically, the IDE can distinguish between namespaces and the first XML element in XML files. You can use this to, for example, distinguish between a JBoss deployment descriptor and a WebLogic deployment descriptor. Once you have made this distinction, you can ensure that menu items added to the JBoss deployment descriptor's contextual menu are not available to the WebLogic deployment descriptor. For an example, see the  link:nbm-palette-api2.html[NetBeans Component Palette Module Tutorial].

Click Next.


[start=3]
1. 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.


image::images/filetype_60-filewizard2.png[]

*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: 
image::images/filetype_Datasource.gif[]


[start=4]
1. Click Finish.

The Projects window should now look as follows:


image::images/filetype_60-projectswindow2.png[]

Each of the newly generated files is briefly introduced:

* *AbcDataLoader.java.* Recognizes the  ``text/x-abc``  MIME type. Functions as a factory for  ``AbcDataObject.java`` . For more information, see  link:http://wiki.netbeans.org/wiki/view/Netbeans/DevFaqDataLoader[What is a DataLoader?].
* *AbcResolver.xml.* Maps the  ``.abc``  and  ``.ABC``  extensions to the MIME type. The  ``AbcDataLoader``  only recognizes the MIME type; it does not know about the file extension.
* *AbcDataObject.java.* Wraps a  ``FileObject`` . DataObjects are produced by DataLoaders. For more information, see  link:https://netbeans.apache.org/wiki/devfaqdataobject[What is a DataObject?].
* *AbcDataNode.java.* Provides what you _see_ in the IDE—functionality like actions, icons, and localized names.
* *AbcDataLoaderBeanInfo.java.* Controls the appearance of the loader in the Object Types section of the Options window.



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


[start=1]
1. Right-click the project node and choose New > Action.

[start=2]
1. 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:


image::images/filetype_60-action1.png[]

Click Next.


[start=3]
1. 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:


image::images/filetype_60-action2.png[]

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.


[start=4]
1. 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.

[start=5]
1. In the Source Editor, add some code to the action's  ``performAction``  method:

[source,java]
----

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.


[start=6]
1. 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  link:https://netbeans.apache.org/tutorials/nbm-glossary.html[System Filesystem] Browser. Expand  ``<this layer>`` , expand  ``Loaders`` , continue expanding nodes until you see the  ``Action``  that you created above.

[start=7]
1. Drag-and-drop  ``My Action``  so that it appears below the  ``Open``  action, as shown below:


image::images/filetype_60-action3.png[]

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.


[start=1]
1. Use the Window Component wizard to create a TopComponent called AbcTopComponent.

[start=2]
1. Change the data object to use OpenSupport instead of DataEditorSupport.


[source,java]
----

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()));
              
}
----


[start=3]
1. Create OpenSupport class:


[source,java]
----

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;
    }
 
}
----


[start=4]
1. 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  link:https://netbeans.apache.org/tutorials/60/nbm-visual_library.html[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

* In the Projects window, right-click the  ``Abc File Type``  project and choose Install/Reload in Target Platform.

The module is built and installed in the target IDE. The target IDE opens so that you can try out your new module. The default target IDE is the installation used by the current instance of the IDE.


=== Using the NetBeans Module


[start=1]
1. Create any kind of application in the IDE.

[start=2]
1. Right-click the application node and choose New > Other. In the Other category, a dummy template is available for the new file type:


image::images/filetype_60-action4.png[]

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.


[start=3]
1. 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:


image::images/filetype_60-dummytemplate.png[]


[start=4]
1. Choose the new menu item, the Abc file's name and location are shown:


image::images/filetype_60-information.png[]


=== Creating a Shareable Module Binary


[start=1]
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):


image::images/filetype_60-shareable-nbm.png[]


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


link:http://netbeans.apache.org/community/mailing-lists.html[Send Us Your Feedback]



== Next Steps

For more information about creating and developing NetBeans modules, see the following resources:

*  link:https://netbeans.apache.org/platform/index.html[NetBeans Platform Homepage]
*  link:https://bits.netbeans.org/dev/javadoc/[NetBeans API List (Current Development Version)]
*  link:https://netbeans.apache.org/kb/docs/platform.html[Other Related Tutorials]


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

|8 |15 April 2008 |Updated the styles (badge, table of contents, required software table) to the new format. 
|===