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:

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.

  1. Choose Tools > Server Manager from the main window.
  2. Click Add Server. Select your server and give a name to the instance. Then click Next.
  3. 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

  1. Choose File > New Project (Ctrl-Shift-N).
  2. Select Web > Web Project with Existing Sources. Click Next.

Setting the project name and location

  1. In Location, click Browse to select your web application's web module root.
  2. 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".
  3. 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.
  4. Leave the Set as Main Project box selected. Click Next.

Selecting the existing sources and libraries

  1. In Web Pages Folder, check that the location is correctly filled.
  2. Optionally, add JAR files to the Libraries Folder.
  3. 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.
  4. Optionally, add JUnit test package folders.
  5. 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.

  1. Right-click the project to which you want to add a required project and choose Properties.
  2. Click Libraries in the left panel of the Project Properties dialog box. The Libraries pane lists all of the project's required projects.
  3. Click Add Project.
  4. 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.
  5. 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

  1. Choose File > New Project (Ctrl-Shift-N).
  2. Select Web > Web Project with Existing Ant Script. Click Next.

Setting the project name and location

  1. 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:
  2. enterprise2\jakarta-tomcat-5.5.7\webapps\tomcat-docs\appdev\sample
  3. 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.
  4. Leave the Set as Main Project box selected. Click Next.

Linking Ant targets to IDE commands

  1. 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.
  2. Click Next.

Setting the web sources

  1. In the Web Pages Folder, check that the application's "web" folder is correctly filled.
  2. In the Context Path text box, type /MyProject. Click Next.

Setting the source package folders

  1. 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.
  2. Optionally, add JUnit test package folders.
  3. 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

  1. 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.
  2. 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:

  1. Edit the app.name property in the File and Directory Names section to configure the context path:
         <property name="app.name" value="MyProject"/>
  2. 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"/>
  3. 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"/>
  4. 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" />
  5. 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.

  6. (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

  1. 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.
  2. 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:

  1. Expand the nbproject folder in the Files window and double-click project.xml so that it opens in the Source Editor.
  2. 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>
  3. In the context-menu section, add your new ide-action:
        <ide-action name="debug"/>
  4. Now, when you right-click the project node, you will see the Debug Project item.
  5. Use the debug target.
If you do not have your own debug target, generate and use one as follows:
  1. 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.
  2. 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.

  3. 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.

  1. 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.
  2. 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.

  3. Once the server has started in debug mode, choose Run > Debug Main Project (F5). The application is deployed and is attached to the debugger.
  4. 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.
  5. 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.
  6. 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.