Using NetBeans with the JBoss Getting Started Guide

Installing the Software

Before you begin, you need to have the following software installed on your computer:

• NetBeans IDE 5.0, the beta release, or higher (download).
• JBoss Application Server v4 (download). This tutorial was developed using JBoss Application Server v4.0.2, but should work with other releases as well.
• Java Standard Development Kit (JDK^TM) version 1.4.2 (download) or 5.0 (download).

Installing the Example Code

Getting Started with JBoss v4.0 uses the Duke's Bank example program from the J2EE tutorial. The J2EE tutorial example code must therefore be installed.

1. Install the J2EE 1.4 tutorial (download). Unpacking the archive file will create a j2eetutorial folder.
2. Download startguide40.zip from this page (click the Download button that is next to the JBoss AS Getting Started Guide entry). The startguide40.zip file contains jbossj2ee-src.zip. The jbossj2ee-src.zip contains supplementary source files necessary for the J2EE tutorial to work with the JBoss application server. Unpack the jbossj2ee-src.zip file to the j2eetutorial folder.
3. The j2eetutorial/examples/bank/nbproject folder contains project files for the NetBeans IDE that are not needed for this tutorial and will in fact cause a conflict because they do not specify the Ant script provided by JBoss. So remove the j2eetutorial/examples/bank/nbproject folder and all of its contents.
4. Edit j2eetutorial/jboss-build.properties and specify the installation location of the JBoss application server. This is the folder that was created when you unpacked the JBoss application server archive file. An example is:

               jboss.home=C:/tools/jboss-4.0.2
           

Registering the JBoss Application Server

Before you can use JBoss with the NetBeans IDE you have to register a local instance of the JBoss Application Server.

1. In the NetBeans IDE, choose Tools > Server Manager from the main window.
2. Click Add Server. Select JBoss Application Server 4.0 and give a name to the instance. Then click Next.
3. Specify the location of the local instance of the application server. Then click Next.
4. Specify the server domain. This tutorial was developed using the default domain. Then click Finish.

1. Choose File > New Project (Ctrl-Shift-N or Command-Shift-N on a Macintosh). Under Categories, choose Web. Under Projects, choose Web Application with Existing Ant Script. Click Next.
2. For Location specify the j2eetutorial/examples/bank folder. The IDE will fill-in the Build Script field with the build.xml file that it finds in the j2eetutorial/examples/bank folder. For this project you will need the Ant build script provided by JBoss, so click the Browser button next to the Build Script field and select the jboss-build.xml file instead.
3. For the Project Name specify JBossDukesBank. The default value for Project Location is fine, so you do not have to change it. An example is shown below (click for full size):



Click the Next button.

4. Later, in the Mapping Ant Commands section you'll learn more about the IDE's ability to map IDE commands to targets in an Ant build script. For now, just click the Next button again to advance past the Build and Run actions.
5. For the Web Pages Folder specify web and for the Context Path specify /bank. An example is shown below:



Click the Next button.

6. Additional source package folders could be added, but are not needed, so click the Next button again to advance past the Source Package Folders.
7. In order for the IDE's more advanced editor features to work (code completion, refactoring, etc.), the editor needs Classpath information for the .jar files used by the application. There are four .jar files that are installed with the JBoss application server that therefore need to be added to the Java Source Classpath:
   • server/default/lib/jboss-j2ee.jar
   • server/default/lib/javax.servlet.jar
   • server/default/lib/javax.servlet.jsp.jar
   • client/jboss-jaxrpc.jar

   Use the Add JAR/Folder button to add all four .jar files to the Java Source Classpath; an example is shown below (click for full size):



Click the Next button.

8. Additional .jar files could be added if needed to support code completion in the JSP files, but are not necessary for this project. So just click the Finish button. The IDE will create the project and display it in the Projects window. An example is shown below:

1. Select Window > Navigator to display the IDE's Navigator window.
2. Expand the src node under the JBossDukesBank project.
3. Expand the com.sun.ebank.web package.
4. Click the Dispatcher.java entry. Notice how the Navigator window updates to display the methods from the Dispatcher class.
5. In the Navigator window, double-click the doPost entry. The IDE's editor opens the Dispatcher.java file and displays the doPost method, as shown below (click for full size):



6. Take some time to explore other source files in the Duke's Bank example application. There are several handy features that make browsing source code easier, including:
   • Source code line numbers. Select View > Show Line Numbers.
   • Class hierarchy indicators. The up-arrow icon in the left margin next to the first line of the doPost method indicates that it overrides a method from another class. Point your mouse cursor at the up-arrow icon to find out more.
   • Hyperlinks. In the doPost method there is a reference to the AccountHistoryBean class. Hold down the Control key (on a Macintosh, use the Command key) and point your mouse cursor at AccountHistoryBean. The editor will change its color to blue and underline it, as shown below. Clicking AccountHistoryBean while it is underlined will open the AccountHistoryBean.java source file.

     

   • Go Back/Go Forward. As you move from file to file in the editor, you can navigate much like you would with a web browser. The arrow buttons on the editor's toolbar can be used to navigate backward and forward. Keyboard shortcuts are also available, Alt-K for backward and Alt-L for forward.

1. In section 4.1.2 of Getting Started with JBoss v4, the first Ant target you are told to run is compile. When you used the NetBeans IDE to create the JBossDukesBank project, the IDE's Build Project command got mapped to the compile target in jboss-build.xml. So to invoke the compile target, simply right-click the JBossDukesBank project and select Build Project from the context menu.
2. An Output window will open at the bottom of the IDE and its last line should start with BUILD SUCCESSFUL.
3. Continuing with the instructions in section 4.1.3 of Getting Started with JBoss v4, you need to run the following four targets, in this order: package-ejb, package-web, package-client, and assemble-app. The NetBeans IDE makes this very easy to do (for more options on using Ant, see Mapping Ant Commands below). Select the entry for jboss-build.xml in the Projects window. The IDE's Navigator window will display all the Ant targets. An example is shown below:



To invoke an Ant target, right-click the target in the Navigator window and then select Run Target from the context menu. Or, instead of choosing Run Target when you right-click the target, you can choose Create Shortcut and create a toolbar button, menu item, or keyboard shortcut. That way, you can integrate the target into the IDE. Either way you choose to do it, be sure to invoke each of these four targets one time each: package-ejb, package-web, package-client, and assemble-app.

4. Section 4.1.7 of Getting Started with JBoss v4 describes setting up the Hypersonic database that is bundled with JBoss. Before proceeding, make sure the JBoss application server is running. To do this from within the NetBeans IDE, click on the tab for the Runtime window and then expand the Servers entry. You will see an entry for JBoss in the list of servers. An example is shown below.

   

   If the application server is running, it will have a green arrow icon () next to its name, as shown in the example below.

   If the JBoss application server is not running, then right-click its entry and select Start.

5. Section 4.1.7.1 of Getting Started with JBoss v4 describes changes that must be made to the JBoss application server's hsqldb-ds.xml file. You can use the NetBeans IDE to make those changes. Select File > Open File and then navigate to your JBoss installation's server/default/deploy folder, which contains the hsqldb-ds.xml file. Select the file and then click the Open button. The IDE will open the file in an editor window. There are two changes to make. At the top of the file the connection-url needs to be changed so that the tcp connection is used. At the bottom of the file the mbean for use with tcp connections needs to be un-commented. For full details, refer to section 4.1.7.1. After you have made the changes, select File > Save.
6. Invoke these Ant targets, in this order: db-create-table, db-insert, and db-list. The db-list target should display data in the IDE's Output window; an example is shown below.

   

7. Continuing with section 4.1.8 of Getting Started with JBoss v4, the next step is to deploy the sample application's .ear file. To do this you can invoke the deploy Ant target directly. Or, since the IDE's Deploy Project command is mapped to the deploy Ant target, you can right-click the JBossDukesBank project entry and select Redeploy Project from the context menu.
8. In your browser, specify the URL for the application's logon screen: http://localhost:8080/bank/main. Note, if you configured the JBoss application server with a port number other than 8080, use that port number instead. An example is shown below.

   

   To use the application, specify 200 for the Customer and j2ee for the Password.

9. The final Ant target that section 4.1.8 of Getting Started with JBoss v4 instructs you to invoke is run-client. The run-client target starts a standalone client application. When you created the JBossDukesBank project, the NetBeans IDE mapped its Run Project command to the run-client target, so you can just right-click JBossDukesBank and select Run Project from the context menu to start the standalone client application. After the client application starts, select its Customer Admin > View Customer Information option and specify 200 for the Customer ID. The customer's information will be displayed, as shown in the example below.

   

1. If you are logged on to the example browser-based application, log off by clicking the Logoff link in the upper-right corner of the application's user interface. If the standalone application is running, click the X icon in its upper-right corner to close the application.
2. In the NetBeans IDE, you will need to add the .jar and .war files that you want to debug to the list of outputs created by your project. To do this, right-click the JBossDukesBank entry in the Projects window and select Properties from the context menu.
3. Select the Output category and then click the Add JAR/Folder button.
4. Choose the jar folder and then select the app-client.jar, bank-ejb.jar, and web-client.war files. Then click the Open button. The end result should look like the example below (click for full size).

   

   Click the OK button.

5. Click the Runtime tab so that you can see the list of installed servers. Right-click the entry for the JBoss application server and select Stop. An example is shown below.

   

   Note: In the beta release of NetBeans v5.0, there is a bug with some configurations that requires this step to be done twice. If the IDE displays an error message that indicates a timeout, then dismiss the error dialog and repeat this step.

6. In the Runtime tab right-click the entry for the JBoss application server and select Start in Debug Mode.
7. Set a breakpoint in the doGet method of the com.sun.ebank.web.Dispatcher class by opening Dispatcher.java and then placing the cursor on the first line of the doGet method. Then select Run > Toggle Breakpoint. A quicker way to set a breakpoint is to just click the left margin next to the line where you want the breakpoint. Either way, the IDE will display the line with a red background; an example is shown below (click for full size).

   

8. Select Run > Debug Main Project. Since this project was created with its own pre-existing Ant build script, the NetBeans IDE refers to it as a freeform project. As would be expected, the project's Ant build script does not contain a target that can be used to start the IDE's debugger. The NetBeans IDE, therefore, offers to create an appropriate target; an example of the dialog displayed is shown below.

   

   Click the Generate button.

9. The NetBeans IDE opens two editor windows. The first is for ide-targets.xml. This file contains Ant targets that are for use by the IDE only. This allows the IDE to add Ant targets for your project without modifying your Ant script (which in this project is jboss-build.xml). The second editor window is for debug.properties. Modify the jpda.address and client.url entries in debug.properties, so that they match the values shown below.

      jpda.address=8787
      client.url=http://localhost:8080/bank/main
   

   Save your changes to debug.properties and then select Run > Debug Main Project.

10. After the IDE's debugger starts, your browser will automatically be set to the application's logon screen: http://localhost:8080/bank/main. Logon to the application by specifying 200 for the Customer and j2ee for the Password.
11. After you click the application's Submit button, the debugger will stop the application at the breakpoint that was set earlier in the servlet. An example is shown below (click for full size).

    

12. Take some time to experiment with the debugger's features. To control the debugger, select a command from the Run menu. To display debugger windows, select Window > Debugging. When you are finished debugging, select Run > Finish Debugger Session.

Project Files

The Projects window displays a high level logical view with only the files that are most likely to be modified on a regular basis. To see all the files in a project's folder, click the Files tab. As an example, the web.xml file is in the dd/web folder, as shown in the example below.

If you right-click the web.xml entry and select Open the IDE will display a custom deployment descriptor editor.

Mapping Ant Commands

This tutorial described the creation of a freeform project, which uses an existing Ant build script. In order for the NetBeans IDE to make use of an existing Ant build script, it must map its own commands to targets within that build script. You can control how this mapping is done by right-clicking the project and selecting Properties. Then click on Build and Run. An example is shown below.

Project Templates

In this tutorial a Web Application project was created. The NetBeans IDE supports several other project templates. The example application consists of more than just web components; it has Enterprise Java Beans (EJBs), and a standalone application client. The NetBeans IDE could be used to create additional projects, one for each type of deliverable component. As an example, an EJB Module with Existing Ant Script project could be created. The IDE would then provide a significant set of EJB related features, starting with a logical view of the EJBs, as shown below.

Extending the IDE

The NetBeans IDE provides all the standard functionality you need for working with JBoss. If you have specific requirements that are not met by the IDE, however, then you can take advantage of the IDE's comprehensive support for creating extensions, which are called modules. By creating modules, you can easily enhance the IDE to provide additional JBoss functionality. For example, maybe you want to add project samples for JBoss to the New Project wizard. Or maybe you want to provide a special file template for the creation of the JBoss deployment descriptors. In the first case, you would use the Project Template wizard. In the second case, you would use the Wizard wizard, as shown below (click for full size).

These File Types are available for module projects; just select New > File/Folder. For more information about extending the NetBeans IDE, refer to http://platform.netbeans.org/tutorials.

Additional Tutorials

For more information about using NetBeans IDE 5.0, see the following resources:

• NetBeans IDE 5.0 Quick Start Guides:
  • For J2SE Applications
  • For Web Applications
  • For Web Services
  • For J2EE Applications
  • For J2ME MIDP Applications
• NetBeans IDE 5.0 Import Guides:
  • For J2SE Applications
  • For Web Applications
  • For J2EE Applications
  • For J2ME MIDP Applications
• NetBeans IDE Support and Docs page

To send comments and suggestions, get support, and keep informed on the latest developments on the NetBeans IDE J2EE development features, join the mailing list .

Acknowledgements: Thanks to Geertjan Wielenga and Brian Leonard for their review and comments on this article.