NetBeans Wiki: DeveloperDocumentation

DeveloperDocumentation

Your trail:

Page Info Plain View My Prefs Log in

This page (revision-13) last changed on 18:38 30-May-2007 by GandalfTheGrey.

CategoryNeedProofRead
This page was converted from http://wiki.java.net/bin/view/Netbeans/DeveloperDocumentation
Please check if the conversion was accurate and fix the found mistakes. Once done, delete this text, ie from the beginning of the page up to and including the horizontal line
Thank you for help

Quick links:

NetBeans Developer FAQ NetBeans Module and Rich Client Application Development NetBeans Plugin Portal Basic Terms for NetBeans Plug-in Module Development

NetBeans Module & Platform Development Work-in-Progress Page

This is the work-in-progress page for documentation about developing modules for NetBeans IDE and for developing standalone rich-client application on top of the NetBeans Platform. Anyone can contribute to this page, though NetBeans developers and writers will regularly maintain, correct, finetune, and update it.

A NetBeans module is a Java archive (JAR) file which contains Java classes written to interact with the NetBeans APIs. A module identifies itself as a module by an entry in its MANIFEST.MF file. NetBeans modules are packaged as NBM files (.nbm extension) for non-installer distribution, usually via the NetBeans Update Center. NetBeans modules are written with one of two aims in mind:

Extending the IDE. You can very easily extend the IDE's functionality with new features. For example, you can write modules that make your favorite cutting-edge technologies available to the IDE. Or, if you miss some functionality in the IDE, you can add it yourself, by writing a module that provides the desired functionality.
Building a standalone rich-client application. You can use the core of the IDE as a platform on top of which you develop rich client applications. The core of the IDE is a separate NetBeans product called the NetBeans Platform. You can save a lot of development time by reusing features readily available in the NetBeans Platform.

Basic NetBeans Module Development Terms

NetBeans Platform. This the core of the NetBeans IDE, with all the IDE-specific modules stripped away. The NetBeans Platform provides an application's common requirements such as menus, document management, and settings right out-of-the-box. Building an application "on top of NetBeans" means that, instead of writing applications from scratch, you only provide the parts of your application that the NetBeans Platform doesn't already have. At the end of the development cycle, you bundle your application with the NetBeans Platform, saving you time and energy and resulting in a solid, reliable application.
NetBeans (Plug-in) Module. A group of Java classes that provides an application with a specific feature. For example, the feature provided by the Java classes in the Google Toolbar Module is a google toolbar. The Java classes use the manifest.mf file to declare the module and the layer.xml configuration file to register their functionality in the System Filesystem. In NetBeans terminology, "plug-in" is an adjective while "module" is a noun. There is no difference in meaning between them.
Cluster. A cluster is a group of modules. They are usually closely related as in the example of a loader, editor and viewer for a specific file format, but can also be a group of unrelated modules that together form a complete application which you can distribute to your users. This relieves you from having to distribute the platform to those who already have a copy, which is similar to how applications are often distributed without a copy of the JRE.
Module Suite. A group of interdependent modules that are deployed together. The IDE helps you to brand the suite -- for example, you can add a splash screen and you can specify the parts of the NetBeans Platform that you don't want your application to provide. See also What is the difference between a suite and a cluster?
NetBeans System Filesystem. The System Filesystem is the general registry for publicly accessible data and objects. It is a virtual filesystem that contains configuration information. NetBeans stores a wide variety of configuration information in the system filesystem. For example, the system filesystem contains a folder called "Menu", which contains subfolders with names such as "File" and "Edit". These subfolders contain files that represent Java classes which implement the actions that appear in the "File" and "Edit" menus.

When you create a module, you are free to create your own folders in the system filesystem to store data that relate to your module. You can also add objects to existing folders. One of the reasons to use the system filesystem is that it allows objects to be declared, but their classes not actually loaded by the JVM until something needs to use them, thus saving memory.

One important aspect of a NetBeans virtual filesystem is that it can fire events to notify the rest of the system when something in it changes. NetBeans listens for changes in the system filesystem, and if, for example, something creates a new object in one of the menu folders, that new item will appear in the menu.

XML Layer Files. You use a XML layer file (layer.xml) as part of the installation system for your module. The contents of the layer.xml will be automatically included in the system filesystem when your module is installed.

When you use a module project template, a layer.xml file is automatically created for you. When you use a module file template to create a new action or to have the IDE recognize a new file type, the IDE automatically registers the new items in the layer.xml. You can use the System Filesystem Browser to tweak the layer.xml file, or you can do so manually using code completion in the Source Editor.

NetBeans APIs. The NetBeans APIs are the public interfaces and classes which are available to module writers. They are divided into specific APIs for dealing with different types of functionality. The contents and behavior of the Java source packages and its subpackages, as specified in the API reference documentation, are the APIs. After you access the NetBeans API sources and Javadoc, you can refer to them in the Source Editor, while developing NetBeans modules. For a full list of NetBeans APIs, see the NetBeans API List .

What Can I Do with NetBeans Module Development?

Do You Have a "Hello World"?

"Hello World" for NetBeans module developers: NetBeans IDE 5.0 Plug-in Module Quick Start Guide
"Hello World" for rich-client application developers: NetBeans IDE 5.0 Rich-Client Application Quick Start Guide

NetBeans APIs

NetBeans provides a rich set of APIs for extending the IDE and for building on top of the NetBeans Platform. The hardest part of understanding the APIs is probably to know what functionality each API provides. Below is a table listing only the most common APIs, with a brief introduction and related tutorials. Each tutorial provides related downloadable sample code.

API	Description	Related Sample Code and Tutorials
Actions API	Defines global singleton actions (such as Open, Cut, Paste) which your module may use.	NetBeans Google Toolbar Module Tutorial
File Systems API	An API for "virtual files". NetBeans uses this API to access user files on disk, files inside JARs, and configuration data for the IDE.	File Systems API description
Datasystems API	"Parsed files". Provides DataObjects which wrap FileObjects and provide programmatic access to their contents. Each file type NetBeans recognizes (such as Java files or HTML files) has a corresponding DataObject subclass provided by the module that adds support for that file type.	NetBeans DataLoader Module Tutorial NetBeans Component Palette Module Tutorial
Nodes API	Generic hierarchy and action context. Nodes are similar to TreeNodes, but can be used in more than trees. Nodes add user-visible things such as popup menu actions, localized display names and icons to DataObjects, but can also be used without DataObjects, by themselves. The Explorer API contains a variety of UI components such as trees, lists and tables which can be used to display a node and its children. Each window system UI component (TopComponent) has one or more "activated nodes" which determine what actions are enabled when that component has focus.	NetBeans System Properties Module Tutorial
Windows API	Allows modules to provide window-like components, mainly through embeddable visual components called topcomponents .	NetBeans Anagram Game Module Tutorial FeedReader Tutorial
Palette API	Provides a palette topcomponent with drag-and-droppable content. For example, this API is used to provide groups of related tags that can be inserted in HTML file and JSP files in the IDE.	NetBeans Component Palette Tutorial NetBeans Code Snippet Tutorial
Refactoring API	Enables you to extend the IDE's refactoring capabilities by providing facilities for plugging your own refactorings into the IDE.	Refactoring in a BPEL Module Project Using NetBeans Enterprise Pack
MultiView API	Lets you display multiple perspectives of the same data. For example, the `web.xml` multiview editor provides an XML view and a topcomponent view.	NetBeans Visual Library in NetBeans Platform 6.0
JavaHelp Integration API	Adds helpset to the IDE or an application built on the NetBeans Platform.	Connecting Help in NetBeans: From Help Set Installation to Hooking up Context-Sensitive Help
...	...	...
...	...	...
...	...	...

Basic API Terms

The general repository for commonly used API terms is the NetBeansDeveloperFAQ. Here is a list of entry points to the most common of the commonly used terms:

NBM What is an NBM?
FileObject What is a FileObject?
Filesystem What is a Filesystem?
DataObject What is a DataObject?
Dataloader What is a DataLoader?
Node What is a Node?
Cookie ...
Action ...
Lookup What is a Lookup?

How Do the APIs Relate to Each Other?

Introduction to the NetBeans Idioms and Infrastructure

Templates for API Extensions in NetBeans IDE 5.0

NetBeans IDE 5.0 provides a set of wizards that create the basic files for various APIs. For example, when you want to implement the TopComponent class, use the New Window Component wizard to get started. After using the Window Component wizard, you have a bunch of files and sample code that you extend to build your module. Below, where an API is supported by a wizard, the wizard is listed, together with a list of files that is generated, as well as a related tutorial (with sample code) that illustrates a typical scenario.

Note that all tutorials listed below include downloadable source code, which means that you can look at examples of how to extend the files created by the wizards.

Name of Wizard	Which API(s) was the wizard created to support?	Which files, sample code, etc, does the wizard give me?	Once I have them, what can I do with these files and sample code?	Which tutorial(s) make use of this wizard?
New Action wizard	NetBeans Actions API	Created files: * A file that subclasses CallableSystemAction class or a file that subclasses CookieAction class . Impact on `layer.xml` (the module's NetBeans configuration file): * The action is registered as an instance file in the `Actions` folder. Shadow files are created in all the folders that you specified in the New Action wizard. For example, if you specified that the action should be registered as a global menu item, it will find itself as a shadow file in the `Menu` folder in the `layer.xml` file. If you're extending CookieAction class , a shadow file is created in the `Loaders` folder. (For details on shadow files, see What are .shadow files? )	Do something with the action that the IDE created for you. For example, now that the menu item is attached to one or more of a variety of items—the main menu, a toolbar, a keyboard shortcut, the the pop-up menu of one or more of the editors (the Source Editor is made up of an XML editor, a Java editor, a JSP editor, etc), or the pop-up menu of a node in one of the windows (such as the pop-up menu of a JSP node in the Projects/Files/Favorites windows)— you need to provide the code that specifies what you want to have happen when the user invokes the action. What an action does is defined in its `performAction()` method.	NetBeans Google Toolbar Module Tutorial
New File Type wizard	NetBeans Loaders API	Created files: `DataLoader.java` A class that extends UniFileLoader . (See also: What is a DataLoader? ) `DataBeanInfo.java` A class that extends `java.beans.SimplebeanInfo`. It is used for displaying information, such as the related icon. `DataNode.java` A class that extends DataNode . (See also: What is a Node? ) `DataObject.java` A class that extends MultiDataObject . (See also: What is a DataObject? ) `resolver.xml` Declarative resolution of MIME-type. Impact on `layer.xml` (the module's NetBeans configuration file): A long list of standard actions are listed in the `Loaders` folder for the specified MIME type, so that the file type has these default actions (such as 'Open' and 'Save') available from the start. The MIME resolver is registered in the `Services/MIMEResolver` folder. The dummy template is registered in the `Templates/Other` folder. This means that when the user opens the New File wizard, the dummy template will be in the Other folder. (You can change the position of the template, as well as, of course, its content.)	Now that the IDE (or your application built on top of the NetBeans Platform) recognizes your file type as being distinct from all other file types, you can provide a lot of functionality specifically for the newly-recognized file type (such as menu items, dialog boxes, wizards, syntax highlighting, code completion, multiview editors, code folding, component palettes, etc. etc. etc. For all of these features, the starting point is that the IDE is able to identify a file type as being distinct) and that's why the first step is to run through the New File Type wizard so that the basic file type recognition files are generated for you.	NetBeans DataLoader Module Tutorial NetBeans Component Palette Module Tutorial
New Project Template wizard	WizardDescriptor class	Created files: `.ZIP` file (containing the project that forms the basis of the project template or sample) `WizardIterator.java` `PanelVisual.java` `WizardPanel.java` `.HTML` file (for the description area in the New File wizard) Impact on `layer.xml` (the module's NetBeans configuration file): The template is registered in the Templates/Project folder, within the subfolder that you indicated in the wizard. This means that when the user opens the New Project wizard, the template will be in the specified folder. (You can change the position of the template after using the wizard.)	Extend the files to finetune a template that users build on when creating their own project. For example, in the IDE a user chooses the 'Web Application' project template in the New Project wizard, then the IDE creates a project consisting of a JSP file, a `web.xml` file, a server-specific deployment file, and project metadata within a specific structure that is useful for web application projects. Alternatively, extend the files to finetune a sample that illustrate some aspect of project functionality. For example, in the Samples directory within the New Project wizard, an Anagram Game is included to demonstrate J2SE functionality. Samples are a kind of project template; they have the same behavior as project templates, but they are used for a different purpose.	NetBeans Project Template Module Tutorial NetBeans Project Sample Module Tutorial
New Window Component wizard	TopComponent class	Created files: `TopComponent.java` A class that extends the TopComponent class. The TopComponent subclass includes the following methods when you use the New Window Component wizard: `getDefault()` `getPersistenceType()` `componentOpened()` `componentClosed()` `writeReplace()` `preferredID()` `Action.java` An action that the `layer.xml` file registers in the Window menu. The IDE creates this Action class to display the component. `TopComponentSettings.xml` `TopComponentWstcref.xml` These files dock, instantiate, and load the window. There should be no need to touch these files at all. These files need to be registered in the `layer.xml` file. The Window Component wizard does this for you automatically. Impact on `layer.xml` (the module's NetBeans configuration file): The action is registered in the `Actions` folder, with a shadow file registered in the `Menu/Window` folder. For details on shadow files, see What are .shadow files? ). `TopComponentSettings.xml` is registered in the `Windows2/Components` folder. *`TopComponentWstcref.xml` is registered in the `Windows2/Modes/your-selected-position` folder.	Extend the TopComponent implementation to create a window (also known as 'view') for a module. For example, the IDE's Projects window is a 'window', just as the Navigator, Output window, Palette, and Debugger. The multiview editor used by the `web.xml` file is also a topcomponent , so you would use the Window Component wizard to create a basic implementation of this class.	...
New Wizard wizard	WizardDescriptor class	Created files: The Wizard wizard's first panel lets you set a 'Registration Type' ('Custom' or 'New File') and a 'Wizard Step Sequence' ('Static' or 'Dynamic'). The consequences of these selections are outlined below: Registration Type: Custom Wizard Step Sequence: Static ---- Created files: `SampleAction.java` `VisualPanel.java` (for each wizard step) `WizardPanel.java` (for each wizard step) These files are ideal for uncomplicated wizards that progress sequentially from panel to panel without divergences or reversals. A menu item or toolbar button invokes the wizard and subsequent steps are generally linear and forward-directed. An example of this type of wizard is the Update Center wizard, which does not allow you to skip steps. It does not branch off or change direction based on choices made by the user. Registration Type: Custom Wizard Step Sequence: Dynamic ---- Created files: `WizardIterator.java` * `VisualPanel.java` (for each wizard step) `WizardPanel.java` (for each wizard step) These files are for wizards that provide more flexibility to the user. A WizardDescriptor.Iterator class guides progress from one panel to the next. The developer has a lot more freedom in coding the wizard, but has a more complex task since there are many more possibilities to consider. Even though the Custom/Simple wizard type can also be extended to provide support for panel skipping and reversals, the Custom/Dynamic type was made for this purpose. For example, the Add Server Instance wizard offers different panels depending on the type of server that the user wants to register. Registration Type: New File Wizard Step Sequence: Not Applicable ---- Created files: `WizardIterator.java` `VisualPanel.java` (for each wizard step) `WizardPanel.java` (for each wizard step) `.HTML` file (for the description area in the New File wizard) These files are for wizards that are used to create new files. This wizard is registered in the New File wizard via the `layer.xml` file. All the necessary entries in the `layer.xml` file are created for you by the Wizard wizard. In addition, when you make this choice, the Wizard wizard creates a WizardDescriptor.Iterator	Add user interface components to the visualpanels and wire them to their related wizardpanels so that the information is correctly passed from one to the other. Finetune the wizard's steps, graphics, left side-bar text, and a user panel on the right. For more complex wizards, set the sequences that the user will follow when using the wizard.	...

Module Development Lifecycle

Set up the project. If you're building on top of the NetBeans Platform, you'll need to start with a Module Suite project. Only this project type lets you brand an application. If you use the Module Suite project, you can use the IDE to specify a splash screen, and create an executable, ZIP file, and JNLP application. If you're building a NetBeans module, don't use the Module Suite project, except if you need to include JAR files (you put these on your classpath by wrapping them in Library Wrapper Module projects and attaching them to a Module Suite project, along with the NetBeans Module project that provides the module's code).
Let the IDE generate lots of files and code for you. Use the templates listed in the table above to very quickly create the basis of your module's code.
Code the module or application. Here are some ideas on 'what to do when I am stuck':
Download the NetBeans sources and learn from them. Alternatively, you can browse the sources on-line , i.e., without having to download them.
Use NetBeans API JavaDoc and Source inside the IDE. Download the NetBeans sources and get the JavaDoc from the Update Center. Attach both of them to the NetBeans Platform Manager (available under the Tools menu). Now you can access the JavaDoc while typing. When you hold down the Ctrl key and move your mouse over an identifier (such as TopComponent in a class declaration for classes that subclass TopComponent) a hyperlink appears, which you can click, and when the hyperlink is clicked, the source file opens and you can read the source to understand what you're supposed to be doing with it.
Refer to the tutorials and downloadable sample code. The FeedReader sample is included in the New Project wizard in the Samples folder. In addition, many typical scenarios are outlined in tutorials here . Each tutorial contains a link to a ZIP file containing the sample discussed in the tutorial.
Join the mailing list. Share your expriences with others, ask questions, and discuss your issues at http://openide.netbeans.org/ .
Build and run. Try out the module or application by building and running it. With modules, you can try them out in the IDE that you're currently using or in another instance of the same IDE. The latter means that the IDE starts up again and that your module is loaded in this newly-started IDE. This is safer.
Test, debug, and profile. Use the NetBeans debugger, the NetBeans Profiler, and NetBeans JUnit file templates.
Brand and distribute. Branding is only applicable to Module Suite projects. Right-click the Module Suite Project node and choose Properties. In the Project Properties dialog box, define a splash screen, application title, progress bar, etc. Distribute NetBeans modules in binary form as NBM files. (Use the Create NBM menu item on the module's project node.) Recipients can install your NBM file through the Update Center. Distribute applications as JNLP applications (i.e., web startable) or ZIP distributions (these distributions include an .exe file created by the IDE). (Use Build JNLP or Build ZIP distribution on the Module Suite's project node.)

Layer Files: What Are They For and How Are They Used?

(coming soon)

End Products: ZIP, JNLP, NBM, and Other Acronyms