NetBeans Platform 7.2 Quick Start

Choose File | New Project and then choose NetBeans Modules. Select "NetBeans Platform Application". You should see this:

Click Next.

Name your new application "WordProcessor" and specify a folder on disk for storing it:

Click Finish. The new project appears as follows in the Projects window:

Right-click the "Modules" node, shown in the screenshot above, and choose "Add New":

Name the new module "WordEditorCore":

Click Next.

Specify "org.word.editor.core" as the unique string identifying the module, which is its code name base, together with a project display name that will be shown in the Projects window.

Click Finish. The new module is created and its structure is shown in the Projects window:

Right-click the "WordEditorCore" module and choose New | Other. In the Module Development category, select "Window":

Click Next.

You should now see a dialog for specifying the position where the new window will appear in the application frame, as well as whether it will open automatically when the application starts, among other settings:

In the wizard step above, select "editor", which is the default central position within the application frame, and "Open on Application Start". Then click Next.

Set the class name prefix to "Word" and the package to "org.word.editor.core":

Click Finish. The new window is added to the source structure of your module:

Now double click on the file "WordTopComponent.java" to open it in the Design view of the "Matisse" GUI Builder. Use the Palette (Ctrl-Shift-8) to drag and drop a button and a text area onto the window:

Do the following to make the new GUI components meaningful:

• Right-click the text area, choose "Change Variable Name", and then name it "text". That is the name that will enable you to access the component from your code.
• Right-click the button, choose "Edit Text", and then set the text of the button to "Filter!"

private void jButton1ActionPerformed(java.awt.event.ActionEvent evt) {
   String s = text.getText();
   s = s.toUpperCase();
   text.setText(s);
}

Right-click the application and choose Run. Doing so will start up your new NetBeans Platform application and install your module. You will have a new window, as well as a new menu item for opening it, as shown below:

Enter a text in lowercase in the text area, and click "Filter!". You should see that the text is now shown in uppercase:

Expand the new application in the Projects window, right-click the Modules node, and choose "Add New":

Name the new module "WordEditorAPI":

Click Next. Use code name base "org.word.editor.api" and complete the wizard, which adds the module to your previously created application, as you did in the previous section:

Right-click the "WordEditorAPI" module and choose New | Java Interface. Name the Java interface "WordFilter", in the package "org.word.editor.api", and use the editor to define it as follows:

package org.word.editor.api;

public interface WordFilter {

    String process(String s);

}

Right-click the "WordEditorAPI" module, choose Properties, and use the "API Versioning" tab to specify that the package containing the interface should be available throughout the application:

Click OK.

In the Projects window, expand "Important Files" in the "WordEditorAPI" project and then double-click "Project Metadata". The "project.xml" file opens and you should see that the package has now been declared public:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="www.netbeans.org/ns/project/1">
    <type>org.netbeans.modules.apisupport.project</type>
    <configuration>
        <data xmlns="www.netbeans.org/ns/nb-module-project/3">
            <code-name-base>org.word.editor.api</code-name-base>
            <suite-component/>
            <module-dependencies/>
            <public-packages>
                <package>org.word.editor.api</package>
            </public-packages>
        </data>
    </configuration>
</project>

Expand the new application in the Projects window, right-click the Modules node, and choose "Add New" again:

Name the new module "UppercaseFilter":

Click Next. Use code name base "org.word.editor.uppercase" and complete the wizard, which adds the module to your previously created application, as you did in the previous section:

Right-click the Libraries node "UppercaseFilter" module, and Add Module Dependency, as shown below:

Start typing the name of the API class and notice that the list narrows until the module containing the class is found:

Click OK.

In the Projects window, expand "Important Files" in the "UppercaseFilter" project, and then double-click "Project Metadata". The "project.xml" file opens and you should see that a new dependency has been declared:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="www.netbeans.org/ns/project/1">
    <type>org.netbeans.modules.apisupport.project</type>
    <configuration>
        <data xmlns="www.netbeans.org/ns/nb-module-project/3">
            <code-name-base>org.word.editor.uppercase</code-name-base>
            <suite-component/>
            <module-dependencies>
                <dependency>
                    <code-name-base>org.word.editor.api</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>1.0</specification-version>
                    </run-dependency>
                </dependency>
            </module-dependencies>
            <public-packages/>
        </data>
    </configuration>
</project>

Note: In the same way as shown above, set a dependency on the Lookup API module, which provides the @ServiceProvider annotation that you will use in the next step.

package org.word.editor.uppercase;

import org.openide.util.lookup.ServiceProvider;
import org.word.editor.api.WordFilter;

@ServiceProvider(service=WordFilter.class)
public class UppercaseFilter implements WordFilter {

    @Override
    public String process(String s) {
        return s.toUpperCase();
    }

}

At compile time, the @ServiceProvider annotation will create a META-INF/services folder with a file that registers your implementation of the WordFilter interface, following the JDK 6 ServiceLoader mechanism.

In the WordEditorCore module, the code that handles a click on the filter button now needs to be changed, so that all implementations of the interface "WordFilter" are located and loaded. When such implementations are found, you need to invoke its method to filter the text. Before we can do this, we need to add a dependency in the the "WordEditorCore" module on the "WordEditorAPI" module:

Now, you can load implementations of the "WordFilter" class, as shown below:

private void jButton1ActionPerformed(java.awt.event.ActionEvent evt) {                                         
   String enteredText = text.getText();
   Collection<? extends WordFilter> allFilters = Lookup.getDefault().lookupAll(WordFilter.class);
   StringBuilder sb = new StringBuilder();
   for (WordFilter textFilter : allFilters) {
      String processedText = textFilter.process(enteredText);
      sb.append(processedText).append("\n");
   }
   text.setText(sb.toString());
}

The above could be achieved via the JDK 6 "ServiceLoader" class, except that the "Lookup" class can be used in JDK's prior to JDK 6. Aside from that, the "Lookup" class has a number of additional features, as the next section will illustrate.

Now you can run the application again and check that everything works just as before. While the functionality is the same, the new modular design offers a clear separation between the GUI and the implementation of the filter. The structure of the application should be as shown below.

The new application can also be extended quite easily, by adding new service providers to the application's classpath. As an exercise, add a new module that provides a "LowercaseFilter" implementation of the API to the application.

private InstanceContent content;

private WordTopComponent() {
    initComponents();
    setName(Bundle.CTL_WordTopComponent());
    setToolTipText(Bundle.HINT_WordTopComponent());
    content = new InstanceContent();
    associateLookup(new AbstractLookup(content));
}

Change the code of the filter button so that the entered text is added to the InstanceContent object when the button is clicked.

private void jButton1ActionPerformed(java.awt.event.ActionEvent evt) {                                         
   String enteredText = text.getText();
   Collection<? extends WordFilter> allFilters = Lookup.getDefault().lookupAll(WordFilter.class);
   StringBuilder sb = new StringBuilder();
   for (WordFilter textFilter : allFilters) {
      String processedText = textFilter.process(enteredText);
      sb.append(processedText).append("\n");
      content.add(enteredText);
   }
   text.setText(sb.toString());
}

In the same way as done in the previous sections, create another module in your application and name it "WordHistory". Use code name base "org.word.editor.history".

In the WordHistory module, right-click the "org.word.editor.history" package and choose New | Window. Use the New Window wizard to create a new window component that will automatically be opened on the left side of the application frame, which is the "explorer" position:

Click Next. Use prefix "WordHistory" and specify that the new window will be stored in the "org.word.editor.history" package. Click Finish.

Once you have created the window, add a JTextArea to it:

Change the variable name of the text area to "historyText".

...
...
...
public final class HistoryTopComponent extends TopComponent implements LookupListener {

    private org.openide.util.Lookup.Result<String> result;

    ...
    ...
    ...

    @Override
    public void componentOpened() {
        result = org.openide.util.Utilities.actionsGlobalContext().lookupResult(String.class);
        result.addLookupListener(this);
    }

    @Override
    public void componentClosed() {
        result.removeLookupListener(this);
    }

    @Override
    public void resultChanged(LookupEvent le) {
        Collection<? extends String> allStrings = result.allInstances();
        StringBuilder sb = new StringBuilder();
        for (String string : allStrings) {
            sb.append(string).append("\n");
        }
        historyText.setText(sb.toString());
    }

    ...
    ...
    ...
                        

Then you can start the application and experiment with it. The result should look similar to that shown in the screenshot below:

As an exercise, redesign the user interface of the "WordTopComponent" in such a way that a JList displays the filters.