Importing J2EE Applications in NetBeans IDE 5.0

Feedback

This document explains how to import existing J2EETM enterprise applications and into NetBeansTM IDE projects. As an example, we will import the cmpcustomer example application that is included in the J2EE 1.4 SDK Samples.

The cmpcustomer application has one src folder that contains the enterprise application deployment descriptors, one cmpcustomer-ejb folder containing the EJB module source, and a cmpcustomer-war folder containing the source for the Web application client.

The cmpcustomer sample source code is located in the Sun/AppServer/samples/ejb/cmp/apps/cmpcustomer folder. If you do not have the J2EE 1.4 SDK Samples, you can download them at http://java.sun.com/j2ee/1.4/download.html. Make sure you extract the samples to the samples folder of your application server installation directory.

Note: This guide uses the same project source to demonstrate how to import a project in the following ways:

  • Import an entire enterprise application.
  • Import only the EJB module.
  • Import the EJB module and use the module's existing Ant script to build and deploy the project.

In the IDE, however, a source root can only be used in one project at a time. If you want to create each of the three types of projects, you have to delete each existing project before creating the new one. You can delete a project by right-clicking its project node in the Projects window and choosing Delete Project. In the Delete Project dialog box, make sure that the option to delete the project sources is not selected.

Getting Started

Before we get going, let's get all of the necessary software and set up our environment.

Installing the Software

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

  • NetBeans IDE 5.0 (download).
  • Sun JavaTM System Application Server Platform Edition 8.2 (download)
  • Java Standard Development Kit (JDKTM) version 1.4.2 (download) or 5.0 (download)

Note: NetBeans IDE 5.0 also supports Sun Java System Application Server 8.1. Version 8.1 of the application server uses the PointBase database server instead of Apache Derby, but the procedure for importing projects is the same.

Registering the Sun Java System Application Server

Before you can work with J2EE projects, you have to register an instance of the Sun Java System Application Server. If you installed the NetBeans IDE 5.0/Sun Java System Application Server bundle, the local application server is registered automatically.

  1. Choose Tools > Server Manager from the main window.
  2. Click Add Server. Select Sun Java System Application Server and give a name to the instance. Then click Next.
  3. Specify the installation directory of the application server (for example, C:\Sun\Appserver).
  4. Leave the Register Local Default Domain radio button selected and select a domain.
  5. Optionally, click Next and enter your administrator username and password. If you do not want to store the username and password in your IDE user directory, you can leave these fields blank. The IDE will prompt you every time it needs the information.
    Note: The default admin password is adminadmin.
  6. Click Finish.
  7. Click the Runtime window and expand the Servers node. The Sun Java System Application Server is listed.
  8. Right-click the application server's node and choose Start Server.

Importing an Entire Enterprise Application

You can import an entire enterprise application at once if the following is true:

  • The project adheres to the Java BluePrints recommendations for enterprise application project structure.
  • You do not want to use your existing Ant build script to build the enterprise application's modules. The IDE will create a build script for each modules.

Note: Some older versions of the cmpcustomer example are not BluePrints compliant. If the IDE does not let you open the example as a project, go to http://java.sun.com/j2ee/1.4/download.html and download the latest version of the J2EE samples.

Creating the Projects

  1. If you have already created a project using any of the source roots in the cmpcustomer example, right-click the project and choose Delete Project. In the Delete Project dialog box, make sure that the option to delete the project sources is not selected.
  2. Choose File > New Project (Ctrl-Shift-N).
  3. Choose Enterprise > Enterprise Application with Existing Sources. Click Next.
  4. In the Location field, type or browse to the folder that contains the enterprise application. This should be the folder that contains the src folder for the enterprise application and the top-level folder for each of the application's modules. In our example, you should enter the samples/ejb/cmp/apps/cmpcustomer folder.
  5. Name the project cmpcustomer (or give it any name you like) and specify a location for the project folders. We will call this location NetBeans_projects. For Enterprise Applications with Existing Sources, you cannot create the project folders in the same location as the source folders.
  6. Select the J2EE version for the project. This setting defines which version of the J2EE specification the IDE uses for generating code and maintaining the deployment descriptors. In our example, we are going to leave the J2EE version at J2EE 1.4.
  7. Set the target application server for the project and click Finish. The IDE creates a standard IDE project for the enterprise application and each of its modules.

Configuring the Projects

When you create the projects, IDE displays a warning to check the context-root element in your sun-application.xml file. The reason for this is that the IDE does not know the names of the module JAR files and WAR files and gives them its own names. The IDE therefore creates new deployment descriptors with the corrected JAR and WAR file names. The original deployment descriptors are also saved. You should use the new deployment descriptors, but you need to change some of the settings.

  1. Set the correct context root for the web module in both application.xml and sun-application.xml. Double-click application.xml and change the context-root element from cmpcustomer-war to customer. Then double-click sun-application.xml to open it in the visual editor, expand the EAR node, and select the cmpcustomer-war.war node. Change the Context Root field from cmpcustomer-war to customer.
  2. In the cmpcustomer-ejb project, expand Configuration Files, double-click sun-ejb-jar.xml, and set Create Tables at Deploy to True. Choose File > Save All to save your changes.
  3. The web module's LocalStrings.properties file is in the wrong location. Move the file from the cmpcustomer-war/src/conf folder to the cmpcustomer-war/src/java folder.

Setting the Project Classpath

Because an enterprise application's deployment descriptors do not contain any information about the classpath relationships between the application's modules, you have to configure the classpath yourself.

  1. In the Projects window, expand the Libraries node for the cmpcustomer-war project node. Notice that it only lists the project's target JDK and application server.
  2. Right-click the Libraries node and choose Add Project.
  3. Select the project folder for the cmpcustomer-ejb project (NetBeans_projects/cmpcustomer/cmpcustomer-ejb), and click OK. The EJB module's classes are added to the Web module's classpath.
    Note: You have to select the project folder for the cmpcustomer-ejb project in NetBeans_projects, not the cmpcustomer-ejb source folder in the samples folder.

Configuring the Database and JDBC Resource

The cmpcustomer application is set to create all of the database tables when you deploy the application. All you have to do is specify the Derby database in which the tables are created. When you register the Sun Java System Application Server 8.2 in the IDE, a preconfigured Derby database called sample is created in the .netbeans-derby folder in your home directory. You can use this database as the target database.

In order for your EJB module to access this database, you have to create a connection pool and a database resource for the database on the server. You can do so using Server Resource files in the EJB module project.

  1. Right-click the cmpcustomer-ejb project and choose New > File/Folder. From the Sun Resources category, select the JDBC Connection Pool template and click Next.
  2. In the JDBC Connection Pool Name field, type cmpcustomerPool. Select the Extract from Existing Connection radio button and select the sample database from the combo box. Click Next.
  3. Type app for the value of the Password property and click Finish. The connection pool node appears under the project's Server Resources node.

Now let's create the database resource that connects to the connection pool.

  1. Right-click the cmpcustomer-ejb project and choose New > File/Folder. From the Sun Resources category, select the JDBC Resource template and click Next.
  2. Select Use Existing JDBC Connection Pool and select cmpcustomerPool from the combo box.
  3. Type jdbc/cmpcustomer in the JNDI Name field and click Finish. A node for the resource appears under the project's Server Resources node.

Finally, we have to configure the EJB module to use the correct JNDI name when looking up the database.

  1. Expand the Configuration Files node and double-click sun-ejb-jar.xml.
  2. In the CMP Resource section, type jdbc/cmpcustomer in the Jndi Name field. Save and close the file.

Running the Application

  1. If the cmpcustomer project is not the main project, right-click the project node and choose Set Main Project.
  2. Choose Run > Run Main Project. The IDE builds the EAR file for the project and deploys it to the application server.

Troubleshooting

  • The IDE does not let you complete the New Wizard and complains that the selected location does not contain a BluePrints structured application. You probably have an old version of the cmpcustomer example. Go to http://java.sun.com/j2ee/1.4/download.html and download the latest version of the J2EE samples.
  • When you try to create a customer or search for customers, you get an EJBException. Check that the Derby database server is running by choosing Tools > Derby Database > Start Derby Server.
  • None of the JSP pages have the correct display text. Make sure that you moved the LocalStrings.properties file from the src/conf folder to the src/java folder in the web application.
  • When you try to create a customer or search for customers, you get the following error: Create Customer Failed : javax.ejb.EJBException: Transaction aborted; nested exception is: javax.transaction.RollbackException: Transaction marked for rollback. Check that you correctly created and configured the JDBC resource for the example. Also, check that the cmpcustomerPool connection pool exists and contains the default password. To view the connection pool, go to the Runtime window and expand JDBC > Connection Pools for the application server. To check that it contains the password, double-click cmpcustomerPool, click the ellipsis button for Properties, and make sure the Password property is set to app.

Importing Individual Modules

You may need to import individual modules in the following situations:

  • Your enterprise application does not meet BluePrints recommendations.
  • Your module is a stand-alone EJB module or Web application.
  • You want to use your own Ant build script to build, deploy, and debug your module.

As an example, we will import the cmpcustomer-ejb module by itself. There are two templates you can use to import an individual EJB module:

Using the IDE to Build, Deploy, and Debug

When you create a standard EJB module project, the IDE creates an Ant build script and properties files that control how your project is built and deployed. The IDE updates the Ant script as you set options for the project.

Creating a Project

  1. If you have already created a project using any of the source roots in the cmpcustomer example, right-click the project and choose Delete Project. In the Delete Project dialog box, make sure that the option to delete the project sources is not selected.
  2. Choose File > New Project (Ctrl-Shift-N).
  3. Choose Enterprise > EJB Module with Existing Sources. Click Next.
  4. In the Location field, type or browse to the folder that contains the EJB module source. Generally this should be the folder that contains the src folder for the EJB module, but it can be any folder. The IDE accommodates any EJB module structure. In our example, you should enter the samples/ejb/cmp/apps/cmpcustomer/cmpcustomer-ejb folder.
  5. Name the project cmpcustomer-ejb-standard (or give it any name you like) and specify a location for the project folder. Note you cannot use the cmpcutomer-ejb folder as the project folder, since it already contains a build.xml which would conflict with the build.xml that the IDE generates.
  6. Set the target application server for the project.
  7. Select the J2EE version for the project. This setting defines which version of the J2EE specification the IDE uses for generating code and maintaining the deployment descriptors.
  8. Click Next. The Existing Source and Libraries page is where you would configure more complicated EJB module projects. You can add multiple source directories, specify the location of the conf folder if it is in an irregular location, and specify a libraries folder. When you create the project, all of the folders and JAR files in the libraries folder are added to the project's classpath.
  9. Click Finish without changing any of the settings in the Existing Source and Libraries page. The IDE creates the EJB module project.
    Note: If you want to run the module, you may have to configure the database and JDBC resource.

Using Your Own Ant Script to Build, Deploy, and Debug

When you create a free-form EJB module project, the IDE uses your Ant build script to build and deploy your project. In the IDE, you have to set up the project to mirror the settings that are contained in the project's Ant script. You also have to write your own targets to debug the project in NetBeans.

Note: Before you can use the cmpcustomer application's Ant script to build and deploy the project, you have to provide information about your server installation and domain configuration in the Sun/AppServer/samples/common.properties file.

Creating a Project

  1. If you have already created a project using any of the source roots in the cmpcustomer example, right-click the project and choose Delete Project. In the Delete Project dialog box, make sure that the option to delete the project sources is not selected.
  2. Choose File > New Project (Ctrl-Shift-N).
  3. Select Enterprise > EJB Module with Existing Ant Script. Click Next.
  4. Type or browse to the folder that contains the EJB module source. Generally this should be the folder that contains the src folder for the EJB module, but it can be any folder. The IDE accommodates any EJB module structure. In our example, you should enter the samples/ejb/cmp/apps/cmpcustomer/cmpcustomer-ejb folder. The IDE fills in the name of the build script for you.
    Note: The build script for the cmpcustomer-ejb module imports the standard common-ant.xml build script that is in the Sun/AppServer/samples/ directory. The build script assumes that your samples directory is located in the AppServer directory as well. If you downloaded the samples separately and installed them in a different location, the IDE complains that the build.xml is not a valid build script. Open the build script in a text editor and edit the following line to point to the correct location of common-ant.xml:
    <!DOCTYPE project [ <!ENTITY include SYSTEM "../../../../../common-ant.xml"> ]>
  5. Name the project cmpcustomer-ejb-freeform and specify a location for the project folder. Then click Next.

Linking Ant Targets with IDE Commands

  1. In the Build and Run page of the wizard, specify which targets the IDE should run for project commands. The IDE suggests targets for each action. Specify the following targets for each action:
    • Build Project: core
    • Clean Project: clean
    • Generate Javadoc: javadocs
    • Run Project: update
    • Test Project: leave blank
    • Deploy Project: update
  2. Click Next.

Configuring Source Folders

  1. In the EJB Sources page of the wizard, specify the folder that contains the module's deployment descriptors. In our example, the Configuration Files Folder is cmpcustomer/cmpcustomer-ejb/src/conf.
  2. In the Server Resources Folder field, you can specify a folder that contains any server resource files the IDE generates. Server resource files are XML files that the IDE uses to automatically configure resources, like JDBC connection pools and data sources, on the Sun Java System Application Server.
  3. In the Server Type combo box, choose Sun Java System Application Server.
  4. In the J2EE Version combo box, choose J2EE 1.4. This setting defines which version of the J2EE specification the IDE uses for generating code and maintaining the deployment descriptors.
  5. Click Next.
  6. In the Source Packages page of the wizard, you can add additional source roots and test package roots. Since our example only has one source root, you do not need to configure anything on this page.
  7. In the Source Level combo box, select JDK 1.4. This setting tells the IDE which J2SE platform's classes to use in code completion and error highlighting. It does not set the target JDK for your project. You must set the target JDK in your Ant script.
    Note: The IDE checks all of its registered Java platforms for a platform with a matching version number and uses this platform to provide Javadoc and source code for debugging. To register a Java platform and specify the platform's source code and Javadoc location, choose Tools > Platform Manager.
  8. Click Finish. The cmpcustomer-ejb-freeform project is displayed in both the Projects window and the Files window.

Configuring the Project Classpath

In free-form projects, the Ant script manages all of your classpath settings. In the IDE, you declare the project's classpath to match the settings defined in your Ant script. These settings are used to provide code completion, error highlighting, and refactoring for your project.

For all free-form EJB module projects, you have to add the j2ee.jar library from your local Sun Java System Application Server installation to the classpath.

  1. In the Projects window, right-click the cmpcustomer-ejb-freeform project node and choose Properties.
  2. Click Java Sources Classpath in the right panel of the dialog box. Click Add JAR/Folder. Navigate to the lib folder in your application server installation folder, select j2ee.jar, and click Open.

Configuring Project Outputs

In order to set up dependencies between projects, the IDE needs to know the name and location of your build outputs and Javadoc output directory. You should declare these in the project's properties.

  1. In the Projects window, right-click the cmpcustomer-ejb-freeform project node and choose Build Project to generate the build outputs.
  2. Right-click the cmpcustomer-ejb-freeform project node and choose Generate Javadoc for Project to generate the Javadoc output directory.
  3. Right-click the cmpcustomer-ejb-freeform project node and choose Properties.
  4. Click Output in the right panel of the dialog box. Specify each of the build outputs and the Javadoc output directory and click Close.

Next Steps

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

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