Importing Existing Web Applications into NetBeans IDE 5.0
Feedback
There are two project templates you can use to create a NetBeans
IDE 5.0 project from an existing web application:
- Web Project with Existing Sources.
Use
this project template to create a standard web project. A standard web project
uses the IDE to compile, run
and debug a web application.
- Web Project with Existing Ant Script.
Use
this project template to create a free-form web project. A free-form web project uses your own Ant script to compile and run
a web application, and to start the NetBeans debugger.
In this document, you first use a
hypothetical web application to learn how to import source code that does not
have its own Ant build script. In this first scenario, the NetBeans IDE creates an Ant build
script for you.
In the second scenario, you import the Tomcat Web Server's sample "Hello World" application, which is bundled with the
NetBeans IDE 5.0 installation.
This sample application has its own Ant build script. During this part of the
document, you learn how to import your source code if you want to use your own
Ant build script to work with your web application.
Choosing the Server
Before you start writing code, you have to make sure you have all of the necessary software
and that your project is set up correctly.
Installing the Software
Before you begin, you need to install the following software on your
computer:
Optionally, you can download and use one of the following application servers:
- Sun Java System Application Server
- JBoss Application Server
- WebLogic Application Server
However, the Tomcat
Web Server that is bundled with the IDE provides all the support you need for two-tier web applications
such as the ones described in this import guide.
Application servers are only required when you want to develop enterprise applications.
Registering the Server
The bundled Tomcat Web Server is registered with the IDE automatically.
However, before you can deploy to
the Sun Java System Application Server, JBoss, or WebLogic, you have to register a local instance
with the IDE. If you installed the NetBeans IDE 5.0/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 your server and give
a name to the instance. Then click Next.
- Specify the server information, the location of the local instance of
the application server, and the domain to which you want to deploy.
Using the IDE to Build, Run, and Debug
When you create a standard web application 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.
Selecting the project type
- Choose File > New Project (Ctrl-Shift-N).
- Select Web > Web Project with Existing Sources. Click
Next.
Setting the project name and location
- In Location, click Browse to select your web application's web module root.
- In Project Name, type the name of your project. The name is also used to set the
context path.
Note: The context path cannot contain
spaces. If your project name contains spaces, they are replaced by underscores in the context
path. For example, a project named "Servlet Examples"
would have a context
path consisting of "/servlet_examples".
- In Project Folder,
click Browse to select a folder to house your project.
Note: Your project folder cannot already contain a folder called nbproject,
because this is the name of the folder that the IDE creates to house the project-level files.
- Leave the Set as Main Project box selected. Click Next.
Selecting the existing sources and libraries
- In Web Pages Folder, check that the location is correctly filled.
- Optionally, add JAR files to the Libraries Folder.
- Specify the source package folders.
Note: The source root cannot be owned by another loaded project.
In addition, the source root cannot be owned by another compilation unit of
the same project. For examples, a source package folder cannot also be a test package folder
for the same project.
- Optionally, add JUnit test package folders.
- Click Finish. The project opens in the IDE. You can view its
logical structure in the Projects window and its file structure in the Files window.
Creating dependencies between projects
When you create separate projects for each of your source roots, you have to set up
the classpath dependencies between the projects. Typically you set up one main project
and several required projects. A required project is a project that has been added
to another project's classpath.
Note: The NetBeans IDE 4.1 Applet Tutorial
illustrates the usefulness of creating dependencies between projects.
- Right-click the project to which you want to add a required project and choose Properties.
- Click Libraries in the left panel of the Project Properties dialog box.
The Libraries pane lists all of the project's
required projects.
- Click Add Project.
- Select the project directory of the project whose JAR files you want to add
to the classpath. IDE project directories are marked with a (icon) badge.
When you select the project directory, the project name and project JAR files are displayed.
- Click Add Project JAR Files.
Running the application
- Choose Run > Run Main Project to run your web application.
Using Your Own Ant Script to Build, Run, and Debug
When you create a free-form web application 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 the IDE.
Selecting the project type
- Choose File > New Project (Ctrl-Shift-N).
- Select Web > Web Project with Existing Ant Script. Click
Next.
Setting the project name and location
- In Location, click Browse and select your web module root,
which, in this example, is the Tomcat Web Server's sample folder in your NetBeans IDE installation folder:
enterprise2\jakarta-tomcat-5.5.7\webapps\tomcat-docs\appdev\sample
- In Project Folder,
click Browse to select a folder to house your project.
Note: Your project folder cannot already contain a folder called nbproject,
because this is the name of the folder that the IDE creates to house the project-level files.
- Leave the Set as Main Project box selected. Click Next.
Linking Ant targets to IDE commands
- Link Ant targets in your Ant build script to project commands in the IDE:
- For Build Project, select compile.
- For Clean Project, select clean.
- For Generate Javadoc, select javadoc.
- For Run Project, select install.
- For Deploy Project, select reload.
- Click Next.
Setting the web sources
- In the Web Pages Folder, check that the application's "web" folder is correctly filled.
- In the Context Path text box, type /MyProject. Click Next.
Setting the source package folders
- In Source Packages Folder, check that the application's "src" folder is correctly filled.
Note: The source root cannot be owned by another loaded project.
In addition, the source root cannot be owned by another compilation unit of
the same project. For examples, a source package folder cannot also be a test package folder
for the same project.
- Optionally, add JUnit test package folders.
- In Source Level, choose the JDK that your Ant script compiles
and runs against. For this example, the JDK level is 1.5. Click Next.
Setting the classpath
- Click Add JAR/Folder and browse to the Servlet API in your NetBeans IDE installation folder:
enterprise2/jakarta-tomcat-5.5.7/common/lib
Note: The
classpath is not used for compilation or execution, because your Ant script
handles the classpath for these tasks. These settings tell the IDE which
classes to include in code completion and refactoring.
- Click Next and then click Finish. The project opens in the IDE. You can view its
logical structure in the Projects window
and its file structure in the Files window:
Customizing your Ant build script for use with the IDE
Expand the MyProject project node in the Projects window, open the build.xml file in the
Source Editor, and do the following:
- Edit the app.name property in the File and Directory Names section to configure the
context path:
<property name="app.name" value="MyProject"/>
- Edit the catalina.home property in the File and Directory Names section to define the entry
to point to the Tomcat Web Server. For example, if your version of the Tomcat Web Server is 5.5.7 and the NetBeans IDE is installed
in the default folder, use the following property statement:
<property name="catalina.home"
value="C:\Program Files\netbeans-5.0\enterprise2\jakarta-tomcat-5.5.7"/>
- If you want to change the Tomcat Web Server's default port number (8080), edit the manager.url property in the File and Directory
Names section:
<property name="manager.url"
value="http://localhost:8084/manager"/>
- Edit the Custom Ant Task Definitions section to set your environment's
CLASSPATH variable used by the IDE whenever it runs the Ant build
script. For example, your entry for the "deploy","list", "reload", and "undeploy"
tasks might be the following:
<path id="catalina.ant.cp">
<pathelement path="${catalina.home}/server/lib/catalina-ant.jar"/>
</path> <taskdef name="deploy" classname="org.apache.catalina.ant.DeployTask"
classpathref="catalina.ant.cp"/>
<taskdef name="list" classname="org.apache.catalina.ant.ListTask"
classpathref="catalina.ant.cp"/>
<taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask"
classpathref="catalina.ant.cp"/>
<taskdef name="undeploy" classname="org.apache.catalina.ant.ReloadTask"
classpathref="catalina.ant.cp" />
- Modify the install target and the reload target
by adding this line above the closing </target> tag:
<nbbrowse url="http://localhost:8084/MyProject"/>
The default install and reload targets do not display the application in a browser. When you
add the above line, the IDE's default browser is opened and the application is displayed as the final
step of these targets.
- (Optional) Add your own targets to the Ant build script and map them to project commands in the IDE.
For details, see the "Debugging the application" section below.
Deploying the application
- In the Runtime window (Ctrl-5), expand the Servers node and check that your
Tomcat Web Server is running. If it is not running, right-click your Tomcat Web Server's
instance node and choose Start from the contextual menu.
- Right-click the project in the Projects window and choose Run Project from the
contextual menu. When you linked Ant targets to IDE commands, you linked the install target
to the Run Project command. This is the target that is called when you run the project.
A progress
monitor window appears as the application is prepared for deployment.
Note: The first time that you run the application per session, the Tomcat Web Server asks you
for a username and password. The only acceptable username and password is
that of a user with a "manager" role. This is defined in the conf/tomcat-users.xml
file in the Tomcat Web Server's base directory. To identify the location of this directory,
right-click the Tomcat Web Server instance node in the Runtime window and select
Properties. In the Properties dialog box, the Base Directory property
points to the Tomcat Web Server's base directory.
After the application has successfully deployed, you can redeploy it by right-clicking the project in the
Projects window and choosing Redeploy Project from the
contextual menu. When you linked Ant targets to IDE commands, you linked the reload target
to the Deploy Project command. This is the target that is called when you run the project.
Debugging the application
Let's add a debug target to the project. When you run the debug target, it will run
the project in the debugger and allow you to step line by line through your code. The IDE
can generate a complete debug target for you. After you have provided some settings that
are specific to your project, you'll be ready to go. However, maybe you have your own debug
target already. In this case, take the following steps:
- Expand the nbproject folder in the Files window and double-click
project.xml so that it opens in the Source Editor.
- In the ide-actions section,
add the following action:
<action name="debug">
<script>path to my build script</script>
<target>name of my debug target</target>
</action>
- In the context-menu section, add your new ide-action:
<ide-action name="debug"/>
- Now, when you right-click the project node, you will see the Debug Project item.
- Use the debug target.
If you do not have your own debug target, generate and use one as follows:
- Choose Run > Debug Main Project (F5) from the main menu.
Note:You are prompted to let the IDE generate an IDE-specific debug target
in nbproject/ide-targets.xml.
Click Generate.
A complete debug target is generated in the new ide-targets.xml file
and all the properties are defined in the new debug.properties file.
The debug.properties file, ide-targets file, and projects.xml
file all open in the Source Editor. The debug.properties file has the following content:
jpda.session.name=MyProject
jpda.host=localhost
# Sun Java System Application Server using shared memory (on Windows)
# jpda.address=localhost4848
# jpda.transport=dt_shmem
# Sun Java System Application Server using a socket
# jpda.address=9009
# jpda.transport=dt_socket
# Tomcat using shared memory (on Windows)
jpda.address=tomcat_shared_memory_id
jpda.transport=dt_shmem
# Tomcat using a socket
# jpda.address=11555
# jpda.transport=dt_socket
src.folders=src
web.docbase.dir=web
# you can change this property to a list of your source folders
debug.sourcepath=${src.folders}:${web.docbase.dir}
# Client URL for Tomcat
client.url=http://localhost:8084/MyProject
# Client URL for Sun Java System Application Server
# client.url=http://localhost:8080
The properties above specify that the application will be deployed to
the Tomcat Web Server via shared memory. If you want to use the Sun Java System Application Server
instead, or if you want to use a socket connection, place a comment symbol (#) in front of the
Tomcat properties and remove those for the applicable connection using the Sun Java System
Application Server. Similarly, notice that the application will be deployed to http://localhost:8084/MyProject
by default, but that the port number for the Sun Java System Application Server is included. Finally,
the debug.sourcepath property specifies the folders that contain the files that you want
to debug. In this example, we will make the Java files and the web files available for debugging.
For more information on these properties, see Writing a Target to Debug your Web Application.
- In the Files window, expand the project node, expand the nbproject folder and
double-click the ide-targets.xml. The IDE has defined a complete debug target for you,
as shown below.
<target name="-load-props">
<property file="nbproject/debug.properties"/>
</target>
<target name="-check-props">
<fail unless="jpda.session.name"/>
<fail unless="jpda.host"/>
<fail unless="jpda.address"/>
<fail unless="jpda.transport"/>
<fail unless="web.docbase.dir"/>
<fail unless="debug.sourcepath"/>
<fail unless="client.url"/>
</target>
<target depends="-load-props, -check-props" name="-init"/>
<target depends="-init" if="netbeans.home" name="debug-nb">
<nbjpdaconnect address="${jpda.address}" host="${jpda.host}" name="${jpda.session.name}" transport="${jpda.transport}">
<sourcepath>
<path path="${debug.sourcepath}"/>
</sourcepath>
</nbjpdaconnect>
<antcall target="debug-display-browser"/>
</target>
<target name="debug-display-browser">
<nbbrowse url="${client.url}"/>
</target>
Any customization you need to do should be done in the debug.properties file, not
in the debug-nb target or the targets that support it.
Use the Debug Target
Before you can use the debug target, your web application must be deployed.
- In the Projects window, expand the web folder and double-click
hello.jsp so that it opens in the Source Editor.
Right-click in the grey bar on the left side of the Source Editor and choose Show Line Numbers.
Go to line 25 and click on the line number. A red bar appears. This is a breakpoint.
When you run the debugger, it will stop at this line. Set another breakpoint at line 29.
- In the Runtime window, expand the Servers node, right-click the
node for the Bundled Tomcat Web Server, and choose Start/Stop Server.
Uncheck the Automatically close this window when finished checkbox and then
click Stop Server in the Server Status dialog box.
Now click Start Server (Debug) in the Server Status dialog box.
- Once the server has started in debug mode,
choose Run > Debug Main Project (F5). The application is deployed
and is attached to the debugger.
- Click the JSP page link in the deployed application. In the IDE, you should
see something similar to the following in the Debugger Console:
Attaching to tomcat_shared_memory_id
User program running
Breakpoint reached at line 68 in hello.jsp by thread http-8084-Processor23.
Thread http-8084-Processor23 stopped at hello.jsp:25.
- Choose Run > Step Into (F7). You should see that the Debugger
has stepped into the next line (line 26) in the file:
User program running
Thread http-8084-Processor23 stopped at hello.jsp:26.
- Use F7 to continue stepping from line to line in your code.
Troubleshooting the Debug Target
See the Debugging section
in the NetBeans User FAQ.
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.
|