NetBeans Master Developer FAQ

First, make sure you have Mercurial installed on your machine, along with its requirements such as python.

Then, from the command line, you run

hg clone http://hg.netbeans.org/main/

hg fclone http://hg.netbeans.org/main/ nb_all

To build, simply run Ant in the root of your NetBeans sources. The build will appear in $NB_SRC/nbbuild/netbeans/.

More info about using Mercurial with Netbeans sources...

related message in the NetBeans mailing list

public Action[] getActions( boolean context )

If this node is really a DataNode for your own file type, instead see How do I add an action to a file of a given mime-type?.

See also:

• 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?

<folder name="Editors">
 <folder name="text">
   <folder name="x-java">
      <folder name="Popup">
         <file name="org-mymodule-MyAction.instance"/>
</folder></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?

<folder name="Menu">
   <folder name="File">
         <file name="org-mymodule-MyAction.instance"/>
</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 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

public final class AddActionOperation implements CopyOperationImplementation {
    
    private final AddActionProject project; // suppose this is the 
    private final FileObject projectDir;
    
    public AddActionOperation(final AddActionProject project) {
        this.project = project;
        this.projectDir = project.getProjectDirectory();
    }
    
    public List/*<FileObject>*/ getMetadataFiles() {
        return Collections.EMPTY_LIST;
    }
    
    public List/*<FileObject>*/ getDataFiles() {        
        return Collections.EMPTY_LIST;
    }
    
    public void notifyCopying() throws IOException {
        System.out.println("Copying");
    }

    public void notifyCopied(Project project, File file, String string) throws IOException {
        System.out.println("Copied");
    }
}

public final class AddActionActions implements ActionProvider {
    
    private final AddActionProject project; //suppose this is your project
    
    public AddActionActions(AddActionProject project) {
        this.project = project;
    }
    
    public String[] getSupportedActions() {
        return new String[] {
            ActionProvider.COMMAND_COPY
        };
    }
    
    public boolean isActionEnabled(String command, Lookup context) {
        if (command.equals(ActionProvider.COMMAND_COPY)) {
            return true;
        } else {
            throw new IllegalArgumentException(command);
        }
    }
    
    public void invokeAction(String command, Lookup context) {
        if (command.equalsIgnoreCase(ActionProvider.COMMAND_COPY)){
            DefaultProjectOperations.performDefaultCopyOperation(project);
        }
    }
}

lookup = Lookups.fixed(new Object[] {
            this,
            state,
            new AddActionOperation(this),
            new AddActionActions(this),
            loadProperties(),
            new Info(),
            new AddActionLogicalView(this)
        });

public Action[] getActions(boolean context) {   
        Action[] nodeActions = new Action[2];
        nodeActions[0] = CommonProjectActions.copyProjectAction();
        nodeActions[1] = CommonProjectActions.closeProjectAction();
        return nodeActions;
    }

See also Common Project Actions

<filesystem>
    <folder name="Projects">
        <folder name="Actions">
            <file name="projectcontextmenudemo-DemoAction.instance"/>
        </folder>
    </folder>
</filesystem>

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

<folder name="Toolbars">
   <folder name="Build">
         <file name="org-mymodule-MyAction.instance"/>
</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 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). To understand how this works, see the section on the global action context:

public class FooAction extends AbstractAction implements LookupListener, ContextAwareAction {
    private Lookup context;
    Lookup.Result 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
        Lookup.Template tpl = new Lookup.Template(Whatever.class);
        lkpInfo = context.lookup (tpl);
        lkpInfo.addLookupListener(this);
        resultChanged(null);
    }

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

    public void actionPerformed(ActionEvent e) {
        init();
        Collection 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);
    }
}

Name: com/tomwheeler/example/dataimport/wizard/DataImportCookieAction.class
OpenIDE-Module-Class: Action

• 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 NetBeans menu bar?

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

The default UI in NetBeans includes the ability to rearrange, and even delete, whole menus or individual menu items. Many applications built on NetBeans will not want to expose such customizability, but some do. The Actions/ folder is shown in the options dialog (and also used from the key bindings editor); it makes it possible for a user to delete an action from menus and toolbars, but still be able to restore it at a later date - if there were not some UI for this, any deleted action would effectively disappear from the universe, as far as the user was concerned.

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

Note that providing a ModuleInstall class will degrade overall startup time somewhat, but as long as you don't overuse ModuleInstall classes and take care to execute any long-running tasks from its methods in a background thread, you should be OK.

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

Here is the sequence of events you can hook into for when a TopComponent is opened:

1. JComponent.addNotify
2. TopComponent.componentOpened
3. TopComponent.componentShowing
4. 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 is the sequence of events you can hook into for when a TopComponent is closed:

1. TopComponent.canClose
2. JComponent.removeNotify
3. TopComponent.componentHidden
4. TopComponent.componentDeactivated
5. TopComponent.componentClosed

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

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.

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

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. Most have additional module projects underneath them.

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

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.

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

Classloaders in the NetBeans platform

There are basically three main classloader types used in the platform. Most of the code should be loaded by the Modules classloader. Only in justified special cases the System classloader can be used - e.g. when you need access to resources from all the modules. And finally the resources directly on the classpath from the launch script are loaded by the original classloader (the term boot classloader might be a bit confusing because of the bootstrap classloader used by the JVM).

Most of the classloaders in the NetBeans platform are multi-parented classloaders. This means that the classloader can have zero or more parents. When looking for a resource the classloader uses this algorithm (implemented in class org.netbeans.ProxyClassLoader):

Modules Classloader

Every module registered by the module system creates one instance of the Module classloader. The classloader loads resources primarily from the module's jar file. This classloader is able to load from more jar files (besides having more classloaders as parents). The original (application) classloader is implicitly one of the parents of each module's classloder - always at the first position.

• locale extension - jar file placed in subfolder locale relative to the original module jar file position named by appending a locale suffix to the original name - is again loaded by this classloader
• patch - jar file placed in directory patches relative to the original jar file position is also loaded by this classloader

The implementation class is org.netbeans.StandardModule$OneModuleClassLoader. The ability to use more jar files is implemented in its superclass org.netbeans.JarClassLoader.

System Classloader

The system classloader is regular multiparented classloader that has as its parents all module's classloaders. It is accessible via call to the global lookup (ClassLoader)Lookup.getDefault().lookup(ClassLoader.class); or by using the fact that it is the context classloader on most of the threads: Thread.currentThread().getContextClassLoader();.

Original (application, JNLP) Classloader

This classloader is set up by the launching script. It is usually able to load classes from the original CLASSPATH plus clontents of the folder lib (with usual subfolder lib/ext). If a jar is loaded by this loader and it does not have proper manifest information required by the NetBeans module system the contained resources "bypass" the NetBeans module system. Also such resources are always found first if by accident the same resource is contained here and in a module jar (the module supplied resource is ignored in such case). It is generally discouraced to use this classloader for loading anything in the platform but it is sometimes needed e.g. for the Look And Feel classes (that has to be loaded very early during the startup sequence).

Example

example.gif

Let's have 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-a-1.0.jar ext/library-b-1.1.jar

Module b also declares a dependency on 2 external libraries - they will be loaded by the very same classloader as b.

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