NetBeans Master Developer FAQ

<folder name="Editors">
  <folder name="text">
    <folder name="x-java">
      <folder name="Popup">
        <file name="org-mymodule-MyAction.instance"/>
      </folder>
    </folder>
  </folder>
</folder>

• How do I add an action to a file of a given mime-type?
• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to the NetBeans tool bar?
• How do I add an action to my custom node?

<folder name="Loaders">
  <folder name="text">
    <folder name="html">
      <folder name="Actions">
        <file name="org-mymodule-MyAction.instance"/>
      </folder>
    </folder>
  </folder>
</folder>

DataLoader loader = DataLoaderPool.getDefault().firstProducerOf(SomeDataObject.class);
if (loader != null) {
    SystemAction[] actions = loader.getActions();
    SystemAction[] newactions = new SystemAction[actions.length + 2];
    System.arraycopy(actions, 0, newactions, 0, actions.length);
    // More realistically: take care that it is not a duplicate,
    // place into a specific position, etc.:
    newactions[actions.length] = null;
    newactions[actions.length + 1] = SystemAction.get(SomeAction.class);
    loader.setActions(newactions);
}

• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to the NetBeans tool bar?
• How do I add an action to my custom node?

<folder name="Loaders">
  <folder name="folder">
    <folder name="any">
      <folder name="Actions">
        <file name="org-mymodule-MyAction.instance"/>
      </folder>
    </folder>
  </folder>
</folder>

• How do I add an action to a file of a given mime-type?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to the NetBeans tool bar?
• How do I add an action to my custom node?

• An example how to register action manually
• How do I add an action to a file of a given mime-type?
• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans tool bar?
• How do I add an action to my custom node?

<filesystem>
    <folder name="Projects">
        <folder name="org-netbeans-modules-java-j2seproject">
            <folder name="Customizer">
                <file name="Bla.instance">
                    <attr name="instanceCreate" methodvalue="org.bla.BlaPanelProvider.createBlaPanel"/>
                </file>
            </folder>
        </folder>
    </folder>
</filesystem>

public class BlaPanelProvider implements ProjectCustomizer.CompositeCategoryProvider {

    public static BlaPanelProvider createBlaPanel() {
        return new BlaPanelProvider();
    }

    @Override
    public Category createCategory(Lookup arg0) {
        ProjectCustomizer.Category toReturn = null;
        toReturn = ProjectCustomizer.Category.create(
                "Bla",
                "Bla",
                null,
                null);
        return toReturn;
    }

    @Override
    public JComponent createComponent(Category arg0, Lookup arg1) {
        return new BlaPanel();
    }
    
}

See also Project Properties GUI for custom project templates

See also: Common Project Actions

<filesystem>
    <folder name="Actions">
        <folder name="SomeFolder">
            <file name="projectcontextmenudemo-DemoAction.instance"/>
        </folder>
    </folder>
    <folder name="Projects">
        <folder name="Actions">
            <file name="projectcontextmenudemo-DemoAction.shadow">
                <attr name="originalFile"
stringvalue="Actions/SomeFolder/projectcontextmenudemo-DemoAction.instance"/>
            </file>
        </folder>
    </folder>
</filesystem>

See also How do I add an action to a project popup menu of a specific project type?

• An example how to register action manually
• How do I add an action to a file of a given mime-type?
• How do I add an action to a folder?
• How do I add an action to the text-editor popup menu?
• How do I add an action to the NetBeans menu bar?
• How do I add an action to my custom node?

CookieAction is used to write actions that are sensitive to what is in the selected Node(s) Lookup. You can specify one or more classes that must be present in the selected Node's Lookup, and some other semantics about enablement.

Being an older class, under the hood it is using Node.getCookie(), so your action will only be sensitive to things actually returned by that method - in other words, only objects that implement the marker interface Node.Cookie can work here.

NodeAction

NodeAction is somewhat more flexible, but requires more code to implement. It is just passed the array of activated nodes whenever that changes, and can choose to enable or disable itself as it wishes. Essentially this is just an action that automagically tracks the global Node selection.

Roll your own

The following is relatively simple and affords a way to perform whatever enablement logic you like (NodeAction can do that too, but this might be a little more straightforward and your code doesn't have to worry about nodes at all: DevFaqWhatIsANode). To understand how this works, see DevFaqTrackGlobalSelection:

public class FooAction extends AbstractAction implements LookupListener, ContextAwareAction {
    private Lookup context;
    Lookup.Result<Whatever> lkpInfo;

    public FooAction() {
        this(Utilities.actionsGlobalContext());
    }

    private FooAction(Lookup context) {
        putValue (Action.NAME, NbBundle.getMessage(FooAction.class,
                "LBL_Action")); //NOI18N

        this.context = context;
    }

    void init() {
        assert SwingUtilities.isEventDispatchThread() 
               : "this shall be called just from AWT thread";

        if (lkpInfo != null) {
            return;
        }

        //The thing we want to listen for the presence or absence of
        //on the global selection
        lkpInfo = context.lookupResult(Whatever.class);
        lkpInfo.addLookupListener(this);
        resultChanged(null);
    }

    public boolean isEnabled() {
        init();
        return super.isEnabled();
    }

    public void actionPerformed(ActionEvent e) {
        init();
        Collection<? extends Whatever> c = lkpInfo.allItems();
        //do something with them here
    }

    public void resultChanged(LookupEvent ev) {
        setEnabled (lkpInfo.allItems().size() != 0);
    }

    public Action createContextAwareInstance(Lookup context) {
        return new FooAction(context);
    }
}

Applies to: NetBeans 6.5, 6.7

<folder name="Actions">
   <folder name="Build">
     <file name="com-foo-SomeAction.instance"/>
   </folder>
</folder>
<folder name="Menu">
   <folder name="Build">
     <file name="pointerToComFooSomeAction.shadow">
        <attr name="originalFile" stringvalue="Actions/Build/com-foo-SomeAction.instance"/>
     </file>
   </folder>
</folder>

And you may have noticed that actions are usually put, not directly into the Menu/ folders, but into subfolders of this Actions/ folder. Then we create .shadow files that act like symbolic links, pointing to the real .instance file . Why all this indirection?

Older versions of the NetBeans UI included the ability to rearrange, and even delete, whole menus or individual menu items, and future ones may again. (Many applications built on NetBeans will not want to expose such customizability, but some do.) The current UI does include a key binding editor; the Actions/ folder can be used from this editor to list available actions, even those which are not currently bound to any keystroke.

Additionally, for actions which are javax.swing.Action but not SystemAction, creating the action instance in only a single place ensures that it acts as a singleton. (While the action class likely has no declared instance fields, it does have some state, notably information about keyboard accelerators which should be displayed in menu presenters.)

Applies to: NetBeans 6.7

If one does not exist, file an enhancement request against the module that actually creates these nodes, asking for an appropriate API for doing what you want (and be clear about exactly what you want or why). If you really want to expedite it, write a patch that creates such an API (look at how other modules do this sort of thing and aim to follow a similar pattern) - it's hard to say no to working code.

Yes. Have your node subclass AbstractNode or whatever else you like.

NB 6 > m9 Specific: Implement ChildFactory. To create the Children object for your Node, pass it to Children.create(). When the child list needs updating, call refresh() on your ChildFactory. Its createKeys method will be called again and you can update the set of key objects as needed; Nodes for objects that remain in the list of keys will simply continue to exist; additions and removals will be handled.

NB 5 And Earlier: Have your Children object subclass Children.Keys . As needed, call setKeys() on the Children.Keys object. Just by passing a larger or smaller (or reordered) list of keys, you will be adding or removing (or reordering) children.

Do not ever try to add/remove children from a node you did not create (unless it has an API that explicitly gives you permission to do that); occasionally people try to add child nodes to nodes for things like Java files. If it works at all it's by accident.

Applies to: NetBeans 4.0, 4.1, 5.0

• A module is a JAR file with some special manifest entries. The NetBeans IDE (5.0 and up) has lots of support for building modules.
• Modules usually affect the system by putting entries in an XML file inside their JAR, which the system reads.
• You can add to, remove from, change or completely remove menus from the main window, toolbars and other things from a module
• To show your own tabs in the main window, you will want to subclass TopComponent
• The windowing system provides facilities for tracking selection, and actions can be made sensitive to selection. Selection typically centers around use of Nodes; it is also possible to have context sensitive actions without Nodes.
• It is possible to build tree and other views of objects very quickly using Nodes in conjunction with Explorer Views
• Many pieces of NetBeans UI are really views of some folder in the configuration filesystem which modules install things into
• The configuration filesystem is read-write, and changes can be saved to the user's settings directory
• Applications built on NetBeans do not have to be IDE-like - there is plenty of support for editing files available in the Editor module and friends, but you do not even have to include those modules in your application if you do not use them

A lot of things in NetBeans are based around file recognition and using files to provide Java objects. Even if your application has nothing to do with editing files, this may still be very useful to you, since the same mechanism that recognizes/displays a user's files on disk also recognizes/displays configuration data (which may not even be files in the traditional sense at all), and such "files" can actually be factories for whatever kind of object you want (and that way you get persistence of those files for free).

For example, the FeedReader tutorial simply serializes POJO Feed objects into the configuration filesystem , and its whole UI consists of aiming a standard tree component at a folder full of those objects, and providing a few actions to let the user create more of them. When the application shuts down, it does not need to any special code for persisting them, it is all automatic.

For more information about how that works, see the section on file recognition.

One of the most basic and important things to know about is how modules register objects - this is mainly done through a configuration file inside the module's jar file (if you are using NetBeans 5.0 or greater's module building support, you can usually avoid hand-editing this file). Most things a module does to influence the environment are declarative rather than programmatic - in other words, you put some text in an XML file, or an entry in a jar manifest, or a file in some specific place in the module jar, and your functionality will be discovered when the system starts up - as opposed to writing java code.

Two of the most common needs are opening custom Swing components in the UI, and installing actions in the main menu .

Other basic topics that are worth reading to get the lay of the land are:

• Lookup
• How to run some code on startup
• Overview of filesystems
• The windowing system

There are various tutorials, and the canonical reference to NetBeans APIs is the API javadoc.

• Requirements
• Installation And Configuration
• Projects Creation
• Enterprise Application Development
  • Build Script Modifying
  • Generating Entity Classes From Database
  • Create Session Bean (stateless) with remote interface to communicate with persistence unit
  • Modify the dbreader-ear-app-client Application Client module
• NetBeans Modules Development
  • Set Up dbreader NetBeans Module Suite
  • Set Up customers NetBeans Module
  • Create Window Component
  • Write Customers Top Component Logic
• Run Application
• Debug Application

Requirements

• Java(TM) SE Development Kit 5.0
• NetBeans IDE 5.5.1 or later
• NetBeans Platform 5.5.1 or later
• GlassFish v2 or later

Installation And Configuration

Install all of the required products (installation guides are available on the product's websites). When it'll be done we have to set up a few things. First of all please start NetBeans IDE 5.5.1 and register GlassFish v2. Right click on the Servers node in the Runtime tab and select Add server (choose Sun Java Application Server).

Now we need to register NetBeans Platform into IDE. It's in fact almost same as to add a new server. In menu Tools -> NetBeans Platform Manager click on a Add Platform button and pass through the wizard (as a new platform select downloaded NetBeans Platform 5.5.1).

Projects Creation

It's time to create all projects. We need NetBeans Module Suite project, NetBeans Module (added into your NetBeans Module Suite) project and Enterprise Application project with Application Client and EJB module included. Let's do it. First of all we create NetBeans Module Suite project. Call it dbreader. As used platform choose the new one what you registered before.

Then create NetBeans Module Project. Call it customers. And check that you want to add it into your dbreader suite. All other options leave as default.

Actually we have had NetBeans Modules created and now we have to create Java EE part. So let's create an Enterprise Application with Application Client and EJB module. Call it dbreader-ear. Include Application Client and EJB module. Exclude Web module. Also select Java EE 5 version and choose Sun Java Application Server as development server.

Great ! You have successfully created all required projects. Now you should see something like this in Projects tab.

Enterprise Application Development

Build Script Modifying (5.5.x)

We need to modify dbreader-ear build.xml script because the dbreader suite jnlp distro has to be packed into dbreader ear. Due to add these lines into dbreader-ear build.xml (instructions for 6.x are in the next part).

    <property name="dbreader.home" value="../"/>
    
    <target name="build-dbreader-jnlp">
        <java classname="org.apache.tools.ant.Main" dir="${dbreader.home}" failonerror="true" fork="true">
            <jvmarg value="-Dant.home=${ant.home}"/>
            <arg value="build-jnlp"/>
            <classpath path="${java.class.path}"/>
        </java>
    </target>
    
    <target name="pre-dist" depends="build-dbreader-jnlp">
        <!-- dbreader.home must point to DatabaseReader Application home directory -->

        <mkdir dir="${build.dir}/lib"/>
        <copy todir="${build.dir}/lib">
            <fileset dir="${dbreader.home}/build/jnlp/app" includes="*.jar" />
            <fileset dir="${dbreader.home}/build/jnlp/branding" includes="*.jar" />
            <fileset dir="${dbreader.home}/build/jnlp/netbeans" includes="*.jar" />
        </copy>
    </target>

You are able to access build.xml file in Files view.

After editing you should see something like this.

Build Script Modifying (6.x)

    <property name="dbreader.home" value="../"/>
    
    <target name="build-dbreader-jnlp">
        <java classname="org.apache.tools.ant.Main" dir="${dbreader.home}" failonerror="true" fork="true">
            <jvmarg value="-Dant.home=${ant.home}"/>
            <arg value="build-jnlp"/>
            <classpath path="${java.class.path}"/>
        </java>
    </target>
    
    <target name="pre-dist" depends="build-dbreader-jnlp">
        <!-- dbreader.home must point to DatabaseReader Application home directory -->

        <mkdir dir="${build.dir}/lib"/>
        <copy todir="${build.dir}/lib">
            <flattenmapper/>
            <fileset dir="${dbreader.home}/build/jnlp/app" includes="**/*.jar" />
            <fileset dir="${dbreader.home}/build/jnlp/branding" includes="**/*.jar" />
            <fileset dir="${dbreader.home}/build/jnlp/netbeans" includes="**/*.jar" />
        </copy> 
    </target>

If you're not using Mac then also don't forget to exclude "Apple Application Menu" module (module suite project properties -> libraries -> PlatformX). Also make sure you're including only modules from platformX cluster.

Generating Entity Classes From Database

We have dbreader-ear project infrastructure prepared. Now we have to generate entity classes from sample database. Right click on dbreader-ear-ejb project in Project tab and select New -> Entity Classes From Database. In wizard chose as datasource jdbc/sample datasource and select CUSTOMER table.

On the next wizard panel type package for entity classes. Type db. Then Click on create persistence unit. Persistence unit dialog will appear. Click on Create. Now finish the wizard by clicking on the Finish button.

Now we have generated entity classes from jdbc/sample database. Under dbreader-ear-ejb project you can see generated classes.

Create Session Bean

We need to create stateless session bean with remote interface to communicate with persistence unit. Create one and call it DataBean.

When you have session bean created add business method called getData. You are able to do it by right clicking on the editor pane (in DataBean.java file opened) and select EJB Methods -> Add Business Method. Pass through the wizard and create getData method which returns java.util.List.

Now use entity manager. Once again do a right click on the editor pane and select Persistence -> Use Entity Manager. Entity manager code is generated. Now implement getData method.

    public List getData() {
        //TODO implement getData
        return em.createQuery("SELECT c FROM Customer c").getResultList();
    }

After that you should see in editor (in DataBean.java file) something like this.

Modify Application Client

We prepared EJB module and now we have to implement functionality into dbreader-ear-app-client Application Client module. Open Main.java file in dbreader-ear-app-client project.

Now call your session bean DataBean. Right click on editor pane and select Enterprise Resources -> Call Enterprise Bean. In the dialog select your DataBean and click OK.

Now we need to implement main method and create getCustomers method. Before that add <dbreader_project_home>/build/jnlp/netbeans/boot.jar (or <dbreader_project_home>/build/jnlp/netbeans/org-netbeans-bootstrap/boot.jar in case of NetBeans 6.1) file on classpath. Do it by right clicking on dbreader-ear-app-client project and select Properties. There select Libraries and then click on Add JAR/Folder and in open file dialog select boot.jar file. Don't forget to uncheck the checkbox. We do not want to package this file with dbreader-ear-app-client module. Actually you have to run build-jnlp target on dbreader suite. Before that please perform step Set Up Suite. Then you can right click on dbreader project and select Build JNLP Application.

Implement main method by this code.

    public static void main(String[] args) {
        try {
            String userDir = System.getProperty("user.home") + File.separator + ".dbreader";
            org.netbeans.Main.main(new String[] {"--branding", "dbreader", "--userdir", userDir});
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }

Now create getCustomers static method.

    public static List getCustomers() {
        return dataBean.getData();
    }

After doing this you should see something like this in editor pane.

Great ! We have finished development of the dbreader-ear Enterprise Application. Let's go to develop NetBeans Modules.

NetBeans Modules Development

Set Up Suite

Now we set up the dbreader NetBeans module suite. We have to set it as standalone application and also we are able to change splash screen. Right click on dbreader project and select Properties. There select Application and then click on the Create Standalone Application.

Also you are able to set up your own splash screen. Do it by same way and under the Application node in project Properties click on Splash Screen.

Set Up Module

Now we set up the customers NetBeans Module. We have to add dbreader-ear-ejb.jar, dbreader-ear-app-client.jar and javaee.jar on compile classpath. First of all set sources level of the module to 1.5. Right click on customers project and on the first panel select 1.5 for sources level.

Open project.properties file from project tab.

Add this code into project.properties file. Of course use your own path to dbreader and glassfish.

cp.extra=\
/home/marigan/temp/dbreader/dbreader-ear/dbreader-ear-ejb/dist/dbreader-ear-ejb.jar:\
/home/marigan/temp/dbreader/dbreader-ear/dbreader-ear-app-client/dist/dbreader-ear-app-client.jar:\
/home/marigan/apps/glassfish/lib/javaee.jar

After that you should see something like this in editor pane.

Create Window Component

Now we create a new window component which will serve as viewer for database data. Right click on customers project and select New -> Window Component. On the first wizard panel choose editor as Window Position and select Open on Application Start.

On the second panel specify component Class Name Prefix (use Customers) and finish the wizard.

After that you should see this in Project tab.

Write Customers Top Component Logic

We have to write application logic for customers top component. Open CustomersTopComponent.java file in design mode and drag and drop a jTable component from palette into it.

Now switch into source view and modify constructor and add initData method.

    private CustomersTopComponent() {
        initComponents();
        setName(NbBundle.getMessage(CustomersTopComponent.class, "CTL_CustomersTopComponent"));
        setToolTipText(NbBundle.getMessage(CustomersTopComponent.class, "HINT_CustomersTopComponent"));
//        setIcon(Utilities.loadImage(ICON_PATH, true));
        
        initData();
    }
    
    private void initData() {
        List<Customer> data = Main.getCustomers();
        
        Object[][] rows = new Object[data.size()][3];
        int i = 0;
        
        for (Customer c : data) {
            rows[i][0] = c.getName();
            rows[i][1] = c.getEmail();
            rows[i++][2] = c.getPhone();
        }
        
        Object[] colums = new Object[] {"Name", "E-mail", "Phone"};
        
        jTable1.setModel(new DefaultTableModel(rows, colums));
    }

After that you should see something like this.

Run Application

Great job !! Everything is done. Now you can run your application. Right click on dbreader-ear project and select Run Project. Wait a minute do build and glassfish to start. Enjoy your application :o)

Debug Application

There of course comes a time when you need to debug your application. Debugging the server side is relatively easy: start Glassfish in Debug mode and simply "Attach" to it ('Attach Debugger...' from the 'Run' menu).

Debugging the client side is a little harder. On NetBeans 6.1, simply right-clicking on the EAR project and select "Debug" doesn't seem to work. It fails with error messages saying that your classes from your other modules are not found on the classpath. Manually referring to them isn't sufficient either, because once you've done that the Ant debug script will complain about not finding classes belonging to the Platform modules you depend on.

The simple solution is to add the following 2 Ant targets to your build.xml :

   <target name="Debug platform (Attach-debug)" description="Debug the platform, need to attach the debugger once the JVM is started"
            depends="-debug-init-jvm,run"/>

   <target name="-debug-init-jvm">
        <property name="j2ee.appclient.jvmoptions.param" value="-agentlib:jdwp=transport=dt_socket,server=y,address=9009"/>
    </target>

The idea is to call the already-existing "run" target, but specify arguments to be passed to the JVM when its launched. The above arguments will launch the JVM in debug mode, asking it to wait for a connection (default behavior) and the address will be 9009. You could even specify a different port number if you want to run Glassfish in debug mode at the same time (note that the debugger can only attach to one JVM at a time, so you have to detach from the client and then attach to the server).

For more details about the JPDA debugging arguments, see here.

Although a bit drastic for most cases, you can replace the main class used to start NetBeans (DevFaqPlatformAppAuthStrategies) with your own class and then delegate back to NetBeans' normal main class. This offers you a hook early in the startup sequence without having to modify the launchers or shell scripts.

Any module may provide a ModuleInstall class. The validate method will be called before your module is even loaded, so it's the first module-level hook typically available in the startup sequence. Note that many services and classes offered by the platform are unlikely to be initialized at this point.

A short time afterwards, the restored() method will be called on each ModuleInstall class. More services and classes will be initialized at this point than with the validate() method, but the GUI will probably not yet be realized. You can post some code to be executed when the UI is fully loaded like this:

@Override public void restored() {
    WindowManager.getDefault().invokeWhenUIReady(
        new Runnable() {
            public void run() {
                // any code here will be run with the UI is available
                SomeTopComponent.findInstance().open();
            }
        });
}

The ModuleInstall class offers two methods which let you plug into the exit sequence. The closing method is called first and requires that you return a boolean value. If true, then your module agrees to be closed, but if false, then you will prevent the exit sequence from continuing. The close method is called after all ModuleInstall classes return true from the closing method and is the final hook in which modules can participate in the application's lifecycle.

Note that providing a ModuleInstall class will increase total startup time a little, even if you have taken care to execute any long-running tasks from its methods in a background thread. It is always preferable to register objects declaratively, and/or run procedural code when it is first needed rather than eagerly.

Another major class in platform development is the TopComponent class. It offers several methods which allow you to hook into its lifecycle.

Here are some events you can hook into for when a TopComponent is opened:

• JComponent.addNotify
• TopComponent.componentOpened
• TopComponent.componentShowing
• TopComponent.componentActivated

When you set focus on a TopComponent, the componentActivated method is called. Likewise, the componentDeactivated method is called when focus is moved away from that TopComponent.

Here are some events you can hook into for when a TopComponent is closed:

• TopComponent.canClose
• JComponent.removeNotify
• TopComponent.componentHidden
• TopComponent.componentDeactivated
• TopComponent.componentClosed

It seems that the exact sequence in which the opening/closing hooks are invoked could vary, perhaps based on platform. Tom Wheeler listed them above in they order in which he observed them on Windows XP but later found they were invoked in a slightly different order. Likewise, Fabrizio Giudici found that they occurred in yet a different sequence.

Note that you can return false from TopComponent.canClose to prevent the TopComponent from being closed at all.

Applies to: NetBeans 6.5

• Where to find Javadoc? http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-autoupdate-services/overview-summary.html
• Which version of NetBeans should I use? This API was firstly introduced in NetBeans 6.0 Platform where the API was still in development. In NetBeans 6.1 Platform it was made official API, it means further changes should be backward compatible. Use upcoming NetBeans 6.5 Platform for the best performance.

Related articles

• What is an NBM?
• How to customize Plugin Manager?
• How to specify post-install code in NBM?
• How to install components using its custom installers?

Other resources

• Rechtacek's Blog
• Geertjan's Blog

<target name="netbeans-extra" depends="init">
    <branding cluster="${cluster}" overrides="${suite.dir}/branding" token="app"/>
</target>

nbm.needs.restart=true
nbm.is.global=true
nbm.target.cluster=app
extra.module.files=\
        core/locale/core_app.jar,\
        modules/ext/locale/updater_app.jar,\
        modules/locale/org-netbeans-core-windows_app.jar,\
        modules/locale/org-netbeans-core_app.jar,\
        modules/locale/org-netbeans-modules-autoupdate-ui_app.jar,\
        modules/locale/org-netbeans-modules-favorites_app.jar,\
        modules/locale/org-netbeans-modules-javahelp_app.jar,\
        modules/locale/org-netbeans-modules-projectui_app.jar

Note that you may encounter problems doing this in NetBeans 6.0.

Thanks to Matteo Di Giovinazzo for sharing how to do this on the dev@openide list.

This also means that code that responds to a key or mouse event, or some call triggered by one, should run very quickly, because the user can by typing or clicking, but the entire application is blocked from responding to more events until your code exits. So sometimes you will want to move expensive or slow work onto a background thread.

A background thread is any thread that is not the event thread.

If you are running on some other thread, but need to modify some component, a simple way to do this is EventQueue.invokeLater(new Runnable() { public void run() { //this code can modify components } });

Note that the caveat about Swing includes creating components - it is provably not safe to even construct Swing components on a background thread, because of synchronization on Component.getTreeLock().

All of the documents linked here are also available from del.icio.us.

It's a good thing to bookmark.

Javadoc

If you want a local copy of it, you can either download it from the update center, or build it from your source checkout

cd $NB_SRC_ROOT
ant build-javadoc

Using the Javadoc

NetBeans Tutorials

FAQs

Getting the Source Code

Some people claim that they should never need to look at source code - documentation should suffice. That's just silly. The NetBeans codebase is a treasure-trove of examples of how to do things.

Since the end of January 2008 the NetBeans sources are stored in Mercurial repository at hg.netbeans.org.

You can see useful documentation about Mercurial and also about its specifics for NetBeans repository in HgMigrationDocs wiki topic. If you are already familiar with Mercurial you cat go directly to HgHowTos topic.

You will end up with a large number of directories representing top-level NetBeans projects. Most of them will be openable as projects in NetBeans.

Here's how to build it.

The build of NetBeans will be created in nbbuild/netbeans.

How To Find Useful APIs

Get the Platform Examples

Build Platform from Sources

To build platform run

cd $NB_SRC_ROOT
ant build-platform

Mining the NetBeans Source Code for Examples

Use the Mailing Lists

This How-To is based on GlassFish EJB Faq

How to call EJB from Java EE Application Client built on top of NetBeans Platform

Important: Application Client must be created as it is described in Java EE Application Client on top of the NetBeans Platform Tutorial otherwise this will not work

• create lookup method in some class in your module
• add entry to application-client.xml in application client module

Example

• for following lookup method in some class from your module:

protected mypkg.MySessionBeanRemote lookupMySessionBean() {
    try {
        javax.naming.Context c = new javax.naming.InitialContext();
        return (mypkg.MySessionBeanRemote) c.lookup("java:comp/env/ejb/MySessionBean");
    } catch(javax.naming.NamingException ne) {
        java.util.logging.Logger.getLogger(getClass().getName()).log(java.util.logging.Level.SEVERE,"exception caught" ,ne);
        throw new RuntimeException(ne);
    }
}

• there must be following entry in application-client.xml:

<ejb-ref>
    <ejb-ref-name>ejb/MySessionBean</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <remote>mypkg.MySessionBeanRemote</remote>
</ejb-ref>

How to call EJB from standalone module/NB platform based application

Call EJB on GlassFish

• ensure that $GLASSFISH_HOME/lib/appserv-rt.jar, $GLASSFISH_HOME/lib/appserv-ext.jar, $GLASSFISH_HOME/lib/appserv-deployment-client.jar, $GLASSFISH_HOME/lib/javaee.jar, $GLASSFISH_HOME/lib/jmxremote_optional.jar are on NB platform based application's classpath (startup classpath is not enough)
• ensure that the same applies to jar with EJB interfaces and its helper classes
• when using jars from GlassFish v1 or v1u1 - disable assertions (due to bug in GlassFish which should be fixed in GlassFish v2)
• add org.omg.CORBA.ORBInitialHost and org.omg.CORBA.ORBInitialPort JVM options to application's startup JVM options
• use lookup

Example

• add:

run.args.extra=-J-da -J-Dorg.omg.CORBA.ORBInitialHost=localhost -J-Dorg.omg.CORBA.ORBInitialPort=3700 \
               -cp:a $GLASSFISH_HOME/lib/appserv-rt.jar:$GLASSFISH_HOME/lib/appserv-ext.jar:\
                     $GLASSFISH_HOME/lib/appserv-deployment-client.jar:$GLASSFISH_HOME/lib/javaee.jar:\
                     $GLASSFISH_HOME/lib/jmxremote_optional.jar:someejb.jar

• add javaee.jar and jar with ejb interfaces to compile time dependencies for your module
• create lookup method for your bean in some class in your module:

// for EJB 3.0 bean
protected mypkg.MyBeanRemote lookupMyBeanRemote30 throws NamingException {
    javax.naming.Context ic = new javax.naming.InitialContext();
    return (mypkg.MyBeanRemote) ic.lookup("mypkg.MyBeanRemote");
}

// for EJB 2.1 and/or earlier
protected mypkg.MyBeanRemote lookupMyBeanRemote21 throws NamingException {
    javax.naming.Context ic = new javax.naming.InitialContext();
    Object remote = c.lookup("java:comp/env/ejb/MyBean");
    mypkg.MyBeanRemoteHome rv = (mypkg.MyBeanRemoteHome) PortableRemoteObject.narrow(remote, mypkg.MyBeanRemoteHome.class);
    return rv.create();
}

Platforms: all

If you want to test running with a different look and feel during development of your application, and you know it will be on the application's classpath, see the example in DevFaqPassCommandLineArgumentsAtDevTime for how to include --laf in the runtime arguments to your module suite.

@Override
public JMenuItem getMenuPresenter() {
    JMenuItem item = super.getMenuPresenter();
    item.setOpaque(true);
    item.setBackground(Color.BLUE);
    item.setForeground(Color.YELLOW);
    return item;
}

Note about using alternate components in the main menu: If you want your action to work properly on Mac OS, you probably don't want to return anything other than a JMenu or JMenuItem from getMenuPresenter() if you implement Presenter.Menu. In general, Swing allows you to treat menu popups as generic Swing containers you can put what you like into. This is not true at all of the Mac OS screen menu bar - it expects normal menu items, and will not handle unusual contents for menus.

It's pretty simple to change the font color, style or weight for your node's label. Simply override getHtmlDisplayName and provide some HTML in your return value. (An example can be found in this tutorial.) Here is another example:

public class MovieNode extends AbstractNode {

    private Movie movie;

    public MovieNode(Movie key) {
        super(Children.LEAF, Lookups.fixed(new Object[]{key}));
        this.movie = key;
        setName(key.getTitle());
        setDisplayName(key.getTitle());
        getHandle();
        setIconBaseWithExtension("org/nb/marilyn/pics/marilyn.gif");
    }

    @Override
    public String getHtmlDisplayName() {
        return "<b>" + this.getDisplayName() + "</b>";
    }
    
}

The javadoc for the HtmlRenderer class explains what subset of HTML is supported. You can also change the icon's node by overriding various methods such as getIcon(int type) or getOpenedIcon().

It's also possible, but far more difficult, to control other aspects of the node's appearance; for example, drawing a box around the node or changing its background color. To do this you must create or modify the explorer view in which the node is rendered. Fabrizio Giudici posted code that illustrates this on the dev@openide list.

autoupdate.services/libsrc/org/netbeans/updater/resources/updatersplash.gif

You can brand this in your application by following the instructions in this FAQ entry.

This FAQ item should be a companion to the main classpath documentation. Please refer to the original document for additional details.

Class loaders in the NetBeans platform

There are basically three main class loader types used in the platform. Most code is loaded by module class loaders. In special cases the "system" class loader can be used, when you need access to resources from unknown modules. Resources directly on the classpath from the launch script (mainly platform*/lib/*.jar) are loaded by the application loader. (There are also bootstrap and extension loaders in the JRE, and the platform has a special loader for a couple of JARs in platform*/core/*.jar.)

Most of the class loaders in the NetBeans platform are multi-parented class loaders. This means that the class loader can have zero or more parents. org.netbeans.ProxyClassLoader implements the search across multiple parents.

Module class loader

Every module loaded by the module system has its own class loader. This loader loads resources primarily from the module's JAR. The application loader is an implicit parent of each module loader.

The module loader is able to load from additional JARs (besides delegating to various parents):

• extensions - anything listed in the manifest attribute Class-Path of the module JAR
• locale extensions - JARs placed in a subdirectory locale relative to the original module JAR position, named by appending a locale suffix to the original name
• patches - JARs placed in a subdirectory patches/code-name-base relative to the original JAR position (can override module classes)

The implementation class is org.netbeans.StandardModule$OneModuleClassLoader.

System class loader

The "system" loader loads no resources on its own, but has as its parents all enabled module's class loaders. It is accessible via Lookup.getDefault().lookup(ClassLoader.class) or by using the fact that it is the context loader on all threads by default: Thread.currentThread().getContextClassLoader()

Application class loader

This class loader is set up by the launch script (or by javaws if running in JNLP mode). It can load classes from lib/*.jar in specified clusters. It is generally discouraged to use this loader for your own classes, but it is sometimes needed e.g. for Look & Feel classes (which must be loaded very early during the startup sequence).

Example

Take a very simple module a:

Manifest-Version: 1.0
OpenIDE-Module: org.netbeans.modules.a

and module b depending on a:

Manifest-Version: 1.0
OpenIDE-Module: org.netbeans.modules.b
OpenIDE-Module-Module-Dependencies: org.netbeans.modules.a
Class-Path: ext/library-b-1.1.jar

Classes in org-netbeans-modules-a.jar will be loaded in a's module class loader. Classes in both org-netbeans-modules-b.jar and library-b-1.1.jar will be loaded in b's module loader, and can refer to classes in org-netbeans-modules-a.jar.

Yes. In fact, once you have some code written, request the developer role on contrib.netbeans.org (you need to have an account and be logged in to see the link), so you have write access to CVS there, and go ahead and check it in. You will need to sign a Contributor Agreement to get CVS write access.

For more info on how to start module projects or join existing ones, see the contributing page on netbeans.org .

If you have initially written the module as a standalone module project using the NB 5.0 IDE, beware that the format for module projects inside the netbeans.org CVS tree is slightly different. To convert a standalone module project to a netbeans.org module:

1. . Close your module and shut down the IDE, just to be safe.

1. . Copy the module into the desired location in the netbeans.org CVS source tree.

1. . Open nbproject/project.xml and delete the line <standalone/>.

1. . Delete =nbproject/genfiles.properties=, =nbproject/platform.properties=, and =nbproject/build-impl.xml=.

1. . Open build.xml and change <import file="nbproject/build-impl.xml"/> to <import file="../../nbbuild/templates/projectized.xml"/> (assuming a second-level module like =contrib/foo=; adjust number of ../ occurrences as needed).

Now you ought to be able to open the new project in the IDE and work with it as usual.

If you had specified an explicit NBM license (=license.file=) before, you might just remove it - netbeans.org modules by default use nbbuild/standard-nbm-license.txt which is appropriate for any SPL module with no external (non-SPL) components.

If you had a module suite project with several module suite component projects, just discard the suite project (netbeans.org modules cannot reside in suites) and copy the component module projects into the netbeans.org CVS tree. You will be deleting <suite-component/> from project.xml and deleting suite.properties rather than platform.properties but the process is otherwise similar.

A future release of the module development support should permit you to simply select Move Project or Copy Project from the GUI and handle these format changes automatically.

Explorer views are generic Swing components, not subclasses of TopComponent , the Swing panel class that is used for top level components (tabs) in the main window. So an explorer view component is added to a TopComponent, using the TopComponent as a Swing container for the view.

A little bit of plumbing is needed to wire up an explorer view to the global Node selection so that code that is sensitive to selection such as context sensitive actions . Basically you want the TopComponent to expose the selection in your Explorer View so that when your view has focus, the global selection that affects everything will be whatever the user selects in your view.

In olden times, there was a convenient class called ExplorerPanel (now in org.openide.compat ) which would do this for you; due to a tragedy of being in the wrong package, it is now deprecated, but the required plumbing is not hard:

public class MyView extends TopComponent implements ExplorerManager.Provider {
    private final ExplorerManager manager = new ExplorerManager();
    private final JComponent view = new BeanTreeView();
    public MyView() {
        setLayout (new BorderLayout());
        add(view, BorderLayout.CENTER);
        manager.setRootContext(someNode);

        // Probably boilerplate (depends on what you are doing):
        ActionMap map = getActionMap();
        map.put(DefaultEditorKit.copyAction, ExplorerUtils.actionCopy(manager));
        map.put(DefaultEditorKit.cutAction, ExplorerUtils.actionCut(manager));
        map.put(DefaultEditorKit.pasteAction, ExplorerUtils.actionPaste(manager));
        // This one is sometimes changed to say "false":
        map.put("delete", ExplorerUtils.actionDelete(manager, true));
        // Boilerplate:
        associateLookup(ExplorerUtils.createLookup(manager, map));
    }
    // This is optional:
    public boolean requestFocusInWindow() {
        super.requestFocusInWindow();
        // You will need to pick a view to focus:
        return view.requestFocusInWindow();
    }
    // The rest is boilerplate.
    public ExplorerManager getExplorerManager() {
        return manager;
    }
    protected void componentActivated() {
        ExplorerUtils.activateActions(manager, true);
    }
    protected void componentDeactivated() {
        ExplorerUtils.activateActions(manager, false);
    }
}

The primary difference between the above code and ExplorerPanel is that ExplorerPanel automagically persisted paths from the selected nodes to the root, so that it could be deserialized on restart with the same selection it had before shutdown (assuming that selection still existed - this was never terribly robust).

-- Main.timboudreau w/ cut & paste from Jesse Glick - 17 Sep 2005

Note: Whenever you need to deploy an update, be sure you have incremented the module's specification version number and then repeat steps 2 and 3 above. Users should be able to easily install the updates you've published. There is more explanation of module versioning and dependencies elsewhere in this FAQ.

The Nodes API documentation provides some guidance, while chapter 14 of NetBeans: The Definitive Guide goes into greater detail. Although some parts of NetBeans: The Definitive Guide are now outdated, the portions related to the Nodes API are likely still relevant.

DataLoaders are factories for DataObjects. Typically there is a 1:1 mapping between file-type:DataLoader-subclass and a 1:1 mapping from files:DataObject instances for files that are visible in the UI. When a file is encountered, a DataLoader is found and used to produce a DataObject for that file.

Modules that provide the ability the system to open (or otherwise use) files of a particular type will register DataLoaders for those types. When the system needs to display a file in the UI, or when some code calls DataObject.find(someFileObject), the registered loaders are queried and one of them will claim it, and create a DataObject to represent it. So typically for each file type (as defined by file name extension, or XML subtype) there is a matching DataObject subclass.

DataLoaders are registered in the module manifest - for example:

Name: org/netbeans/modules/povray/PovDataLoader.class
OpenIDE-Module-Class: Loader

Note that the empty line above the Name: line must be present; create such entries at the bottom of the module manifest.

A DataObject represents one or more (typically only one) FileObjects. A DataObject knows what kind of a file it represents; it may represent the parsed contents of a file such as a .java file; or, as in the case of InstanceDataObject the file name may provide all the information it needs to be useful.

DataObjects are produced by DataLoaders, which modules register for specific file types. So for each file type, there is (usually) one DataLoader; and for each file of that type, there is (typically) one DataObject.

DataObjects are seldom referred to by type - if you are casting a DataObject to its implementation class, you are probably doing something wrong. This is a general rule for which there can be exceptions, but is especially true if you're doing the cast from code in a different module than the one in which the DataObject was defined. The usage pattern is to ask a DataObject for instances of interfaces that are the things your code will actually interact with. The method for doing this is dataObject.getCookie(Interface.class) (or in newer versions of NB, dataObject.getLookup().lookup(Interface.class)).

As a simple example, the NetBeans APIs define an interface org.openide.cookies.OpenCookie. It has one method, open(). That method will open the file in the editor. What exactly will happen when open() is called is entirely up to the module that implements the DataObject. The rest of the system does not need to know any of the implementation details - it just needs to know if the DataObject has an OpenCookie. If it does, then the Open action on its context menu can be enabled, and that action will call ((OpenCookie) theDataObject.getCookie(OpenCookie.class)).open().

The name cookie is historical and somewhat unfortunate; the getCookie() pattern is an older variation on the Lookup pattern for service discovery. The two are equivalent, with the exception that getCookie() requires all returned objects to implement the empty Node.Cookie marker interface, and Lookup can return any object. Expect getCookie() to be replaced with a new getLookup() method at some point in the future.

As suggested above, a DataObject may actually represent more than one file - so when you expand a folder in the UI, there may actually be fewer DataObjects in that folder than there are files. This is why, in the NetBeans IDE, a Swing form is represented by a .java file and a corresponding .form file, but the .form file is not visible in the UI; in the past, .properties files have also used this mechanism to present resource bundles in various languages as a single node in the files tree.

However, this ability to represent multiple files with a single DataObject is strongly discouraged for new code and will probably eventually be deprecated - it has serious negative implications for scalability.

There is a folder in the System Filesystem called Loaders. It is where various things are registered that apply to specific DataObject types. For example, there is a folder Loaders/text/x-java that contains things that pertain to Java files (notice that the path is a MIME type). It has an Actions subfolder where you can add actions to the popup menu for Java files.

You may not think of a folder as being a file type, but to NetBeans it is. There is a subfolder Loaders/folder/any/Actions which contains actions that should appear in the popup menu for folders. Just add your action in your layer file to that folder, i.e.

<filesystem>
  <folder name="Loaders">
      <folder name="folder">
          <folder name="any">
            <folder name="Actions">
               <file name="com-foo-module-MyAction.instance"/>
          </folder>
        </folder>
      </folder>
    </folder>
</filesystem>

No. Not if you want your module to work in the future. Copy the code instead. If it is a thing that seems generally useful, file an enhancement request requesting an API for the thing you need to do (and make sure there isn't already a supported way to do it).

Anything under org.netbeans.core is non-public, not an API, and subject to change without notice. An API is a contract - an agreement about compatibility. There is no such contract for this namespace, under any circumstances. The class or method you are using may not even exist in the future. Depend on it at your peril.

A perfect example of why not to do this is JProfiler's plugin for NetBeans - it broke very badly across releases because it needlessly depended on the implementation of DialogDisplayer rather than on the API class - so when that class moved, it could no longer link, so the module didn't work.

If you really must use some non-API classes to do what you need to do, use an implementation dependency (DevFaqImplementationDependency) - your module probably won't load in any version except the one it was built against, but at least your users won't get nasty surprises. And ideally, notify the maintainer of the thing you're depending on - they can give you a heads-up if they think they're about to make a change that will break your module.

Applies to: NetBeans 6.5

The NetBeans Dialogs API makes it easy to create consistent dialogs that behave as users would expect. But since you don't directly create the OK button, it may not be obvious how you can enable it or disable it.

You can enable the OK button by calling setValid(true) and disable it by calling setValid(false). This thread from the dev@openide list might also be helpful.

The Dialogs API provides support for dialogs and wizards.

Whenever you'd use JDialog or JOptionPane in Swing, using the Dialogs API provides some alternatives. These are easier to use as they automatically take care of centering and other display details, but also allow you to later plug in a different implementation of how they're actually "displayed." Instead of showing them on screen, for example, you could override the default DialogDisplayer class to specify your own that logged them to a printer or read them aloud using speech synthesis.

I'll illustrate three of the most common use cases. The first is when you want to simply show a dialog box with some text:

String msg = "There is something you should know..."
NotifyDescriptor nd = new NotifyDescriptor.Message(msg, NotifyDescriptor.INFORMATION_MESSAGE);
DialogDisplayer.getDefault().notify(nd);

For exceptions, you'll use a similar mechanism. The msg argument is optional here:

String msg = "Something bad happened..."
NotifyDescriptor nd = new NotifyDescriptor.Exception(throwable, msg);
DialogDisplayer.getDefault().notify(nd);

And to request simple user input:

String txt = "Name: ";
String title = "State your name";

NotifyDescriptor.InputLine input = new NotifyDescriptor.InputLine(txt, title);
input.setInputText("John Doe"); // specify a default name
Object result = DialogDisplayer.getDefault().notify(input);
if (result != NotifyDescriptor.OK_OPTION) {
    return;
}

String userInput = input.getInputText();

And finally, the DialogDescriptor subclass, handles complex cases (there are many variants here; see Dialog Descriptor's Javadoc for details):

JPanel form = new MyComplexForm();
String msg = "Something bad happened..."
DialogDescriptor dd = new DialogDescriptor(form, msg);
Object result = DialogDisplayer.getDefault().notify(dd);
if (result != NotifyDescriptor.OK_OPTION) {
    return;
}

// you can now examine the form's state...

*.settings files are similar to *.instance files (DevFaqInstanceDataObject), with the difference that they can contain serialized data rather than just default instances. They may also use custom persistence formats according to the Convertors API.

After the introduction of NbPreferences to replace SystemOption, very little new code uses these files, and they should be considered semi-deprecated. They are difficult and error-prone to use, and have a fair amount of overhead. The Window System still requires them to be used for TopComponent persistence.

*.shadow files are mainly used in the system filesystem (DevFaqSystemFilesystem) for configuration data. They are the functional equivalent of Unix symbolic links - a *.shadow file is a pointer to another file whose behavior in every respect except its path and file name is the same as the original.

*.shadow files are commonly used where only a single instance of an object is needed, but it must be registered in multiple folders. For example, a general Action is declared in the Actions/ folder of the System Filesystem. But the action also needs to appear in menus and toolbars, possibly other places. So, rather than create multiple instances of an action, one *.instance file (DevFaqInstanceDataObject) is created in the module's layer file (DevFaqModulesLayerFile), in the Actions/ folder. Then *.shadow files are created in all of the other places the *.instance file would be needed, pointing to the original file.

Declaring a .shadow file in the system filesystem looks like this:

<folder name="A">
    <file name="com-foo-mymodule-MyClass.instance"/>
</folder>
<folder name="B">
    <file name="Shadow1.shadow">
        <attr name="originalFile" stringvalue="A/com-foo-mymodule-MyClass.instance"/>
    </file>
</folder>
<folder name="C">
    <file name="anotherShadow.shadow">
        <attr name="originalFile" stringvalue="A/com-foo-mymodule-MyClass.instance"/>
    </file>
</folder>

Shadow files can also point to real files on disk. For example, the Favorites tab in the NetBeans IDE uses shadow files to link to real directories on disk.

To add a drop-down menu to a component in a toolbar, you can either extend CallableSystemAction and override public Component getToolbarPresenter(), or implement javax.swing.Action or any subclass thereof, and implement Presenter.Toolbar which defines that method.

You might want to create a JToggleButton, and when the button is pressed, show a JPopupMenu. (Also try org.openide.awt.DropDownButtonFactory.)

Example:

public class PickDrawingLineAction extends CallableSystemAction {
    private static JToggleButton toggleButton;
    private static ButtonGroup buttonGroup;
    private static JPopupMenu popup;
    private MyMenuItemListener menuItemListener;

    List handledCharts;

    public void performAction() {
        java.awt.EventQueue.invokeLater(new Runnable() {
            public void run() {
                toggleButton.setSelected(true);
            }
        });

    }

    public String getName() {
        return "Pick Drawing Line";
    }

    public HelpCtx getHelpCtx() {
        return HelpCtx.DEFAULT_HELP;
    }

    protected boolean asynchronous() {
        return false;
    }

    public Component getToolbarPresenter() {
        Image iconImage = Utilities.loadImage(
            "org/blogtrader/platform/core/netbeans/resources/drawingLine.png");
        ImageIcon icon = new ImageIcon(iconImage);

        toggleButton = new JToggleButton();

        toggleButton.setIcon(icon);
        toggleButton.setToolTipText("Pick Drawing Line");

        popup = new JPopupMenu();
        menuItemListener = new MyMenuItemListener();

        handledCharts = PersistenceManager.getDefalut()
                        .getAllAvailableHandledChart();

        buttonGroup = new ButtonGroup();

        for (AbstractHandledChart handledChart : handledCharts) {
            JRadioButtonMenuItem item =
                new JRadioButtonMenuItem(handledChart.toString());
            item.addActionListener(menuItemListener);
            buttonGroup.add(item);
            popup.add(item);
        }

        toggleButton.addItemListener(new ItemListener() {
            public void itemStateChanged(ItemEvent e) {
                int state = e.getStateChange();
                if (state == ItemEvent.SELECTED) {
                    /** show popup menu on toggleButton at position: (0, height) */
                    popup.show(toggleButton, 0, toggleButton.getHeight());
                }
            }
        });

        popup.addPopupMenuListener(new PopupMenuListener() {
            public void popupMenuCanceled(PopupMenuEvent e) {
                toggleButton.setSelected(false);
            }
            public void popupMenuWillBecomeInvisible(PopupMenuEvent e) {
                toggleButton.setSelected(false);
            }
            public void popupMenuWillBecomeVisible(PopupMenuEvent e) {
            }
        });

        return toggleButton;
    }

    private class MyMenuItemListener implements ActionListener {
        public void actionPerformed(ActionEvent ev) {
            JMenuItem item = (JMenuItem)ev.getSource();
            String selectedStr = item.getText();

            AnalysisChartTopComponent analysisTc =
                AnalysisChartTopComponent.getSelected();

            if (analysisTc == null) {
                return;
            }

            AbstractChartViewContainer viewContainer =
                analysisTc.getSelectedViewContainer();
            AbstractChartView masterView = viewContainer.getMasterView();
            if (!(masterView instanceof WithDrawingPart)) {
                return;
            }

            DrawingPart drawingPart =
                ((WithDrawingPart)masterView).getCurrentDrawing();

            if (drawingPart == null) {
                JOptionPane.showMessageDialog(
                        WindowManager.getDefault().getMainWindow(),
                        "Please add a layer firstly to pick line type",
                        "Pick line type",
                        JOptionPane.OK_OPTION,
                        null);
                return;
            }

            AbstractHandledChart selectedHandledChart = null;

            for (AbstractHandledChart handledChart : handledCharts) {
                if (handledChart.toString().equalsIgnoreCase(selectedStr)) {
                    selectedHandledChart = handledChart;
                    break;
                }
            }

            if (selectedHandledChart == null) {
                return;
            }

            AbstractHandledChart handledChart =
                selectedHandledChart.createNewInstance();
            handledChart.setPart(drawingPart);
            drawingPart.setHandledChart(handledChart);

            Series masterSeries = viewContainer.getMasterSeries();
            DrawingDescriptor description =
                viewContainer.getDescriptors().findDrawingDescriptor(
                    drawingPart.getLayerName(),
                    masterSeries.getUnit(),
                    masterSeries.getNUnits());

            if (description != null) {
                Node stockNode = analysisTc.getActivatedNodes()[0];
                Node node =
                    stockNode.getChildren()
                        .findChild(DescriptorGroupNode.DRAWINGS)
                        .getChildren().findChild(description.getDisplayName());

                if (node != null) {
                    ViewAction action =
                        (ViewAction)node.getLookup().lookup(ViewAction.class);
                    assert action != null :
                        "view action of this layer's node is null!";
                    action.view();
                }
            } else {
                /** best effort, should not happen */
                viewContainer.setCursorCrossVisible(false);
                drawingPart.setActived(true);

                SwitchHideShowDrawingLineAction.updateToolbar(viewContainer);
            }

        }
    }

}

The end result of this code is that we create a Java context for our JEditorPane. This context initializes code completion with a default class path, and that grants us access to the standard Java APIs (i.e. the code completion box can include classes such as java.lang.String, java.util.List, etc.). However, this context has no visibility into any additional jars nor Java projects. In order to expand this default Java context, you will need to create your own class path provider (see the "Java Support APIs" module).

First, let's take a look at some of the classes we'll be using:

• import java.io.File;
• import javax.swing.JEditorPane;
• import javax.swing.text.Document;
• import javax.swing.text.EditorKit;
• import org.netbeans.spi.java.classpath.ClassPathProvider; from the "Java Support APIs" module
• import org.openide.filesystems.FileObject; from the "File System API" module
• import org.openide.filesystems.FileUtil; from the "File System API" module
• import org.openide.loaders.DataObject; from the "Datasystems API" module
• import org.openide.text.CloneableEditorSupport; from the "Text API" module
• import org.openide.util.Lookup; from the "Utilities API" module
• import org.netbeans.api.java.source.ui.DialogBinding; from the "Java Source UI" module

Now we're ready to take a look at the actual code:

        JEditorPane editorPane = new JEditorPane();

        // This will find the Java editor kit and associate it with
        // our editor pane. But that does not give us code completion 
        // just yet because we have no Java context (i.e. no class path, etc.).
        // However, this does give us syntax coloring.
        EditorKit kit = CloneableEditorSupport.getEditorKit("text/x-java");
        editorPane.setEditorKit(kit);
        
        // You can specify any ".java" file.
        // If the file does not exist, it will be created.
        // The contents of the file does not matter.
        // The extension must be ".java", however.
        String newSourcePath = "tmp.java";

        File tmpFile = new File(newSourcePath);
        FileObject fob = FileUtil.createData(tmpFile);

        DataObject dob = DataObject.find(fob);
        editorPane.getDocument().putProperty(
                Document.StreamDescriptionProperty, 
                dob);
        
        // This sets up a default class path for us so that
        // we can find all the JDK classes via code completion.
        DialogBinding.bindComponentToFile(fob, 0, 0, editorPane);

        // Last but not least, we need to fill the editor pane with
        // some initial dummy code - as it seems somehow required to
        // kick-start code completion.
        // A simple dummy package declaration will do.
        editorPane.setText("package dummy;");

In order to get MimeLookup you have to supply MimePath. With the default MimeLookup implementation provided by Netbeans the contents of MimeLookup is defined by a hierarchical structure of folders on the system FileSystem. The structure starts in the Editors folder and then follows all the components of the MimePath you have supplied.

For example if you ask for MimeLookup for the following MimePath of text/x-java you will get Lookup with contents from the following folders:

    Editors/text/x-java
    Editors

As you can see MimeLookup for text/x-java contains not only editor features registered for the text/x-java mime type itself, but it also inherits general features registered for an empty MimePath (i.e. in the root of the hierarchy).

The inheritence algorithm used for composing MimeLookup for a given MimePath supports more than just simple inheritance from the root. It also supports compound mime types such as text/x-ant+xml and embedded mime types such as text/x-jsp/text/x-java.

Compound mime types

Let's have a look at the MimeLookup composition for a compound mime type text/x-ant+xml. The resulting Lookup will contain things registered in the following folders:

    Editors/text/x-ant+xml
    Editors/text/xml
    Editors

That's the reason why editor features provided by XML modules for general XML files work also for specialized, but XML-based, files.

Embedded mime types

The inheritance hierarchy becomes even more complicated when dealing with embedded mime types. Let's use a java scriplet inside a JSP page as an example of language embedding. The MimePath for the scriplet is text/x-jsp/text/x-java and its MimeLookup will contain features registered in the following folders:

    Editors/text/x-jsp/text/x-java
    Editors/text/x-java
    Editors

The algorithm for computing the inheritance tree for a particular MimePath combines all the above cases together and works always the same way no matter what feature you are going to look for in the resulting MimeLookup.

Applies to: NetBeans 6.0 and with some exceptions also to 5.0, 5.5
Platforms: All
See also:
What is MimeLookup?, What is MimePath?, MimeLookup API

    // Suppose you have javax.swing.text.Document
    String mimeType = NbEditorUtilities.getMimeType(document);

    // Suppose you have javax.swing.text.JTextComponent
    String mimeType = NbEditorUtilities.getMimeType(component);

Applies to: NetBeans 6.0, the algorithm in NbEditorUtilities.getMimeType(JTextComponent) works fine in 5.0 and 5.5, but the method is not public.
Platforms: All
See also: Editor Module API

EditorKit kit = CloneableEditorSupport.getEditorKit("text/x-java");

JEditorPane jep = new JEditorPane();
jep.setEditorKit(kit);

Applies to: NetBeans 6.0
Platforms: All
See also: CloneableEditorSupport.getEditorKit()

# How to get Lookup for java files?
MimePath mimePath = MimePath.parse("text/x-java");
Lookup lookup = MimeLookup.getLookup(mimePath);

# How to register instances (e.g. EditorKit) in the Lookup for java files?
<folder name="Editors>
  <folder name="text">
    <folder name="x-java">
      <file name="org-netbeans-modules-java-JavaEditorKitImpl.instance"/>
    </folder>
  </folder>
</folder>

Applies to: NetBeans 5.0, 5.5, 6.0
Platforms: All
See also: What is Lookup?, MimeLookup API

Since MimePath is required when you want MimeLookup and since MimeLookup is the way for pluging-in language specific editor features it is possible to provide features tailored specifically for any type of language embedding. If you want to know more about the contents of MimeLookup generally and for compound and embedded mime types, read more in How is MimeLookup composed?.

Applies to: NetBeans 5.0, 5.5, 6.0
Platforms: All
See also:
What is MimeLookup?, MimePath Javadoc, MimeLookup API

In short, the current NetBeans IDE (6.7) only provides limited support for changing application icons. Alternate solutions are described below, but NetBeans itself does not include any way to change the icon of the Windows launcher executable called <your branding name>.exe, nor does it provide a way to specify an .icns file for Mac OS X. There is already an enhancement request for Windows icon support: issue #64612.

'Application Icon' Images

Similar to toolbar icons, these files always use the .gif extension, regardless of their actual format. The frame.gif file is used for the smallest icon size of 16x16, which shows up in three places: the taskbar (Windows/Linux), in the upper-left corner of the application's title bar (Windows/Linux), and in the upper-left corner of most dialog windows (Windows/Linux). Another file called frame32.gif (which is not generated by the NetBeans Project Properties dialog) provides a 32x32 icon that shows up in the Alt-Tab menu on Windows. Lastly, the frame48.gif file provides a 48x48 icon that shows up in the Alt-Tab menu on Linux.

Windows Icons

If you want a simple commandline program to call as part of your Windows build process, the free ReplaceVistaIcon.exe from RealWorld Graphics works well, and can be invoked as simply as:

ReplaceVistaIcon.exe build\launcher\bin\<your branding name>.exe YourIconFile.ico

To do this automatically when building, simply place a copy of ReplaceVistaIcon.exe and <your branding name>.ico into your project's root directory (where build.xml is), and add the following to your suite's Build Script (build.xml) after the import line:

	<condition property="isWindows">
		<os family="windows" />
	</condition>

	<target name="build-launchers" depends="suite.build-launchers">
		<!-- Replace the icon for the Windows launcher exe. -->
		<antcall target="replaceWindowsLauncherIcon"/>
	</target>

	<!-- Windows-only target that replaces the icon for the launcher exe with our own icon. -->
	<target name="replaceWindowsLauncherIcon" if="isWindows" description="Replace the icon for the Windows launcher exe">
		<echo message="Replacing icon of Windows launcher executable."/>
		<exec executable="ReplaceVistaIcon.exe" resolveexecutable="true">
			<arg line="build/launcher/bin/${app.name}.exe ${app.name}.ico"/>
		</exec>
	</target>

If you would prefer to simply do it manually and need a GUI resource editor, try the free programs:

• http://www.angusj.com/resourcehacker
• http://www.wilsonc.demon.co.uk/d10resourceeditor.htm

If you need an editor for creating/converting both Windows .ico files and Mac .icns files, try the excellent, free program IcoFX.

Mac Icons

In order to replace it automatically when building, name your .icns file as <your branding name>.icns and place a copy into your project's root directory (where build.xml is), and add the following to your suite's Build Script (build.xml) after the import line:

	<!-- Override to change Mac application icon. -->
	<target name="build-mac" depends="suite.build-mac" description="Build Mac OS X Application">
		<property name="nbdist-contents.dir" value="${dist.dir}/${app.name}.app/Contents"/>
		<property name="nbdist-resources.dir" value="${nbdist-contents.dir}/Resources"/>

		<!-- Replace the icns file. -->
		<delete file="${nbdist-resources.dir}/${app.name}.icns"/>
		<copy tofile="${nbdist-resources.dir}/${app.name}.icns" file="${app.name}.icns" />
	</target>

This is a simplified version of Tonny Kohar's (of http://www.kiyut.com) build script posted on: http://forums.netbeans.org/ptopic10504.html

In general you cannot. See issue #7551.

If you created the Explorer view (e.g. you created a BeanTreeView or similar and put it in a Swing panel of some sort) then you can use ExplorerManager.setSelectedNodes)] and more rarely TreeView.expandNode to display a given node in your tree (The node must be a descendant of the current root node. You cannot construct a new "similar" Node and hope to select it).

If you did not create the Explorer view then there is no reliable way to find it. However you might try scanningTopComponent.Registry.getOpened() for instances of ExplorerManager.Provider and looking for appropriate nodes that way. Such tricks must be done with care - the fact that you can find the component to do this does not imply that the author of the component intends that it be there forever, remain of the same type, continue implementing ExplorerManager.Provider or anything else. Check nulls, check casts, be prepared for it not to work on future versions.

In the particular case of making a new file wizard, you can and should ask for the file(s) you create to be selected when the wizard finishes, simply by returning them from WizardDescriptor.InstantiatingIterator.instantiate()

Applies to: NetBeans 5.0, 5.5, 6.x

There is thing that is explorer; the name is historical - very old versions of NetBeans had a window named "Explorer" that contained a tree of files and other components. Colloquially, the term is still used to refer to the area in the left side of the main window where the Files and Projects tabs live in the IDE - but NetBeans has long since stopped having names for or frames around tabbed containers. There is an API in NetBeans which contains Swing components that can render Nodes , which is called the Explorer API.

Once you have a component to show Nodes , you will need to set the root node whose children it will display (some views show the root node, some don't, in some cases you can set whether it does or not).

Presumably you have an ExplorerManager set up for your view - just get that and call setRootContext (someNode) and the view will display it.

You do not directly set the Node that is displayed by an Explorer view component (Swing components that display Nodes ) by calling a method on that component. Rather, you set that kind of information by finding the manager for that component - it's what is in charge of what node is displayed, selected, etc.

The manager may be explicitly set on an Explorer view, but usually this is not necessary. When you add a view component (such as a BeanTreeView ) to a Swing container, it will search backward through its parent, it's parent's parent, and so forth, looking for a component that implements ExplorerManager.Provider (an interface with one method - getExplorerManager()). That ExplorerManager is what will determine what is displayed.

While this may seem like an unnecessary layer of indirection, it is actually quite powerful: It makes it possible to very simply create master-detail views ala Windows Explorer: Just add two views to a JPanel subclass that implements ExplorerManager.Provider . It is very easy to set it up so changing the selection in one causes the other one to show the children of the selected object - just the way selecting a folder in Windows Explorer does.

See also the ExplorerManager javadoc . The FAQ about showing explorer views in the main window includes sample usage of ExplorerManager.

An explorer view is a GUI component which can display a Node and (optionally) its child nodes. While Nodes are, by definition, a tree structure, explorer views are much more than just JTrees. Here is a list of the components available:

• BeanTreeView - the classic tree view, as seen in the Projects and Files tabs in the IDE
• ListView - a JList based node view component - you can see it in the right hand list in
• ChoiceView - a ComboBox based explorer view - older versions of the NetBeans IDE used this to display a list of methods in the editor toolbar
• ContextTreeView - like a BeanTreeView, but sets its manager's explorered context. The "master" part of a master-detail component that uses two views.
• MenuView - a JMenu view of a Node and its children
• TreeTableView - a TreeTable view of a Node and its children, in which the left column of the table is a tree of nodes, and the other columns display/edit a specified set of properties of those nodes
• OutlineView - replacement for TreeTableView
• IconView - a view similar to that of the left pane in Windows Explorer - a table of equidistant icons. Not currently used anywhere in the IDE's UI.
• PropertySheetView - doesn't show Nodes per-se at all, but rather, shows a property sheet for editing a Node's properties

With the exception of PropertySheetView, all of these classes live in the package org.openide.explorer.view (sources in openide/explorer in NetBeans' CVS).

An explorer view's content is controlled by its ExplorerManager - you don't set the root node directly on the view component, you use its manager. This is so that more than one view can share a single manager, to do master-detail views (for example, the first page of the New Project wizard is one such view - the right hand panel displays children of the left hand panel's selection).

There are a number of advantages to using Nodes and Explorer Views

• it is possible to create a rich UI with very little UI code
• they integrate well with standard menu/toolbar actions that are sensitive to selection
• they contain convenient and well tested features (start randomly typing in a tree or list view - a little popup will appear and search for a matching node)
• there is a lot of logic built into NetBeans for creating Nodes simply and easily, for example, from any POJO JavaBean and persisting the things they represent, so you can do a lot with very little code by using Nodes and Explorer Views

A common usage is to get a Node for some folder on disk or in the configuration filesystem, optionally create a FilterNode to filter out some child nodes of it or its children, and display that.

How to store external libraries in the NetBeans Hg repository

In the spirit of building on the shoulders of giants, NetBeans takes advantage of external libraries which are not developed on netbeans.org. Those libraries are either open-source software, or binary-only software but with liberal licenses. A few examples: Apache Tomcat; JUnit; JavaHelp (runtime); javac compiler; JSR-88 interface classes.

For convenience, these libraries are stored in the same Hg repository as the source code under CDDL/GPL. They are placed in well-known places in the source tree. The license text is associated with the binary file to make it clear which terms and conditions the users/developers must agree to besides being compliant with the CDDL/GPL itself. Only source code covered by the CDDL/GPL (or BSD, in the case of samples) can be hosted in the http://hg.netbeans.org/main/ repository. As the NetBeans Hg tree is growing, we need to initiate stricter rules and check that all external binary files have a correct associated license. There are also several recommendations on avoiding unnecessary additions of binary files into Hg.

The build system will automatically check if all binary files under <nbmodule>/external are stored correctly with appropriate license and all required information. <nbmodule> means NetBeans project module, e.g. external is on same level as nbproject. Failing to do so will result in a broken build!

Questions:

• I need to store some binaries in my own VCS repository. Should I follow same rules as well? No, you do not have to. You can store your binaries under release/modules/ext/, more details are described in harness/README
• My binary is not a library and I need to store it somewhere else. It has been also created under CDDL. Then you should update nbbuild/antsrc/org/netbeans/nbbuild/extlibs/ignored-binaries
• How can I check all is all right? Run ant verify-libs-and-licenses

Here are the rules NetBeans committers must follow when placing external libraries into NetBeans Hg:

• Legal due diligence must be observed before using a new external library, to make sure that the library license is suitable for use in NetBeans.
• All external binaries should be stored under a subdirectory named <nbmodule>/external, and nowhere else. (For the contrib repository, the path will be contrib/<nbmodule>/external.)
• External binaries are versioned in Hg. ExternalBinaries describes how the actual binary content is stored outside Hg, while the Hg repository actually tracks the SHA-1 hash of the binary. ant bootstrap suffices to download all external binaries in a fresh checkout.
• Each external binary should have a corresponding license file stored in the same directory as the binary itself. You will upload the binary itself through the Web form, but will add the license file directly to Mercurial (e.g. hg add external/somelib-x.y.z-license.txt).
• The name of the binary must follow the convention somelib-x.y.z.jar or somelib-x.y.z.zip where x.y.z is the version number. The corresponding license file must be named somelib-x.y.z-license.txt.
• All license files should be in UTF-8 encoding with appropriate line and paragraph breaks. The license file must end with a newline. Lines should not exceed 80 characters.
• The license file should follow a specific format. Details below.

License file format

License files should be in the following format:

Name: SomeLib
Version: 1.2.3
Description: Library for management of some blah blah blah.
License: Apache_V20 [see note regarding normalized names]
OSR: 1234 [OSR number, refer to LFI previously; Sun-internal legal]
Origin: http://www.xyz.org [where file(s) were downloaded from]
Files: xyz.jar, xyz-doc.zip, xyz-src.zip [optional; see below for explanation]
Source: URL to source [mandatory for LGPL, otherwise optional]
Comment: needed until NB runs on JDK 6+ [optional: why is this library here?]

Use of SomeLib version 1.2.3 is governed by the terms of the license below:

[TEXT OF THE LICENSE]

As hinted at above, the OSR field refers to a Sun-internal system. Those contributing patches from outside of Sun can leave this field blank. Also note that a single license file may cover multiple JAR files from the same project. For example, if your patch depends on a third-party library distributed under the same license as two JARs, you will only need one license file and can account for both of these JARs in its Files header.

If the Files header is not present, then a license name-x.y.z-license.txt must correspond to a binary name-x.y.z.jar or name-x.y.z.zip. If present, it should list the names of all binaries to which it corresponds.

The header fields are read during the build process and removed. Therefore this information will not appear in the final build or NBMs.

Template-based licenses

If there is template-based license (like BSD one http://www.opensource.org/licenses/bsd-license.php), e.g. the license file has several ad hoc places to be updated accordingly. The template itself should have the license file stored under nbbuild/licenses with well-defined tags __TAGNAME__; these tags will be replaced during the build. Template-based licenses stored along with the binary in Hg must have be in original form as they came with binary:

Example BSD License, as it is stored in nbbuild/licenses:

Copyright (c) __YEAR__, __OWNER__

All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    * Neither the name of __ORGANIZATION__ nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Example BSD License, as it is stored in Hg along with binary:

Copyright (c) 2007, NetBeans

All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    * Neither the name of NetBeans nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

NBM build, managing correct license for NBMs

Required licenses should be listed in project.properties. (There still must be a license along with the binary in Hg.) The new entry will be called extra.license.files, where the license files will be relative to project basedir, e.g.

extra.license.files=external/x-1.0-license.txt,external/y-2.0-license.txt

As a convenient shortcut for the common case that you simply want to copy some files to the target cluster (but cannot use the release directory since third-party binaries are involved), you may use the newly introduced release.* Ant properties which should be specified in project.properties. Each key names a file in the source project; the value is a path in the target cluster. Any such pair will automatically:

• Copy the source file to the cluster. (No need to override the release Ant target.)
• Cause the target file to be included in the NBM file list. (No need to add to extra.module.files.)
• In the case of release.external/* properties, cause the associated binary to be included in the NBM license. (No need to override the nbm Ant target or add to extra.license.files.)

release.external/beansbinding-0.6.1.jar=modules/ext/beansbinding-0.6.1.jar
release.external/beansbinding-0.6.1-doc.zip=docs/beansbinding-0.6.1-doc.zip

release.external/stuff-1.0.zip!/stuff.jar=modules/ext/stuff-1.0.jar

Normalized names

There will be a license repository under nbbuild/licenses where all licenses in use should be available. Each license type will be given a unique name: Apache_V11, Apache_V20, etc. This name must be referred to in the License field. This allows us to count licenses and file names and build a 3rd-party README as well as NBMs. Make sure that the license for a new binary is correctly included under nbbuild/licenses. If there is no existing license of the same type, it must be reviewed prior to committing.

NetBeans Samples

If a sample is created for NetBeans itself, it can be packaged into ZIP file and should not be in the external/ folder. To ensure tests correctly skip over it, the owner must add an entry for the binary into nbbuild/antsrc/org/netbeans/nbbuild/extlibs/ignored-binaries and include a brief explanatory comment.

Alternately, it may be preferable to keep the sample files unpacked directly in Hg, and create the ZIP during the module's build process (either directly into the cluster, or into build/classes for inclusion inside the module). This not only prevents tests from warning about it, but can make it easier to update minor parts of a sample and may make version control operations more pleasant.

The sample itself must be covered by the BSD license; the license must be included in every file (excepting binaries such as icons).

Copyright (c) <YEAR>, Sun Microsystems, Inc.

All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:

* Redistributions of source code must retain the above
  copyright notice, this list of conditions and the following 
  disclaimer.
* Redistributions in binary form must reproduce the above
  copyright notice, this list of conditions and the following
  disclaimer in the documentation and/or other materials
  provided with the distribution.
* Neither the name of Sun Microsystems, Inc. nor the names of
  its contributors may be used to endorse or promote products
  derived from this software without specific prior written
  permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE. 

If sample is not created solely for NetBeans, e.g. bundled in a third-party product and covered by a separate license, it must follow the same rules as for any other binary library.

Common mistakes

A binary file has no associated license. (E.g. xyz.jar is missing xyz-license.txt.)

A binary file has an associated license, but does not maintain the naming convention, or has typos. (E.g. xyz.jar with xy-license.txt.)

Licenses are not pure text. (E.g. they contain HTML.)

A binary file is duplicated in several places. Before adding a new library, please make sure that library is not already available in the Hg tree. If it is, check if the version there is suitable for you; if so, communicate with the owner regarding possible upgrades and/or available packages if they are not available. You might need to move the library to a parent cluster as well. If you do depend on such a third cluster, make sure your module is marked as eager, otherwise it will get disabled.

The names of the binary and its license file will change when the binary is upgraded to a newer version. Update project.properties (or, less commonly, build.xml) to reflect this change.

Before moving from my own repository to NetBeans Hg, I used release/modules/ext/ for storing my binary libraries. They need to be moved into external/ unless the library itself is covered by CDDL, build script, licenses etc., must be updated accordingly!

How do I know if some other modules is relying on the source location of my external binaries? Answer: it's not hard to find out. For example, if you want to know who uses httpserver/external, try this (Unix / Bash syntax):

cd nb-main
for f in */{build.xml,nbproject/*.{properties,xml}}; \
  do fgrep -H httpserver/external $f; done

Implementation work

Interesting files from build:

1. Current license summary
2. VerifyLibsAndLicenses test
3. CreateLicenseSummary test
4. Unreferenced or overreferenced files

Static verification of Hg

Part of regular build. Only pays attention to Hg-controlled files in the checkout, so can run on a built source tree without becoming confused. Writes results in JUnit format for easy browsing from Hudson.

• Look for *.jar not in */external/ dirs (with some exceptions).
• Every license file has at least mandatory headers.
• Every license file has lines at most 80 characters long, etc.
• For LGPL, must have Source header.
• Check that every external *.jar or *.zip has a matching license. (Or it can be mentioned in Files header of some license.)
• Every binary has a version number in name.
• No binary occurs more than once, under any name (so check by CRC-32 or SHA-1 etc.). (Look inside ZIP files for nested JARs.)
• Every license file's License field refers to something in nbbuild/licenses.
• The file in nbbuild/licenses exactly matches the body of the license file. Whitespace-only changes are permitted, e.g. rewrapping lines to make them fit. For licenses with templates (e.g. BSD License) any tokens between two underscores can match whatever character sequence.

Things done in IDE build

Generate a third-party JAR & license summary. Find every binary in the IDE build which is either present directly in some */external dir or present inside a ZIP in some */external dir. For every such binary, retrieve the license from nbbuild/licenses. Make a single document listing all of the binaries and licenses.

Verify that no such binary is present in more than one place.

Saved as THIRDPARTYLICENSE-generated.txt in development builds.

Things done in NBM build

nbbuild/templates/projectized.xml (netbeans.org modules only) will look up extra.license.files and use them in Info.xml.

release.* properties honored (see above).

Golden files

nbbuild/build/generated/external-libraries.txt is generated directly from external dirs.

Does not yet take account extra.license.files correctly. Also may not be a complete list of libraries.

Applies to: NetBeans 6.5

Attributes are routinely used in the System Filesystem for providing additional configuration data. In pre-4.0 NetBeans, they were relatively commonly used for user files on disk. They still may be used for user files, but this is now discouraged - the infrastructure has been changed to store all attributes in the userdir rather than sprinking .nbattrs throughout the users disk; using attributes for user files at this point does have negative performance implications.

See FileObject.getAttribute and FileObject.setAttribute .

1. Reread all relevant documentation to see if you have missed anything important.
2. If you are unsure whether the behavior is really incorrect, you can ask on dev@openide.netbeans.org. Do not be too shy to file a bug, though; it is just as easy to close an invalid bug report as it is to reply to the mailing list.
3. If at all possible, figure out how to reproduce your bug. From scratch: the assignee of the bug report cannot see your computer and has no idea what you are working on or why. Try to make a minimal, self-contained test case that anyone could run to see the bug in action. Often a suite project is a good test case - attach a ZIP of sources, including nested module projects. If you know how to write a unit test for the buggy module, that is ideal, but this can require some deeper knowledge of NetBeans internals. Sometimes a bug occurs that just cannot be easily reproduced - it is still fine to file a bug, but include as much diagnostic information as you can and do not be surprised if it does not get fixed.
4. Read: Issue Reporting Guidelines
5. For general background you may also want to read: How To Ask Questions The Smart Way
6. File a bug report and include at least
   1. Some background on what you are trying to accomplish and why.
   2. Some kind of test case to demonstrate the bug.
   3. Instructions for running the test case.
   4. What you would expect to see happen.
   5. What you actually see happen.
7. Be patient as the bug is assigned and evaluated, and provide additional information if requested. If all goes well it should be fixed for a future NetBeans release. The evaluator may also be able to offer some workarounds for use in current releases.

As of NetBeans 6.7, org.openide.filesystems.FileChooserBuilder makes this easy. Pass a Class or unique String key to the constructor of a FileChooserBuilder. The next time the same key is passed, the new file chooser will automatically be rooted on the directory selected the last time.

Related: DevFaqFileEditorContextMenuAddition

Related: DevFaqFileContextMenuAddition

FileObjects differ from java.io.File in certain ways:

• You don't generally ever have a FileObject representing a file that doesn't really exist
• You can listen for changes on FileObjects
• FileObjects can have key-value pairs of ad-hoc attributes associated with them

They are part of the Filesystems API ; the javadoc for FileObject can be found here .

A lot of applications show some UI that displays folders of files; also a lot of NetBeans UI is created by showing virtual files in the configuration filesystem.

The basic mechanism is this: Some folder is shown in the UI; files of known types have their own icons, menu items and behavior.

The way NetBeans detects files is this: 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're actually seeing is Nodes, which are the things that provide actions, localized names, etc. to files or other things.

In between Nodes and FileObjects are DataObject s. 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 (provided by different modules which implement support for file types - for example, the Image module makes it possible to recognize and open .gif and .png files) for files with different extensions, XML files with different DTDs, etc.

Modules that recognize different file types install DataLoaders - factories for file-type-specific DataObjects.

So what really happens is that, when a folder is expanded, the system asks each known DataLoader, "Do you know what this is?" The first one that says "Yes" gets to create the DataObject for the file (in reality the recognition process is a little more optimized than it sounds here, but it adds up to this description).

In order to actually display something for the each file, the system calls DataObject.getNodeDelegate() for each DataObject, and the Nodes are what you actually see in the UI.

NetBeans uses virtual files to refer to the users files on disk, and to refer to its own configuration files. If you used the NetBeans IDE 3.6 or earlier, you may remember that the way you constructed your classpath used to be by "mounting" filesystems - folders on your disk.

Filesystems are gone from the UI, but are alive and well under the hood in NetBeans.

A FileSystem is a hierarchical tree of folders and files. A filesystem has a "root folder", which may contain files and other folders. "Files" (FileObjects ) in a Filesystem may be actual files on disk, or entries in JAR file, or entries in an XML file, or anything else that walks and talks like a file that someone has implemented the Filesystem interface for.

In the NetBeans Platform there are implementations of FileSystem for

• plain disk files and folders
• ZIP/JAR files
• XML files in a predefined format ("layers")
• a block of memory with no backing store
• proxies for merging other filesystems with optional behavior overrides

Filesystems are used both to represent user files on disk, and also to represent configuration data internal to NetBeans - the System Filesystem . This is one of the reason that it takes only minimal code to create a GUI view of the system filesystem - the same file recognition code that recognizes user files, gives them actions, icons and display names is what recognizes internal configuration data.

Especially in the case of the System Filesystem, it can be useful to think of a Filesystem as a "namespace" in which objects (which may contain data or represent Java objects) live - for the System Filesystem, the fact that the entries in it are referred to as files is incidental.

As of NetBeans 4.0 you will rarely work directly with the FileSystem class.FileUtil.toFileObject is the normal way of getting a file object from a disk file.FileUtil.getArchiveRoot is the normal way of getting file objects from a JAR or ZIP file. In NetBeans 4.x FileSystem implementations are also used for version control integration but the 5.0 CVS support no longer uses this system.

Applies to: NetBeans 4.0, 4.1, 5.0, 5.5, 6.0, 6.1

Node n = ...;
DataObject dob = (DataObject) n.getCookie(DataObject.class);
if (dob == null) {
    // not a file node
} else {
    // could also get all files in the data object, if desired:
    FileObject fo = dob.getPrimaryFile();
    // do something with fo
}

Also see DevFaqFileVsFileObject if you need java.io.File for some reason.

Using InstanceCookie (note that if you have an entire folder of .instance files, there's a more efficient way to get all of them):

DataObject dob = DataObject.find (theDotInstanceFileObject);
InstanceCookie ck = (InstanceCookie) dob.getCookie (InstanceCookie.class);
MyObject obj = (MyObject) ck.instanceCreate();

-J-Dorg.openide.util.NbBundle.DEBUG=true

ant index-layer-paths

to see which module (by code name) contributes each layer file (or folder), including menu items and so on. You can also just look at the trunk version of this file here.

In NetBeans 6, if the folder is in the System Filesystem (as it almost always will be), it is very simple:

Lookup myObjects = Lookups.forPath ("path/to/folder/in/sysfs");

In NetBeans 5.x and earlier, to get a folder from the system filesystem and get all of the .instance files of some particular class in it, instantiated as java objects:

FileObject myFolder = Repository.getDefault().getDefaultFileSystem().findResource (
    "MyFolder/MySubFolder");
DataFolder df = DataFolder.findFolder (myFolder);
FolderLookup lkp = new FolderLookup (df);
Collection <? extends MyType> c = lkp.lookupAll (MyType.class);

If you are using NetBeans 5.x, the lookup code above should read:

Lookup.Template template = new Lookup.Template (MyType.class);
Collection c = lkp.getLookup().lookup (template).allInstances();

Starting with NetBeans 6.7 the following changes in the Windows launcher were introduced - WinNB67Launcher.

You can browse the Javadoc online (this link always points to the latest development version).

You can also download the Javadoc for a particular NetBeans release:

• Go to the nightly build download site: http://bits.netbeans.org/dev/nightly/
• Click the link for the build you want.
• You will be shown an index page which makes no mention of how you can get a ZIP file or a source archive, so ignore it.
• Add "zip/" to the end of the URL in your browser's address bar and hit enter. In other words, the complete URL might look like this: http://bits.netbeans.org/dev/nightly/2008-06-24_02-01-08/zip/
• There are about a dozen links on that page. The one you want is begins with netbeans-trunk-nightly and ends with -javadoc.zip; click that link to download the Javadoc archive.

Finally, you can go to the update center (Tools > Plugin Manager) in the NetBeans IDE and request the NetBeans API Documentation module, which bundles Javadoc matching your IDE release. Use View > Documentation Indices (Help > Javadoc References in NetBeans 6.x) to see the overview pages for API sets currently used by your open projects. The IDE should also automatically display this Javadoc in code completion popups.

Applies to: NetBeans 5.x, 6.x

Platforms: all

But if you're still here, you may be asking where is the platform? Binary distributions of the platform are not being made available from version 6.0 onward (and issue #124372 filed to bring them back was closed without any reasonable explanation). So if you want a platform binary, you'll have to create one yourself.

Building the platform is not difficult, but it's not intuitive either. To start, you will need to download the platform source ZIP file and unpack it to some directory. Open a command prompt to that directory and change to the nbbuild subdirectory. From there, issue the following command:

   ant -Dcluster.config=platform build-platform

If you're using Java 6, you'll need to add an extra property:

   ant -Dcluster.config=platform build-platform -Dpermit.jdk6.builds=true 

But be aware that it is not guaranteed to build under Java 6 due to language changes or compiler bugs. It is unlikely you will encounter such a problem in the platform build, though it has certainly been known to happen in the IDE build. If you find something that won't compile under Java 6 but does compile under Java 5, file a bug report (preferably with a patch) about it so it can be corrected. Meanwhile, you can use Java 5 to compile -- even when Java 6 is first in your path -- by using the nbjdk.home system property to point to your Java 5 installation:

   ant -Dcluster.config=platform build-platform -Dnbjdk.home=c:/devtools/jdk/jdk-1.5.0_u15

This will build the platform into the netbeans subdirectory (i.e. nbbuild/netbeans). You can zip or tar up the netbeans directory to create a ZIP distribution.

It's also possible to create platforms based on a different subset of the NetBeans project. Hints for doing this can be found here:

• Working with NetBeans Sources

Why would you want to build your application on a separate platform instead of the IDE as a platform?

Using the IDE is certainly easier, but there are inherent dangers associated with developing against your own IDE as the platform. In particular, another developer on your team may have a different version of the IDE, have different modules/clusters installed or even have simply named the platform something different in the Platform Manager. This can result in a broken build or the introduction of unwanted features. It also makes doing an automated build, such as through Hudson or CruiseControl, far more difficult.

If you want to avoid these problems, you can check the platform you want to build against into source control and then set the netbeans.dest.dir and harness.dir properties in your suite's nbproject/platform.properties file to point to the platform and harness, respectively. Building from a known version checked out from source control avoids these problems and makes it possible to historically reproduce any build. I show example values for these below:

# NOTE: You must remove the nbplatform.default line which might already exist in this file.
# Also note that editing the properties of your suite via the suite customizer (dialog)
# can add that line back in, so you'll need to watch for this and delete it again in this case.

# where the suite is located; you don't need to change this.  It exists 
# to allow us to use relative paths for the other values
suite.dir=${basedir}

# the path to the NetBeans IDE or platform binary we want to build against 
# (e.g. if building against the IDE, this points to the directory created when 
# you unpack the IDE zip file).  this example assumes your platform directory 
# is parallel to the suite directory, but you can change it to suit your needs
netbeans.dest.dir=${suite.dir}/../platform

# path to the build harness you want to use.  This is typically in the 
# harness subdirectory of your platform, but you could point to a directory
# containing customized build scripts if you want to.
harness.dir=${netbeans.dest.dir}/harness

Update for NBM projects generated by NetBeans 6.7 and later

If you have generated your projects in IDE version 6.7 and later, you have to modify the above described method slightly (6.5.1 and earlier projects compile against newer platform/harness without changes). You can distinguish "newer" project by the presence of cluster.path property in nbproject/platform.properties file or simply by the fact that an attempt to build a suite with above described platform.properties results in error:

.../harness/suite.xml:60: When using cluster.path property, remove netbeans.dest.dir, enabled.clusters and disabled.clusters properties
from platform config, they would be ignored.

In such case you have to replace netbeans.dest.dir, enabled.clusters and disabled.clusters properties with new property cluster.path, e.g.:

# NOTE: You must remove the nbplatform.default line which might already exist in this file.
# Also note that editing the properties of your suite via the suite customizer (dialog)
# can add that line back in, so you'll need to watch for this and delete it again in this case.

# where the suite is located; you don't need to change this.  It exists 
# to allow us to use relative paths for the other values
suite.dir=${basedir}

# just a helper property pointing to the same location as netbeans.dest.dir did before;
# Referenced only in this properties file, has no meaning for NB harness.
platform.base=${suite.dir}/../platform

# classpath-like list of absolute or relative paths to individual clusters 
# against which you want your suite to build; Note that you can use 
# "bare", i.e. not numbered cluster names, which simplifies later transitions
# to newer version of the platform. E.g:
cluster.path=${platform.base}/platform:\
     ${platform.base}/ide:\
     ../otherSuite/build/cluster

# path to the build harness you want to use.  This is typically in the 
# harness subdirectory of your platform, but you could point to a directory
# containing customized build scripts if you want to.
harness.dir=${platform.base}/harness

Note that the content of cluster.path is not limited to clusters from NB platform, you can add clusters from other suites, standalone modules, etc. This allows to reuse non-platform modules in several RCP apps. More on module reuse here, other details about setting up cluster.path can be found in harness/README.

Generally if it's a third party library (you didn't write it, you can't or don't want to change it), you will want to use a wrapper module (see DevFaqWrapperModules). An NBM file (a module packaged for delivery over the net) can contain more than one JAR, so all your libraries can be included in a single file that packages your module.

Note you can multi-select JARs in the New Library Wrapper Module wizard.

Advanced stuff

You can add libraries manually to a standard module; or add additional libraries to an existing library wrapper module. The relevant data is in the project.xml for the module. What you would do is add entries similar to this one for each JAR.

<class-path-extension>
    <runtime-relative-path>ext/hexedit.jar</runtime-relative-path>          
    <binary-origin>release/modules/ext/hexedit.jar</binary-origin>
</class-path-extension>

Note if you want these libraries to be usable outside of the module they're declared in, then you must add the relevant packages to the list of public packages for that module.

See also

• Packaging A Distributable Java App
• German version

If you cannot even use new harness and/or IDE, you have to use suite chaining, build your own platform and depend on it. See harness/README file for details. See also HowToReuseModules.

• How do I set or modify the language encoding for a project?

http://www.netbeans.org/issues/show_bug.cgi?id=153793

Be sure that what you really want to be doing is implement FileSystem . Unless you really need to access objects in a database, remote server, or some other such storage as if they were files, you are probably heading in the wrong direction.

If you do need to implement a FileSystem, you should probably start with AbstractFileSystem - it handles a lot of knotty locking semantics correctly and will save you a lot of time, effort and bugs.

OpenIDE-Module-Module-Dependencies: some.other.module > 1.5

OpenIDE-Module-Module-Dependencies: some.other.module

OpenIDE-Module-Module-Dependencies: some.other.module = 3

OpenIDE-Module-Implementation-Version: 3

Implementation dependencies cause special problems for Auto Update. (Some background information is available in NetBeans API & Module Versioning Policy / Numbering Scheme for Updates.)

The problem is that when an implementation version of a module published to an update server changes, any modules declaring implementation dependencies on it must also be published, with dependencies on the new version of the base module. Furthermore, the Auto Update client has just one method for deciding whether an NBM on a server is an "update" relative to what you already have installed: if its specification version is larger. So consider the following snapshot of an update center. (The syntax is not what the actual XML file looks like, just an abbreviated version that shows parts relevant to this example.)

[Monday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Implementation-Version: 070120

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Implementation-Version: 070120
OpenIDE-Module-Module-Dependencies: infrastructure = 070120

These two modules were built at the same time and could be installed together into a NetBeans instance. So far so good.

Now consider what happens when the developer of guifeature adds a major new feature and decides to publish a new version, 1.1. The next day's build produces

[Tuesday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Implementation-Version: 070121

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.1
OpenIDE-Module-Implementation-Version: 070121
OpenIDE-Module-Module-Dependencies: infrastructure = 070121

Again, these two modules could be installed together.

But what if a user connected to the update center on Monday and downloaded both modules, and then connects again on Tuesday looking for updates? infrastructure is still listed as 1.0 so Auto Update ignores it (1.0 is "already installed", after all). guifeature 1.1 is however a possible update. What if you install this update? The module system will refuse to enable guifeature because it requests infrastructure = 070121, whereas you have infrastructure = 070120. Oops!

The solution (short of not using implementation dependencies at all) is to use the NetBeans build harness to compute a specification version. The developer removes OpenIDE-Module-Specification-Version from manifest.mf in the source projects for both modules. manifest.mf for infrastructure instead will get

OpenIDE-Module-Implementation-Version: 1

(only positive integers 1, 2, ... are supported!). And nbproject/project.properties for both modules will get the specification version in a new form:

spec.version.base=1.0.0

The IDE's GUI for module projects lets you do all this without editing metadata files manually; just click the option Append Implementation Versions Automatically in the Versioning panel of the Properties dialog.

(The extra .0 is required for modules in the NetBeans distribution. When sources are branched for a release, spec.version.base is incremented to 1.0.1, 1.0.2, ... for each release on the branch. "Trunk" (development) changes increment the first or second digits, e.g. 1.1.0, 1.2.0, ...)

The effect of using spec.version.base is that our AU snapshots now look like this instead:

[Monday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0.0.1
OpenIDE-Module-Build-Version: 070120
OpenIDE-Module-Implementation-Version: 1

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.0.0.1
OpenIDE-Module-Implementation-Version: 070120
OpenIDE-Module-Module-Dependencies: infrastructure = 1

[Tuesday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0.0.1
OpenIDE-Module-Build-Version: 070121
OpenIDE-Module-Implementation-Version: 1

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.1.0.1
OpenIDE-Module-Implementation-Version: 070121
OpenIDE-Module-Module-Dependencies: infrastructure = 1

The update to guifeature is now safe; it can still use infrastructure from Monday. Note the new "build version" tag which is used only for diagnostics, not for dependencies.

If there is actually a change in the signature of anything in infrastructure that might affect guifeature, then the developer merely needs to increment the implementation version in infrastructure/manifest.mf:

[Wednesday]

OpenIDE-Module: infrastructure
OpenIDE-Module-Specification-Version: 1.0.0.2
OpenIDE-Module-Build-Version: 070122
OpenIDE-Module-Implementation-Version: 2

OpenIDE-Module: guifeature
OpenIDE-Module-Specification-Version: 1.1.0.2
OpenIDE-Module-Implementation-Version: 070122
OpenIDE-Module-Module-Dependencies: infrastructure = 2

If the user connects to the update center on Wednesday, the wizard will display both modules as needing to be updated - which is exactly what you want.

How is this system enforced? For one thing, attempts to use inherently unsafe implementation dependencies, or incorrect uses of spec.version.base, should produce warnings during the module build process. So look at the output of Ant once in a while and see if the build harness is telling you something.

There is also a continuous builder at http://deadlock.netbeans.org/hudson/job/nbms-and-javadoc/ which (among other things) tries to build NBMs for all modules in the NetBeans standard distribution plus those experimental "alpha" modules normally published on the update center for development builds. If you commit changes to experimental modules this build will be triggered; failures are mailed to broken_builds@netbeans.org, which all developers of modules in netbeans.org ought to subscribe to.

This builder uses an Ant task <verifyupdatecenter> to detect dependency problems among NBMs. There are two checks:

1. Can the NBMs just built all be enabled together? (synchronic consistency)
2. Suppose I had connected to the update center produced by the previous successful build and installed everything, and now I connected again to this build's update center and asked for all updates. Would any updated modules be broken, due to dependencies on new versions of other modules which were not updated? (diachronic consistency)

The second check is what will catch a lot of mistakes in usage of implementation dependencies as described above. Unfortunately it is not feasible to run the second check as part of an offline build process in your own source checkout, as it depends on a build of older sources; so you will need to commit changes and wait for the next build to verify them.

Generally there are two possible solutions to a test failure from this stage:

1. Remove the implementation dependencies; switch to friend dependencies or public APIs.
2. Ensure that all implementation dependencies are against positive integers (not dates), and that spec.version.base is used on both sides of the dependency, as described above.

In either case, to fix a test failure you will generally also need to increment the specification versions of modules on both sides of the dependency.

Applies to: NetBeans 5.x, 6.x

Platforms: all

In NetBeans infrastructure, *.instance files result in InstanceDataObjects. InstanceDataObjects can supply InstanceCookies, which in turn instantiate the object. So, code to actually get an instance of an object declared in the system filesystem (DevFaqSystemFilesystem) would look like this (plus error checking):

public static Object getTheObject(String pathInSystemFilesystem) throws Exception {
    return DataObject.find(
        Repository.getDefault().getDefaultFileSystem().findResource(pathInSystemFilesystem)).
        getLookup().lookup(InstanceCookie.class).instanceCreate();
}

A much easier way to get all instances of objects in a folder exists:

for (WhatISaidToPutHere instance :
        Lookups.forPath("MyFolder").lookupAll(WhatISaidToPutHere.class)) {
    // ...
}

Note that a default constructor is not required in an XML layer; you can also use a static method, using the following syntax:

<file name="ObjectTypes.instance">
  <attr name="instanceCreate" methodvalue="org.netbeans.core.ui.UINodes.createObjectTypes"/>
  <attr name="instanceOf" stringvalue="org.openide.nodes.Node"/>
</file>

See also: DevFaqDotSettingsFiles

Yes. See the JavaHelp Integration API which describes how to include JavaHelp documentation in a module under Help > Contents; and you can provide rich context help rather easily, linking into the same documentation.

There is an IDE wizard for creating a help set for your module.

Applies to: NetBeans 5.x, 6.x

Platforms: all

It's also worth noting that the JavaHelp implementation in NetBeans IDE 6.5.x and earlier seems to require the .html file extension.

Keybindings are specified in yet another folder in the system filesystem . The folder Shortcuts/ contains .instance files or .shadow files (shadow files are like symlinks to another file in the system fs) - these map to Actions.

The file name for the action (.instance or .shadow) file in Shortcuts/ is used to specify what keys are bound. This is done using an emacs-like syntax for specifying keybindings - e.g., CA-P equals Ctrl-Alt-P.

For a full listing of the hard-coded and cross-platform prefixes for key definitions, see the javadoc for Utilities.stringToKey() - that and its analogue, Utilities.keyToString() are used to encode and decode these.

There are special modifier characters which map to Command on Mac and Ctrl on PC, Ctrl on Mac and Alt on PC. You should use those unless you're really sure your app will never be used on macintosh or never be used by someone with a non-English macintosh.

Here is an example of what a layer file might look like if you bound the Ctrl+Shift+Equals sequence to the com.tomwheeler.example.fooviewer.FooAction action:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.0//EN"
  "http://www.netbeans.org/dtds/filesystem-1_0.dtd">

<filesystem>
  <folder name="Actions">
    <folder name="View">
      <folder name="FooViewer">
        <file name="com-tomwheeler-example-fooviewer-FooAction.instance" />
      </folder>
    </folder>
  </folder>

  <folder name="Shortcuts">
     <!--
        set up a shortcut key for executing the Foo Action:
        Ctrl + Shift + Equals on Linux and MS Windows, but Command + Shift + Equals on a Mac
     -->
    <file name="DS-EQUALS.shadow">
      <attr name="originalFile" stringvalue="Actions/View/FooViewer/com-tomwheeler-example-fooviewer-FooAction.instance"/>
    </file>
  </folder>
</filesystem>

For an existing release you can look at e.g. KeymapProfileFor60 to see the specification.

If you are developing a module for NetBeans development builds, you can just look at this file in the section Shortcuts/. This will show all global keybindings being used by modules in the standard IDE as well as experimental update center in http://hg.netbeans.org/main/ and http://hg.netbeans.org/main/contrib/ as of a few hours ago.

Editor-specific keybindings are listed in Editors/*/*/Keybindings/ folders, which is unfortunately harder to browse through.

Be conservative about adding new keybindings; they are a precious resource. Be careful with bindings using Alt, as these often clash with mnemonics, Linux window manager shortcuts, etc. If at all possible, use a multistroke binding: for example, Shortcuts/D-J R C.shadow binds the 3-stroke sequence Ctrl-J R C.

Answer:
In NB 6.0 and 6.1, the Platform includes only the following 3rd party libraries and licenses:

1. 1. JavaHelp 2.0_05 (GPLv2 with Classpath Exception)
2. 2. Script-API (GPLv2 with Classpath Exception)
3. 3. Swing Layout 1.0.x (LGPL)
4. 4. JNA 3.0.x (LGPL)

#2 and #3 are only required for compatibility with JDK 1.5. If you can afford to require JDK 6 or later, those two libraries are not necessary.

However, the above list applies only if your only dependencies are on the content of the 'platform' cluster (folder). If your application depends on other parts of the NetBeans IDE (e.g. the 'ide', or 'java' cluster) there may be derived dependencies on other 3rd party libraries. Such as scenario would require a more thorough investigation.

The DataObject.Registry in LoadersAPI gives you a set of modified DataObjects. You can also add a listener and be notified when the set of modified objects changes.

As this operates on DataObjects you will first need to get a DataObject for your FileObject using DataObject.find() . Or you can take the modified DataObjects and do dataObject.getPrimaryFile().

(Wondering what this is about? See the general FAQ item on keybindings).

There should be no Alt-bound keyboard shortcuts on the mac ever - it is used on international keyboards as the compose key (for a long time, we didn't know it, but Norwegian and French users could not type } or { in NetBeans - kind of limits the usefuless of a Java IDE).

All standard shortcuts should be bound with wildcard keys - e.g., in the layer, not AS-P for Alt-Shift-P, but OS-P, which will map to Alt-Shift-P on PC and Ctrl-Shift-P on mac. For Ctrl/Command, in the layer put DS-P instead of CS-P to bind conditionally to ctrl on PC and command on mac.

All Alt-bound keybindings in the IDE are specified with O so that they are rebound to Ctrl on mac, because they will interfere with typing in a lot of locales (the real way to think about it is "the mac does not have an Alt key" - it does but it is a composition key - you can't use it).

Any alt-bound keybinding on mac is a bug. If you use the logical syntax for keybindings, your app will always work intuitively on any platform.

Note that the mapping handling does skip key combinations that simply can't work on Mac - for example, Command-H and Command-Q are always consumed by the OS, so D-H and D-Q map to Ctrl-H and Ctrl-Q, respectively, everywhere.

Lookup is a mechanism for finding instances of objects. It is pervasively used in NetBeans APIs. The general pattern is that you pass a Class object and get back an instance of that class or null. See the Javadoc for links to articles describing its inspiration and purpose.

The simplest way to think of Lookup is that it is a Map where the keys are Class objects and the value for each key is an instance of the key class.

There is the global lookup which is used to find objects (often, but not always, singletons) that are registered throughout the system. Also, many types of objects have a method getLookup() that enables other code to get things specific to that object. In particular, Nodes and Project objects have a Lookup.

The primary purpose of Lookup is decoupling - it makes it possible to use generic objects to get very specific information, without having to cast objects to a specific type. Confused yet? It's simple. Take the example of OpenCookie - it has one method, open() that will open a file in the editor.

Say that I want to write some code that will open the selected file when the user does something. It could be an Action, a button, or maybe my code has just created a file and I want to open it. This is what I will do:

Node[] n = TopComponent.getRegistry().getActivatedNodes();
if (n.length == 1) {
   OpenCookie oc = n[0].getLookup().lookup(OpenCookie.class);
   if (oc != null) {
      oc.open();
   }
}

One can even write this code more simply, without the Nodes API at all, using Utilities.actionsGlobalContext():

OpenCookie oc = Utilities.actionsGlobalContext().lookup(OpenCookie.class);
if (oc != null) {
    oc.open();
}

The power of all this is in the level of decoupling it provides: My code that wants to open the file does not have to know anything at all about what happens when the file is opened, or what kind of file it is, or what module supports opening it. And the module that supports opening it does not need to know anything about who is going to open it. They both simply share a dependency on the abstract interface OpenCookie. So either one can be replaced without affecting the other at all.

A good example of this is in the POV-Ray tutorial. It launches an external process that generates a .png file. When the process ends, it wants to open it, so it does the following:

FileObject fob = FileUtil.toFileObject(new File(pathWePassedToProcess));
if (fob != null) {  //the process succeeded
   DataObject dob = DataObject.find(fob);
   OpenCookie oc = dob.getCookie(OpenCookie.class);
   if (oc != null) { //the Image module is installed
      oc.open();
   }
}

The fact is that it is the Image module that makes it possible to open .png files in NetBeans. But the POV-Ray tutorial does not need to know or care that the Image module exists, or what it does - it simply says "open this".

The common pattern you'll see for Lookup usage is one where there are three components:

• Module A is pure API - it provides some interfaces
• Module B depends on A and implements those interfaces, providing them from a Node or Project or such
• Module C wants to display some UI or do something with objects that implement those interfaces. It also depends on A, but does not need to know about B at all; either can be replaced independently, and the other will still function.

For global services, the model is more simple - typically there will be some singleton object, implemented as an abstract class:

public abstract class GlobalService {
   public abstract void doSomething(Something arg);
   public static GlobalService getDefault() {
     GlobalService result = Lookup.getDefault().lookup(GlobalService.class);
     if (result == null) {
        result = new NoOpGlobalService();
     }
     return result;
   }
   private static class NoOpGlobalService extends GlobalService {
      public void doSomething(Something arg) {}
   }
}

Some other module entirely actually registers an implementation of this interface in the default Lookup. StatusDisplayer is a good example of this pattern.

What if multiple objects of the same type should be available?

Collection<? extends SomeIface> c = Lookup.getDefault().lookupAll(SomeIface.class);

Note: In NetBeans versions prior to 6.0 you need to use Lookup.Template as the lookupAll method is not present yet.

The Lookup.Result can be listened on for changes in the result of the query. It is often useful to think of a Lookup as a space in which objects appear and disappear, and your code can respond as that happens (the following code uses the NB 6.0 lookupResult method - just use the pattern above with the Lookup.Template for NetBeans 5):

class ObjectInterestedInFooObjects implements LookupListener {
   final Lookup.Result<Foo> result;  //result object is weakly referenced inside Lookup
   ObjectInterestedInFooObjects() {
        result = someLookup.lookupResult(Foo.class);
        result.addLookupListener(this);
        resultChanged(null);
    }
    public void resultChanged(LookupEvent evt) {
        Collection<? extends Foo> c = result.allInstances();
        // do something with the result
    }
}

Another question is, on the side that's providing the lookup, if you have a collection already, how can you expose that in a Lookup. For that, you can create your own AbstractLookup and use InstanceContent to provide the collection of objects that belong in your Lookup.

Objects in a Lookup often are not instantiated until the first time they are requested; depending on the implementation, they may be weakly referenced, so that if an object is not used for a while, it can be garbage collected to save memory. So Lookup additionally enables lazy instantiation of objects, which is useful for performance reasons.

getCookie() (circa 1999) is specific to Nodes and DataObjects. It uses the same pattern, but all objects returned by it will implement the empty Node.Cookie marker interface.

The down-side to both of the above is that they specify the return type. In the case of Node.Cookie, in practice, this meant that anything that might possibly need to be provided by a DataObject or Node needed to implement this silly marker interface, forcing it to have a dependency on the Nodes API, or a wrapper Cookie class had to be created to provide the underlying object, which just added useless classes and noise.

Lookup is the most modern and generic version of this pattern, and probably the final one. It offers two advantages:

1. Its return type is java.lang.Object, so it can be used directly with anything
2. Having objects own a lookup rather than directly providing a lookup(Class c) method makes it easier to replace or proxy the Lookup of some object

• The META-INF/services/ Lookup contains all objects registered by modules via the Java Extension Mechanism - putting files in the META-INF/services/ directory of their module JARs, normally done using @ServiceProvider
• The contents of the Services/ folder of the System (configuration) Filesystem (this is harder and somewhat deprecated)

Objects contained in lookup are instantiated lazily when first requested.

Here is the usual usage pattern:

1. A central "controller" module defines some interface, e.g.

package controller.pkg;
public interface MyService {
    void doSomething();
}

2. Each module which wants to implement that service depends on the controller module which defines the interface, and creates and registers an implementation:

@ServiceProvider(service=MyService.class)
public class MyImpl implements MyService {
    public void doSomething() {....}
}

It is also possible to declaratively mask other people's implementations and declaratively order implementations so some will take precedence.

3. The controller finds all implementations and uses them somehow:

for (MyService s : Lookup.getDefault().lookupAll(MyService.class)) {
    s.doSomething();
}

More About Lookup

• DevFaqLookup
• Extension Points Tutorial
• Javadoc for Lookup

Applies to: NetBeans 6.7

Dne Monday 26 November 2007 17:37:48 Rob Ratcliff napsal(a):
> For the bus we developed, we could subscribe by a specific type, for all
> subclasses of a type or for certain message header attributes of an
> event. We also had a bus per "session" (the GUI could display multiple
> sessions/workspaces using tabs -- equivalent to a JMS topic)  so that
> only events related to that session would be delivered. And, like I
> mentioned earlier, there was support to register as a "GUI" listener or
> a "business" listener so that events would automatically be delivered in
> the correct thread to avoid EDT lockup and rendering issues.
>
> I'd be interested in hearing what you and others think about these types
> of capabilities and how they compare to the NetBeans paradigms.

I've been thinking about this for a while and I believe that there is event bus like system in NetBeans. It is Utilities.actionsGlobalContext()

We have our event bus and it is accessible via Utilities.actionsGlobalContext(). Indeed it may not be perfect, but it plays exactly the role described in the presentation. Menu, Toolbar, etc. listen on it, while somebody else updates it.

Indeed, there could be some improvements. We do not support merging of events or network access, but if one really cares, there is a way to plug into the system. All one needs to do is to implement ContextGlobalProvider One sample implelemention is in openide/windows and second in imagine.dev.java.net.

I've heard a complain that...

> This is a central listener, not an event bus

... however this boils down to a question: How do you envision an event bus? It is a place to contain events or objects that somehow appear in the system. It allows anyone to selectively listen on what is happening in the bus

So in fact event bus is a central listener. Just like Utilities.actionsGlobalContext().

Indeed it could be improved. Is there anyone who would like to contribute in improving our actionsGlobalContext? If so, what should be done?

Hi Jaroslav,

I think it'd be useful to define exactly what an event bus is (like you 
mentioned),  what use cases it supports and how NetBeans supports these 
use cases currently and how it might support these in the future.

I used an EventBus approach in my last project  for receiving 
asynchronous data events from the Network (such as position updates, 
network status events) and internal events such as service status 
(network disconnected) and other state change events such as "sensor 
network reconfigured"...essentially when it made more sense to use a hub 
and spoke communication model rather than a point-to-point.  There could 
be multiple instances of the EventBus, which used a  EDT type of model 
(dispatcher thread/queue) and supported subscriptions by type (any event 
derived from a base class)  or property of the header. 

Since the "Lookup Library" allows you to uncouple senders from receivers, and allows receivers to be notified of changes, I consider it as a small event bus.

I consider "local lookups" as a small event bus, where you can listen to different "event topics". In the previous case, it would probably be enough to dedicate on Lookup for the network events and create various types holding enough information about the events. The you could add/remove/change the content of the lookup and deliver events about such changes.

The instances 
could be looked up globally or injected into a given component. It 
supported "business" and "GUI"  subscriptions to automatically deliver 
the event in the correct thread. If I did it again,  I'm  thinking I'd 
use a JMS style API that supported a Hibernate style OQL subscription.
(I have some more details here: 
http://developers.sun.com/learning/javaoneonline/j1sessn.jsp?sessn=TS-3723&yr=2007&track=2)

The EventBus talk given at JavaOne 2006 had some great use case examples:
EventBus
https://eventbus.dev.java.net/HopOnTheEventBus-Web.ppt

These frameworks provide some other use cases and API examples:

D-Bus
http://www.freedesktop.org/wiki/Software/dbus
http://www.freedesktop.org/wiki/IntroductionToDBus

JUIPiter
 http://juipiter.sourceforge.net

Bradlee Johnson's ReflectionBus
 http://sourceforge.net/projects/werx/

Jasper-Potts - Why Spaghetti Is Not Tasty: Architecting Full-Scale 
Swing Apps, 2007 JavaOne Conference, TS-3316
http://developers.sun.com/learning/javaoneonline/j1sessn.jsp?sessn=TS-3316&yr=2007&track=2

(Also see the JMS API and the OMG COS Notification Service API.)

I don't have much time to spend a lot of time coding on the side right 
now, but I'd be happy to help define requirements and use cases if that 
would be useful to you.

Thanks!
Rob

DataObject does not yet support a getLookup() method, but is expected to do so in the future.

You can simulate this behavior in the meantime by using InstanceContent and AbstractLookup. Simplified typical usage:

public SomeObject {
   private InstanceContent content = new InstanceContent();
   private final AbstractLookup lkp = new AbstractLookup(content);
   
   public someMethod() {
      ic.set (someCollection...);
   }

   public Lookup getLookup() {
      return lkp;
   }
}

This is how you create a lookup with dynamic content of your choosing. See also Tom Wheeler's TodoListManager for an example of some code that illustrates how to do this.

DialogDisplayer displayer = DialogDisplayer.getDefault();

public static DialogDisplayer getDefault() {
    DialogDisplayer dd = (DialogDisplayer) Lookup.getDefault().lookup(DialogDisplayer.class);

    if (dd == null) {
        dd = new Trivial();
    }

    return dd;
}

#-org.netbeans.core.windows.services.DialogDisplayerImpl
com.tomwheeler.example.SpecialDialogDisplayerImpl

More information about this and other Lookup-related topics, including how to set the order of registered services, can be found in the Utilities API documentation.

It is not uncommon to be subclassing an class, such as TopComponent or Node which has a method getLookup(), and to need to add to or filter the original Lookup's contents. There are a number of convenience factories and classes which make it easy to do this:

• ProxyLookup - a Lookup which takes an array of Lookups and merges them together. Typical use is taking an existing lookup and providing it plus a lookup created with one of the convenience methods below
• Lookups.fixed(Object... arr) - a static method that creates a Lookup with an array of persistent objects as its contents
• Lookups.singleton (Object single) - a static method that creates a Lookup with one object as its content
• AbstractLookup - a Lookup which can have dynamic content - use it in conjunction with InstanceContent, which you can add/remove things from

If you need to customize a Node's lookup, read the FAQ item on how to do that.

As noted in the overview of Lookup, a Lookup can contain more than one instance of a given class; Lookup is often used for singletons, but not exclusively for singletons. For example, in the Projects API , there is a class called ProjectFactory that recognizes different types of user projects on disk; each module that provides a project type registers another factory in the system.

So the inevitable question is, if there are two instances of X in a Lookup, and I call lookup(X.class), which one do I get?

The answer is, it's undefined - don't do that. The next inevitable question is, but how can that be?

A Lookup makes no assumptions about what's in it, or what you might want to put in it, or how many of anything there should be. That contract is an agreement between whoever tells you that you should get an instance of X from some Lookup and you. If they document that there will only be one, use Lookup.lookup(Class); if they document that there can be more than one, use Lookup.lookup(Lookup.Template) and iterate the results.

In practice this is a non-problem - anything you are going to try to find in a Lookup is going to document whether it is supposed to be a singleton or not.

1. it is impossible to enforce dependencies . With Lookup, a module's code cannot request an object unless it can access the object's class, and it won't be able to access the object's class unless it declares a dependency on the API module that defines it. (A <T> Map<Class<T>,T> would do the same job as Lookup.)
2. The class of values in a map can change without notice - so if you have (SomeIface) foo = (SomeIface) globalMap.get("foo"), some new version of the module that provides "foo" can change the return type, causing ClassCastException s; with Lookup, you cannot ever get an object that is not of the type you passed in the request - so Lookup's approach is more robust. (Again, a generics-aware Map might be able to solve this.)
3. Lookup supports listening to changes in the result.
4. Lookup supports multiple instances for one key. (Sort of like <T> Map<Class<T>,List<T>> )

There are some other capabilities of Lookup (such as getting classes of results without instantiating them, and naming result items) but these are rarely used in practice.

Lookup is very powerful, yet simple and generic; people quickly learn to love it, once they realize what it can do.

There are a number of places Lookup is commonly found/used in NetBeans. Generally, if you have found some class and you are wondering where on earth you get an actual instance of one of those, the answer is probably "from something-or-other's Lookup".

Common cases:

• Lookup.getDefault()() - you want to find some global singleton or all instances of a particular object registered in the system
• Project.getLookup() - provides objects specific to a project. The typical pattern is, you have used FileOwnerQuery to get the Project that owns some file, and now you want to find something like the classpath (from the Project's ClassPathProvider, which lives in its Lookup)
• Node.getLookup() - this is how you get things like syntax trees, open and save interfaces and other miscellaneous stuff from Nodes representing files or other things
• TopComponent.getLookup() - if you are writing a UI component, and want to affect the global selection, but your component doesn't display nodes and you don't have any use for Nodes, you probably want to provide your own Lookup here with whatever you want to include in it (things like OpenCookie, SaveCookie, objects your other UI code may want to track if you're doing a master-detail view, etc.)
• Utilities.actionsGlobalContext() returns a Lookup which represents the global "selection context" in NetBeans. It is a ProxyLookup which proxies the lookup of whichever TopComponent currently has focus. So if you listen for changes in the presence or absence of a particular type in this lookup, you will receive appropriate changes whenever the backing Lookup being proxied changes.

Description of declarative MIME resolve can be found in this document. In most cases it should be enough to resolve files only by their extensions as the wizard does (see ext element). Other types of resolution can be more time expensive, so use them only exceptionally. Useful can be file name matching, file content matching or magic matching for binary files. Also consider existence of exit element intended for negative matching which can skips next conditions.

Applies to: NetBeans 6.1+, pattern and name elements to 6.7+

Related: DevFaqFileRecognition

Here is an example of a wizard that creates a number of files. This is the layer file that declares it (look at emptyLibraryDescriptor).

You may wish to reuse a standard GUI panel for picking a folder and name, as in Templates.createSimpleTargetChooser.

The NetBeans 5.0 module development support has a (meta-)wizard New Wizard. Choose New File for Registration Type and follow the wizard steps.

Applies to: NetBeans 5.0, 5.5, 6.X

If the problem causes OutOfMemoryError, it is possible to customize the JVM to provide a memory dump automatically whenever an OutOfMemoryError is thrown. FaqNetBeansAndOOME describes what options can be used for this. If you are developing modules, it is a very good idea to set the option -J-XX:+HeapDumpOnOutOfMemoryError.

If the memory leak is not so aggresive to fill all the available memory and cause an OutOfMemoryError, it is still possible to use jmap to generate the same dump. Running full GC before you create this dump can be a good idea as it can strip the size of dump file and remove some unimportant objects from the snapshot. You can do this by turning memory toolbar on (do a right click in toolbar area and check Memory). Repeating this several times can even collect large amounts of data held in various caches throug soft or weak references and make it easier to browse the dump.

Analyze the problem.

Alternately, you can use the JDK's tool jhat. It will start simple web server and you can use a web browser to see the data. There are many functions starting with lists of classes with numbers of objects and their size, navigation between references, finding of reference chains from GC root to certain objects. JavaScript can be used to express more complex queries.

Other tools

INSANE is a home-grown tool that is useful for analysis of memory content and also can be used in automated tests - so once you have fixed a memory leak, you can write a test that will fail if the memory leak is ever recreated. NbTestCase.assertGC is all you need to know.

DTrace can be used to monitor object allocation and garbage collection. Nice article about using DTrace with the HotSpot provider: Java and DTrace

Tips and tricks

Common leaking objects

There are some typical classes where it should be easily possible to tell what the appropriate number of their instances in memory should be, and if these are leaking there is a serious problem:

• Projects - it means instances of all subclasses of org.netbeans.api.project.Project
• Editors (or TopComponents) - it can be useful to check for org.openide.text.QuietEditorPane instances to see if closed editors can release substantial part of associated memory. If the editor component is held it often means that associated editor support is held too linking to parsing data, sidebars providing versioning information and probably also project metadata. It is also possible to look for instance of org.openide.windows.TopComponent if there is some suspicion or better to search for its particular subclasses. Generally there will be always certain numbers of TopComponents.
• Documents - somewhat related to editors. An important class where you can start is org.netbeans.modules.editor.NbEditorDocument.
• Top-level windows - undisposed dialogs can be a problem as these hold native resources that can be limited in the system.
• ClassLoader - we need to be very careful and check that class loaders created dynamically during runtime can be GC'ed when they are no longer used. Without this the result is OOME signaling that perm gen area is full.
• CompilationInfo (java.source module) - related to Java infrastructure. An important class where you can start is com.sun.tools.javac.code.Symtab, which is a singleton in a javac instance.

Leaks vs. retained memory

There are two different ways how memory can be wasted: leaks and improper retention of memory.

Leaks are cases when repeated invocation of certain activity creates new set of objects that cannot be reclaimed after activity is finished. The biggest problem is accumulation of these objects that leads to increased memory usage and after a long enough time leads to OutOfMemoryError. The nature of this error is that it leaves data structures of an application in undefined state so anything executed after this moment may lead to unexpected results.

Retained memory is memory occupied by objects that were created to serve some purpose but these objects are held longer than necessary. This may mean that some action has to be performed that flushes these objects or they will remain in memory until the end of the session. An example of the former is LRU caches (often holding last component in UI, files or projects). A common example of the latter is resources like parsed bundles or images statically referenced in classes that use them.

-J-Dnetbeans.debug.heap can make profiling easier as it more quickly releases references to collapsed nodes.

If you have the Timers module enabled (normally it is in dev builds), click its button in the Memory toolbar to get a summary of interesting live objects and statistics.

Platforms: All

java.lang.ClassCastException: Implementation cannot be cast to Interface
        at Factory.newInstance (Factory.java:123)

module A: Interface, Factory
module B > A: Implementation implements Interface
module C: Interface, Factory
module D > A: Implementation implements Interface

Interface i = (Interface) Class.forName("Implementation", true,
    Thread.currentThread().getContextClassLoader()).newInstance();

An especially silly variant of this problem, known to occur at least in Xerces, is that Implementation actually resides in the same JAR as Interface and Factory, and is the standard impl almost everyone uses unless overridden somehow - yet Factory loads it by name from the CCL rather than simply loading it directly using e.g. new Implementation().

The usual workaround is to wrap the problematic call(s) in a dynamic block:

ClassLoader orig = Thread.currentThread().getContextClassLoader();
Thread.currentThread().setContextClassLoader(SomeReferenceClass.class.getClassLoader());
try {
  Factory.load(...);
} finally {
  Thread.currentThread().setContextClassLoader(orig);
}

Note: NetBeans forbids ambiguous delegations. (Issue 118020) If a class could be loaded from two (or more) places, it will not be loaded at all. This does not solve your problem but it at least ensures it gets reported more reliably and with a descriptive message rather than an odd ClassCastException.

Modules can also load classes from libraries - JAR files that are packaged with the module (see DevFaqHowPackageLibraries). Some points to remember about libraries:

• They are delivered to the user inside the NBM file if they are not part of a full application based on NetBeans.
• When unpacked, the module will end up in $SOMECLUSTER/modules/ and any libraries will end up in $SOMECLUSTER/modules/ext/.
• The module will use the library by having an entry in its manifest Class-Path: ext/someLibrary.jar the same way any JAR would.

If you are using the IDE's module development support, you will manage module dependencies in the properties dialog for your module (or the Libraries node in the Projects tab). This just modifies yourmodule/nbproject/project.xml. The data saved there is then used to generate the appropriate manifest entries for you.

If you are writing a module that will use some third party libraries, you probably want to read DevFaqWrapperModules and also DevFaqWhenUseWrapperModule.

For more details, see the reference documentation about classloading in NetBeans.

Applies to: NetBeans 6.5

If you simply want to run some code when your module loads or unloads, registering an instance of ModuleInstall will do the trick. There is even a wizard in the IDE for setting this up.

But in the very rare case that you want to be notified when other modules are loaded or unloaded, it is possible because:

1. You can use Lookup.Result to listen to changes in the contents of a Lookup, even the global lookup.
2. Every module installs an instance of ModuleInfo into the default Lookup so the module system (or other code) can find out details about the module including its code name base, version numbers and display name.

By using these two facts together, it is possible to listen to changes in the installed modules by running code like this at some point in the application's lifecycle:

final Lookup.Result<ModuleInfo> result = Lookup.getDefault().lookupResult(ModuleInfo.class);
result.addLookupListener(new LookupListener() {
    public void resultChanged(LookupEvent event) {
        // it seems a module was installed or removed
    }
});

Once you detect that a module has been created you may also want to register a PropertyChangeListener and listen to ModuleInfo.PROP_ENABLED. (A module present in the installation will provide a ModuleInfo but isEnabled might be false if it is not currently loaded.)

If you want to protect a NetBeans module from disassembly, you can obfuscate it. For example you can use ProGuard, an open-source obfuscator.

1. Copy proguard.jar somewhere on disk, referenced by proguard.jar.path.
2. Edit the build.xml of your module and override some targets as in the following excerpt:

<!-- Replace the non-obfuscated jar with the obfuscated one when compiling -->
<target name="netbeans-extra" depends="obfuscate">
    <copy file="${suite.dir}/build/obfuscated/${module.jar}" tofile="${cluster}/${module.jar}"/>
</target>

<!-- Overridden debug target that depends on netbeans-debug -->
<target name="debug" depends="netbeans-debug,-jdk-presetdef-nbjpdastart">
    <ant antfile="${harness.dir}/run.xml" target="debug"/>
</target>

<!-- netbeans-debug DOES NOT depends on netbeans-extra (then DOES NOT depends on obfuscate) -->
<target name="netbeans-debug"
        depends="init,jar,module-xml-regular,module-xml-autoload,module-xml-eager,javahelp,module-auto-deps,release,verify-class-linkage">
    <genlist outputfiledir="${cluster}" module="${module.jar}">
        <fileset dir="${cluster}">
            <patternset refid="module.files"/>
        </fileset>
    </genlist>
</target>

<!-- Overridden to delete also the obfuscated jar -->
<target name="clean" depends="files-init,testuserdir-delete">
    <delete failonerror="false" includeemptydirs="true">
        <fileset dir="build">
            <exclude name="testuserdir/"/>
        </fileset>
    </delete>
    <delete dir="${netbeans.javadoc.dir}/${code.name.base.dashes}"/>
    <delete file="${netbeans.javadoc.dir}/${code.name.base.dashes}.zip"/>
    <delete failonerror="false"> <!-- #59457: OK if cluster does not exist currently -->
        <fileset dir="${cluster}">
            <patternset refid="module.files"/>
        </fileset>
    </delete>
    <delete file="${cluster}/update_tracking/${code.name.base.dashes}.xml"/>
    <delete file="${suite.dir}/build/obfuscated/${module.jar}"/>
</target>

<!--  Just a cut and paste of how the proguard obfuscator works.
      This is not supposed to work below.  In fact, this seems to work
      on jars, not .class files, so it will have to be placed in a
      post jar target, which I haven't identified yet -->
<target name="obfuscate" depends="init">
    <taskdef resource="proguard/ant/task.properties"
             classpath="${proguard.jar.path}" />

    <echo message="Obfuscating ${cluster}/${module.jar}..."/>
    <mkdir dir="${suite.dir}/build/obfuscated"/>
    <proguard printmapping="${suite.dir}/build/obfuscated/${code.name.base.dashes}.map"
              renamesourcefileattribute="SourceFile" ignorewarnings="true">

        <!-- Specify the input jars, output jars, and library jars. -->
        <injar  file="${cluster}/${module.jar}" />
        <outjar file="${suite.dir}/build/obfuscated/${module.jar}" />

        <libraryjar path="${module.run.classpath}" />
        <libraryjar file="${nbjdk.home}/jre/lib/rt.jar" />

        <!-- Keep some useful attributes. -->

        <keepattribute name="InnerClasses" />
        <keepattribute name="SourceFile" />
        <keepattribute name="LineNumberTable" />
        <keepattribute name="Deprecated" />
        <keepattribute name="*Annotation*" />
        <keepattribute name="Signature" />

        <!-- Preserve all public classes, and their public and protected fields and methods. -->

        <keep access="public">
            <field  access="public protected" />
            <method access="public protected" />
        </keep>


        <!-- Preserve all .class method names. -->

        <keepclassmembernames access="public">
            <method type      ="java.lang.Class"
                    name      ="class$"
                    parameters="java.lang.String" />
            <method type      ="java.lang.Class"
                    name      ="class$"
                    parameters="java.lang.String,boolean" />
        </keepclassmembernames>

        <!-- Preserve all native method names and the names of their classes. -->

        <keepclasseswithmembernames>
            <method access="native" />
        </keepclasseswithmembernames>

        <!-- Preserve the methods that are required in all enumeration classes. -->

        <keepclassmembers extends="java.lang.Enum">
            <method access="public static"
                    type="**[]"
                    name="values"
                    parameters="" />
            <method access="public static"
                    type="**"
                    name="valueOf"
                    parameters="java.lang.String" />
        </keepclassmembers>

        <!-- Explicitly preserve all serialization members. The Serializable
             interface is only a marker interface, so it wouldn't save them.
             You can comment this out if your library doesn't use serialization.
             With this code serializable classes will be backward compatible -->

        <keepnames implements="java.io.Serializable"/>
        <keepclassmembers implements="java.io.Serializable">
            <field  access    ="final"
                    type      ="long"
                    name      ="serialVersionUID" />
            <field  access    ="!static !transient"
                    name      ="**"/>
            <field  access    ="!private"
                    name      ="**"/>
            <method access    ="!private"
                    name      ="**"/>
            <method access    ="private"
                    type      ="void"
                    name      ="writeObject"
                    parameters="java.io.ObjectOutputStream" />
            <method access    ="private"
                    type      ="void"
                    name      ="readObject"
                    parameters="java.io.ObjectOutputStream" />
            <method type      ="java.lang.Object"
                    name      ="writeReplace"
                    parameters="" />
            <method type      ="java.lang.Object"
                    name      ="readResolve"
                    parameters="" />
        </keepclassmembers>

        <!-- Your application may contain more items that need to be preserved;
             typically classes that are dynamically created using Class.forName -->

    </proguard>
</target>

In this way when running and when creating the NBM (as well from a suite) the module will be obfuscated. When debugging your module you use the non-obfuscated JAR, so you can step through source as well.

Applies to: ??? (unverified)

The patch must be in the same cluster as the original. (Issue 69794) If you want to create an NBM containing a patch, you must ensure it will be installed in the same cluster (use the nbm.target.cluster property), but note that you cannot test such a dummy module as part of a module suite (since this property is interpreted only by Plugin Manager). If you are distributing a complete application including a patch to the NB Platform, you will need to either manually preinstall the patch JAR in your copy of the Platform; or override your build-zip target to include the JAR in the final ZIP (in which case testing using Run Project will not have the patch active).

Because of this, today, most of the APIs you will use to install things into the system involve a text entry (DevFaqWhenToUseWhatRegistrationMethod), such as putting something in an XML file (DevFaqModulesLayerFile), not running Java code. Ideally a module should do nothing on startup. Let's say that again, forcefully: Ideally a module should do nothing on startup.

The main ways to do this are using @ServiceProvider or using annotations which create XML layer entries that declare information about the things your module is installing. Then, when they are needed to do actual work, your objects will be instantiated.

If you really need to run some code on startup, see DevFaqWhenToUseWhatRegistrationMethod about ModuleInstall.

Applies to: NetBeans 6.7

There are four basic ways a module can install configuration data or objects. Three of the ways are declarative (DevFaqModulesDeclarativeVsProgrammatic); these mechanisms are preferred.

If you are writing a module that has an API you want other modules to plug in to, you probably want to read DevFaqWhenToUseWhatRegistrationMethod.

@ServiceProvider

For global services, singletons and such, this is the preferred way. In NetBeans 6.7+, you can simply use the @ServiceProvider annotation.

What exactly you register is a contract between you and whatever module is providing the interface and will, presumably, do something with what you put there. What's really happening is that you are adding your implementation of this interface to the default lookup (see DevFaqLookupDefault).

Any module can specify interfaces that it would like other modules to register instances of. For example, the basic Project support module asks that each module that implements a project type (the things you see in the New Project wizard in NetBeans) register their ProjectFactorys there.

To get an instance of something registered this way, call

TheInterface i = Lookup.getDefault().lookup(TheInterface.class);

If there can be more than one registered object of this type, you can get them all as follows:

for (TheInterface i : Lookup.getDefault().lookupAll(TheInterface.class)) {...}

Registering objects in the System Filesystem

The system filesystem (see DevFaqSystemFilesystem) allows for more detailed information in registering objects. It is a virtual filesystem composed of XML fragments (see DevFaqModulesLayerFile) from all (well, most) of the modules in the system. The top layer of the system filesystem is $USERDIR/config which is where changes that are written at runtime are put.

The system filesystem is composed of folders. Some folders have special meanings to the system; what folders exist and are meaningful depends on what modules you have installed. For example, the core window system defines the folder Menu/, which contains subfolders - one for each menu in the main window's menu bar. If you add a file to the folder Menu/File called com-foo-mymodule-MyAction.instance, an instance of com.foo.mymodule.MyAction will be created, and a menu item will be put on the menu for it.

For more details on registering objects, defining an order in which they should appear, etc., see the DevFaqModulesLayerFile. In the short form, a module registers a layer by including a line in its manifest:

OpenIDE-Module-Layer: com/foo/mymodule/resources/layer.xml

<filesystem>
    <folder name="SomeFolder">
        <file name="SomeFile"/>
    </folder>
</filesystem>

Starting with NetBeans 6.7, more or more layer registrations can be made by using various source code annotations. If you use these exclusively, you will not need to declare a layer in your module's sources at all.

Registering objects in the module's manifest

Some types of objects used to be installed by adding a section to the module manifest. This is now deprecated.

Programmatic registration - ModuleInstall classes

The module system allows you to provide a ModuleInstall class, which runs some code during startup or when the module is loaded, and can run cleanup code when it is uninstalled or disabled. This is the least desirable way to do things, because running code on startup means slowing down startup. Before you use such a class, be sure there is no declarative way to do what you're trying to do; see: DevFaqModulesDeclarativeVsProgrammatic

To have some code run on startup/installation/uninstallation/etc., add a line like the following to your module's manifest file:

OpenIDE-Module-Install: org/netbeans/modules/paintcatcher/PaintCatcherModule.class

Layer files are small XML files provided by modules, which define a virtual filesystem (DevFaqFileSystem). The layer file defines folders and files that will be merged into the system filesystem (DevFaqSystemFilesystem) that makes up the runtime configuration information NetBeans and its modules use.

Layer files help to make it possible for modules to be dynamically installed. If you've read about FileObjects (DevFaqFileObjects) and FileSystems (DevFaqFileSystems), you know that you can listen for changes in folders and files in a filesystem. That's exactly what the components of NetBeans whose content is composed from folders in the system filesystem do. So if a module is added at runtime, the system filesystem fires changes; the UI notices that the contents of the folder has changed and updates the UI to reflect the changes.

If you created your module using the IDE, you may already have an XML layer in your module, and you can expand the node for it under Important Files in your module project to see and modify its contents. The way it is declared is simple:

• In your JAR, provide the layer file - e.g. com/foo/mymodule/resources/layer.xml
• In your module's manifest, include the following line somewhere in the top section:

OpenIDE-Module-Layer: com/foo/mymodule/resources/layer.xml

Starting with NB 6.7, some Java source code annotations generate layer entries for you (you do not need to have a layer.xml in your module's source tree).

• Actions API
• DataSystems API
• Explorer API
• FileSystem API
• Module System API
• Nodes API
• Utilities API
• Window System API

API Reference: JNI in modules

• Loading images - Don't use ImageIO.read() or Toolkit.loadImage() - instead, use ImageUtilities.loadImage() - it has an optimized image caching strategy, and will play nicely with NetBeans module class loaders
• Loading resource bundles/localized strings - Don't use ResourceBundle directly - instead, use NbBundle.getMessage() - it will play nicely with NetBeans class loaders, and Strings resolved this way can be branded using the standard branding mechanism (this is the way you change the title of your application from "NetBeans" to something else). Also, do not hold a reference to a resource bundle - just call NbBundle.getMessage() every time - bundles are cached for a period of time, the call is fast. In a large application, holding resource bundles eats memory wastefully
• Assigning mnemonics to labels and buttons - use Mnemonics to assign text and mnemonic to a widget with one call using one key value pair in properties file and annotate the mnemonic with & character. Also do not reuse the same text if it is used in different UI components. This is more freindly to localization.
  Tip: Check 'Generate Mnemonics Code' checkbox in properties of your form if you are using NetBeans GUI editing support.
• Showing dialogs - instead of creating a JDialog and showing it, or using JOptionPane, use NotifyDescriptor or DialogDescriptor to define your dialog and its contents, then pass these to DialogDisplayer.notify - such dialogs will play nicely with NetBeans' windowing system, global actions, etc.

Applies to: NetBeans 6.5

your_module.nbm
    |   
    +- Info
    |   |
    |   +--- info.xml
    |
    +- netbeans
        |
        +--- modules...
    |
    +-main
        |
        +--- main.properties
        +--- <custom code>

The properties can contain several special variables which Autoupdate replaces by real values:

Example

• Download and unzip a project samplepostinstall.zip
• Go into samplepostinstall/main directory
• In main directory is main class Hello which should use most of possibilities of post-install hooks
  • Using properties mainClass, relativeClassPath, jvm.parameters etc.
  • Reads all special variables like %IDE_HOME%, %JAVA_HOME% etc.
  • Opens some GUI
  • Runs a JDK demo

To see that samplepostinstall project in action

1. download NBM
2. run NetBeans IDE (6.0 or newer)
3. invoke Tools|Plugins and switch to Download tab
4. add the downloaded NBM
5. install it and then watch post-install hook what will be executed while installing that plugin

I'm not author of this feature, it's only my investigation.

Do not hesitate to contact me on mailto:jrechtacek@netbeans.org if you have any question.

What you need is for your libraries to be a module; see DevFaqWrapperModules.

Applies to: NetBeans 6.5

By default, a NetBeans Platform application will use the developer's copy of the IDE as the platform. This is certainly easy, but there are also drawbacks to using the current IDE as a platform. With that in mind, lets check out, and reference our own copy of the Netbeans source code. This way we can also use breakpoints to step through the Netbeans source code, make changes, and create patches!

At a high level the steps are as follows. First get the Netbeans source code checked out. This part is interesting because what you end up with is a complete copy of the Netbeans source repository on your local file system. The second thing you need to do is build the Netbeans platform using the source repository that you just checked out. This is important because without building the platform you will not have the dependencies required by the platform modules. The next step is to create a new platform reference. Of course the platform to reference will be the one that you just checked out and built. Then finally, in your module suite's project properties, select the platform reference that you just created.

So, in more detail then...

1. Check Out Netbeans Source Code

First get the source code from the Mercurial repository. In the following example the source code is checked out to a local ~/netbeans-repository/ directory. In this example the tilde is used to represent the home directory of your file system.

So far, so good, but you still need to build the source code so that you have a complete Netbeans platform, along with all the jar dependencies.

2. Build The Netbeans Source

Building the Netbeans source is very easy, and very satisfying to watch! Just open up your favorite terminal client and navigate to your local repository.

cd ~/netbeans-repository/main/

Then simply run ant.

ant -Dpermit.jdk6.builds=true

Note, I am choosing to build Netbeans using JDK1.6 so I have to explicitly tell Netbeans that I understand that only JDK1.5 is supported.

It took about 25 minutes for the build to finish on my machine.

3. Create A New Platform Reference In Netbeans

In order to work with the Netbeans platform that you just built it needs to be added as a platform in the IDE.

• Click Tools -> NetBeans Platforms (note that the menu item name varies slightly in older versions)
• Click the "Add Platform..." button in the lower right
• Locate the platform binary and click OK. In this example the proper path is ~/netbeans-repository/main/nbbuild/netbeans/.
• You can associate sources and javadoc for this platform using the respective tabs in the platform manager
• You can also choose which version of the build scripts you want to us on the Harness tab. You'll usually want to use the version corresponding to that platform.

4. Reference The New Platform

Now just select the platform in your module suite's Project Properties. There you will see a Netbeans Platform dropdown box where you can select the platform that you set up.

Note: I did have to go through and resolve some of the cluster dependencies. That just means that I had to check the dependencies that Netbeans said that other modules needed. Once you get this far it will be very obvious what to do.

Appendix A. Netbeans Platform And Using JDK1.6

In order to use JDK1.6 with the Netbeans source code we need to tell the Netbeans platform that we understand that only JDK1.5 is supported. What you need to do is create a "user.build.properties" file and put it in the nbbuild directory.

touch ~/netbeans-repository/main/nbbuild/user.build.properties

Inside the user.build.properties file put the following line.

permit.jdk6.builds=true

This tutorial applies to: versions 6.7 and earlier of the NetBeans Java IDE.

If it's problem #2, then you are already declaring a dependency, but get full access to all classes in a module, you need to declare an implementation dependency (DevFaqImplementationDependency). Be sure you really need to use the class you're trying to use, in this case - it will make your module hard to upgrade because generally it will need to be paired with the exact version of the other module's JAR that it was built with - if that module is upgraded, your module may end up being disabled.

Problem #3 may happen if you change your modules name. If some module declared yours as a friend it will no longer recognize it.

Checking for errors eagerly

For a nice way to resolve all module dependencies at once, to force all of the errors to be exposed simultaneously, just add the following to the command line when starting NetBeans:

-J-Dnetbeans.preresolve.classes=true

The message displayed states that when using this flag, you should not use the -J-Xverify:none flag (often specified in the IDE configuration file), so you may need to edit the .conf file to remove the -Xverify option before using the pre-resolve option.

More tips

For help on working with class paths, please see

http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/classpath.html

Applies to: NetBeans 6.x

Platforms: all

The above will suffice if you just want to suppress the aforementioned dialog which is sufficient for most customization cases. But if you need total control over node deletion, you can implement the ExtendedDelete interface.

Implementing such a feature with the OpenIDE API is quite a simple task. We first define a subclass of SystemAction which listens for changes in the selection of the current TopComponent and tracks the currently active ExplorerManager:

public abstract class ExplorerManagerAction extends SystemAction
  {
    private ExplorerManager activeExplorerManager;

    public ExplorerManagerAction()
      {
        TopComponent.getRegistry().addPropertyChangeListener(new PropertyChangeListener()
          {
            public void propertyChange (PropertyChangeEvent event)
              {
                if (TopComponent.Registry.PROP_ACTIVATED.equals(event.getPropertyName()))
                  {
                    Object value = event.getNewValue();

                    if (value instanceof ExplorerManager.Provider)
                      {
                        activeExplorerManager = ((ExplorerManager.Provider)value).getExplorerManager();
                        setEnabled(true);
                      }

                    else
                      {
                        activeExplorerManager = null;
                        setEnabled(false);
                      }
                  }
              }
          });
      }

    final public void actionPerformed (ActionEvent actionEvent)
      {
        if (activeExplorerManager != null)
          {
            try
              {
                performAction(activeExplorerManager);
              }
            catch (PropertyVetoException e)
              {
                // ...
              }
          }
      }

    abstract protected void performAction (ExplorerManager explorerManager)
      throws PropertyVetoException;

    public HelpCtx getHelpCtx()
      {
        return HelpCtx.DEFAULT_HELP;
      }

    protected void initialize()
      {
        super.initialize();
        putValue("noIconInMenu", Boolean.TRUE);
      }

    protected boolean asynchronous()
      {
        return false;
      }
  }

Now in order to implement the specific node selection actions we just have to subclass and provide a concrete implementation of the performAction() method which takes an ExplorerManager as parameter.

For the "Select All" action we have:

public final class SelectAllAction extends ExplorerManagerAction
  {
    protected void performAction (ExplorerManager explorerManager)
      throws PropertyVetoException
      {
        explorerManager.setSelectedNodes(explorerManager.getRootContext().getChildren().getNodes());
      }
    public String getName()
      {
        return NbBundle.getMessage(SelectAllAction.class, "CTL_SelectAllAction");
      }
  }

For the "Deselect all" action we have:

public final class DeselectAllAction extends ExplorerManagerAction
  {
    protected void performAction (ExplorerManager explorerManager)
      throws PropertyVetoException
      {
        explorerManager.setSelectedNodes(new Node[0]);
      }
    public String getName()
      {
        return NbBundle.getMessage(DeselectAllAction.class, "CTL_DeselectAllAction");
      }

At last for the "Invert selection" action we have:

public final class InvertSelectionAction  extends ExplorerManagerAction
  {
    protected void performAction (ExplorerManager explorerManager)
      throws PropertyVetoException
      {
        List nodes = new ArrayList(Arrays.asList(explorerManager.getRootContext().getChildren().getNodes()));
        nodes.removeAll(Arrays.asList(explorerManager.getSelectedNodes()));
        explorerManager.setSelectedNodes((Node[])nodes.toArray(new Node[0]));
      }
    public String getName()
      {
        return NbBundle.getMessage(InvertSelectionAction.class, "CTL_InvertSelectionAction");
      }
  }

The above code for "Select All" and "Invert selection" only works for "flat" node structures with a root and a single level of children. For more complex structures we just need to replace explorerManager.getRootContext().getChildren().getNodes() with a piece of code that recursively explores the node tree contents.

To complete our work, this is the XML code to put in the layer.xml in order to add actions in the menu, the toolbar and to define the proper key bindings:

<!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
<filesystem>
    <!-- Declares the relevant actions. -->
    <folder name="Actions">
        <folder name="Select">
            <file name="my-package-action-SelectAllAction.instance"/>
            <file name="my-package-action-DeselectAllAction.instance"/>
            <file name="my-package-action-InvertSelectionAction.instance"/>
        </folder>
    </folder>
    <!-- Adds the actions to the Select main menu. -->
    <folder name="Menu">
        <folder name="Select">
            <file name="my-package-action-SelectAllAction.shadow">
                <attr name="originalFile" stringvalue="Actions/Select/my-package-action-SelectAllAction.instance"/>
            </file>
            <attr name="my-package-action-SelectAllAction.shadow/my-package-action-DeselectAllAction.shadow" boolvalue="true"/>
            <file name="my-package-action-DeselectAllAction.shadow">
                <attr name="originalFile" stringvalue="Actions/Select/my-package-action-DeselectAllAction.instance"/>
            </file>
            <attr name="my-package-action-DeselectAllAction.shadow/my-package-action-InvertSelectionAction.shadow" boolvalue="true"/>
            <file name="my-package-action-InvertSelectionAction.shadow">
                <attr name="originalFile" stringvalue="Actions/Select/my-package-action-InvertSelectionAction.instance"/>
            </file>
            <attr name="my-package-action-InvertSelectionAction.instance/it-tidalwave-bluemarine-catalog-tagstamper-action-separatorBefore.instance" boolvalue="true"/>
        </folder>
    </folder>
    <!-- Declares the shortcuts. D- maps to "command" on Mac OS X and to "ctrl" on Linux and Windows. -->
    <folder name="Shortcuts">
        <file name="D-A.shadow">
            <attr name="originalFile" stringvalue="Actions/Select/my-package-action-SelectAllAction.instance"/>
        </file>
        <file name="D-D.shadow">
            <attr name="originalFile" stringvalue="Actions/Select/my-package-action-DeselectAllAction.instance"/>
        </file>
        <file name="D-I.shadow">
            <attr name="originalFile" stringvalue="Actions/Select/my-package-action-InvertSelectionAction.instance"/>
        </file>
    </folder>
    <!-- Adds the actions to the Select toolbar -->
    <folder name="Toolbars">
        <folder name="Select">
            <file name="my-package-action-InvertSelectionAction.shadow">
                <attr name="originalFile" stringvalue="Actions/Select/my-package-action-InvertSelectionAction.instance"/>
            </file>
            <attr name="my-package-action-InvertSelectionAction.shadow/my-package-action-DeselectAllAction.shadow" boolvalue="true"/>
            <file name="my-package-action-DeselectAllAction.shadow">
                <attr name="originalFile" stringvalue="Actions/Select/my-package-action-DeselectAllAction.instance"/>
            </file>
            <attr name="my-package-action-DeselectAllAction.shadow/my-package-action-SelectAllAction.shadow" boolvalue="true"/>
            <file name="my-package-action-SelectAllAction.shadow">
                <attr name="originalFile" stringvalue="Actions/Select/my-package-action-SelectAllAction.instance"/>
            </file>
        </folder>
    </folder>
</filesystem>

-- Main.fabriziogiudici - 06 Jul 2006

PENDING: Review/cleanup

From Serialization and traversal in the NetBeans Javadoc:

"If you need to store (serialize) a node for any reason, this is generally impossible due to the welter of Java-level references connecting it to the rest of the system. Rather, you must use a special serializable handle which represents the node by its position in the hierarchy, and permits finding the original node again after deserialization (if it still exists). To create a handle, just call Node.getHandle(), and to restore the node call Node.Handle.getNode().

Creation of a usable handle is implemented in AbstractNode, and you should not need to override it. However, note that a handle consists of a handle for the root node of the target node's hierarchy together with a path (by system name) down to the target node; so if you are creating a root node, and want it or its children to be serializable, then you should create a specific implementation of Node.Handle capable of reconstructing your root from scratch, and return it from Node.getHandle().

The methods in NodeOp such as NodeOp.findPath(...) may also be used for general-purpose navigation along the hierarchy, should this be necessary."

Some concrete examples:

• Serializing Nodes
• Serializing Marilyn Monroe

AbstractNode nue = new AbstractNode (Children.LEAF);
nue.setDisplayName ("Please wait...");
nue.setIcon (Utilities.loadImage ("path/in/jar/to/image.gif"));
return nue;

If you are creating Node s, you will typically deal with one of four things

• AbstractNode - create a Node which represents anything you want - you will implement all its logic, provide children, etc. Typically most logic goes in the Children object.
• BeanNode - a very convenient Node subclass, which can represent any JavaBean as a Node and expose its bean properties as Property objects that can be edited on the property sheet
• FilterNode - a Node subclass that proxies another Node. You can subclass this to take an existing Node (possibly representing a file on disk or in the system filesystem and keep most of its attributes, but provide different actions or display name or icons or properties
• DataNode - a Node subclass specific to editing files. If you are writing a module that adds support for a new file type (such as .svg files), you will write a DataNode subclass to give files of that type icons, display names, and possibly provide access to the file's content

Note that if you just want to write context sensitive code, not provide your own Nodes, you may be able to do it without a dependency on the Nodes API, using Utilities.actionsGlobalContext().

• How do I create an Action that is automatically enabled and disabled depending on the selection?

class NodeProxy extends FilterNode {

    public NodeProxy(Node original) {
        super(original, new ProxyChildren(original));
    }

    // add your specialized behavior here...
}

class ProxyChildren extends FilterNode.Children {

    public ProxyChildren(Node owner) {
        super(owner);
    }

    protected Node copyNode(Node original) {
        return new NodeProxy(original);
    }
}

   class ProxyChildren extends FilterNode.Children {

        public ProxyChildren (Node owner)  {
            super(owner);
          }
        
        @Override
        protected Node copyNode (Node original){
            return new NodeProxy(original);
          }
        
        @Override
        protected Node[] createNodes (Object object) {
            List<Node> result = new ArrayList<Node>();
            
            for (Node node : super.createNodes(object)) {
                if (accept(node)) {
                    result.add(node);
                  }
              }
            
            return result.toArray(new Node[0]);
          }

        private boolean accept (Node node) {
            // ...
          }
      }

class FileFilteredNode extends FilterNode {

    private final FileFilter fileFilter;
   
    static class FileFilteredChildren extends FilterNode.Children {
        private final FileFilter fileFilter;
   
        public FileFilteredChildren (Node owner, FileFilter fileFilter) {
            super(owner);
            this.fileFilter = fileFilter;
          }

        @Override
        protected Node copyNode (Node original) {
            return new FileFilteredNode(original, fileFilter);
          }

        @Override
        protected Node[] createNodes (Object object) {
            List<Node> result = new ArrayList<Node>();

            for (Node node : super.createNodes(object)) {
                DataObject dataObject = (DataObject)node.getLookup().lookup(DataObject.class);

                if (dataObject != null) {
                    FileObject fileObject = dataObject.getPrimaryFile();
                    File file = FileUtil.toFile(fileObject);

                    if (fileFilter.accept(file)) {
                        result.add(node);
                      }
                  }
              }

            return result.toArray(new Node[0]);
          }
      }

    public FileFilteredNode (Node original, FileFilter fileFilter) {
        super(original, new FileFilteredChildren(original, fileFilter));
        this.fileFilter = fileFilter;
      }
  }

Note that if you're showing the filtered nodes in a tree view according to the code above, you might find expansion handles on leaf nodes. This thread from the dev@openide list discusses some solutions to this problem.

This is done by simply starting with the NetBeans Platform and removing all but the most essential components. NetBeans architect Jaroslav Tulach calls this subset of the NetBeans platform the "runtime container" and wrote an application which uses it to control his television.

Here are the steps for creating a runtime container application:

1. Create a new suite
2. Exclude all clusters from the suite
3. Re-enable the platform cluster, but disable all but the following modules:
   • Bootstrap
   • File System API
   • Module System API
   • Startup
   • Utilities API
4. Add a new module to the suite
5. Create and register a ModuleInstall class
6. The restored() method is effectively your application's main method.
7. You may optionally override the close() method of your ModuleInstall to clean up resources upon shutdown.

You will also need to supress the splash screen by passing --nosplash argument when starting the app.

The "New Window Component" wizard in the NetBeans IDE generates a singleton TopComponent. That's fine for some uses, but often you will want to create multiple instances of your TopComponent.

The good news is that you won't have to write any code -- you'll just have to delete some of the code that was generated for you.

In your TopComponent's .java source file:

• Delete the static instance variable, which ought to be declared a few lines above the constructor.
• Make constructor public
• Delete the getDefault() method (typically somewhere around the middle of the file)
• Delete the findInstance() method (which typically follows the getDefault() method)
• Delete the writeReplace() method (typically towards the end of the file)
• Delete the ResolvableHelper inner class (typically towards the end of the file)
• Only singleton TopComponents can have a persistence mode of PERSISTENCE_ALWAYS, so you must locate the getPersistenceType method and change its return value to either TopComponent.PERSISTENCE_NEVER or TopComponent.PERSISTENCE_ONLY_OPENED.

Next, open the settings file that the wizard generated for your TopComponent. This is typically named something like FooTopComponentSettings.xml. Locate the instance XML element (NOT one of the instanceof elements and remove method="getDefault" from the end of that line.

Finally, you will need to change any code, such as from the action which opens the TopComponent, which called the getDefault() method. It should now simply create a new instance of your TopComponent instead.

NOTE: These instructions should apply to NetBeans 5.0 through 6.5. You may need to adapt them slightly for newer versions.