Importing Java EE Applications in NetBeans IDE 5.5
This document explains how to import existing JavaTM EE 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.5 (download).
- Sun JavaTM System Application Server Platform Edition 9.0 (download)
- Java Standard Development Kit (JDKTM) version
or 5.0 or version 6.0 (download)
Note: NetBeans IDE 5.5 also supports Sun Java System Application Server 8.1 and 8.2. 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.5/Sun Java System Application
Server bundle, the local application server is registered automatically.
- Choose Tools > Server Manager from the main window.
- Click Add Server. Select Sun Java System Application Server and give
a name to the instance. Then click Next.
- Specify the installation directory of the application server (for example,
C:\Sun\Appserver).
- Leave the Register Local Default Domain radio button selected and
select a domain.
- 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.
- Click Finish.
- Click the Runtime window and expand the Servers node. The Sun Java System Application
Server is listed.
- 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
- 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.
- Choose File > New Project (Ctrl-Shift-N).
- Choose Enterprise > Enterprise Application with Existing Sources. Click
Next.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Right-click the Libraries node and choose Add Project.
- 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 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.
- 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.
- 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.
- 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.
- Right-click the cmpcustomer-ejb project and choose New > File/Folder.
From the Sun Resources category, select the JDBC Resource template and click
Next.
- Select Use Existing JDBC Connection Pool and select cmpcustomerPool
from the combo box.
- 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.
- Expand the Configuration Files node and double-click sun-ejb-jar.xml.
- In the CMP Resource section, type jdbc/cmpcustomer in the Jndi
Name field. Save and close the file.
Running the Application
- If the cmpcustomer project is not the main project, right-click the project
node and choose Set Main Project.
- 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
- 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.
- Choose File > New Project (Ctrl-Shift-N).
- Choose Enterprise > EJB Module with Existing Sources. Click Next.
- 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.
- 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.
- Set the target application server for the project.
- 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.
- 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.
- 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
- 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.
- Choose File > New Project (Ctrl-Shift-N).
- Select Enterprise > EJB Module with Existing Ant Script. Click Next.
- 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"> ]>
- Name the project cmpcustomer-ejb-freeform and specify a location for the project folder.
Then click Next.
Linking Ant Targets with IDE Commands
- 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
- Click Next.
Configuring Source Folders
- 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.
- 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.
- In the Server Type combo box, choose Sun Java System Application Server.
- 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.
- Click Next.
- 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.
- In the Source Level combo box, select JDK 1.4. This setting tells the
IDE which Java SE 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.
- 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.
- In the Projects window, right-click the cmpcustomer-ejb-freeform project node
and choose Properties.
- 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.
- In the Projects window, right-click the cmpcustomer-ejb-freeform project node and
choose Build Project to generate the build outputs.
- Right-click the cmpcustomer-ejb-freeform project node and choose Generate Javadoc
for Project to generate the Javadoc output directory.
- Right-click the cmpcustomer-ejb-freeform project node and choose Properties.
- 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.5, see the following resources:
To send comments and suggestions, get support, and keep informed on the latest
developments on the NetBeans IDE Java EE development features, join
the nbj2ee@netbeans.org mailing list.
Copyright and Trademark Notice