C H A P T E R  5

Running, Debugging, and Deploying Your Web Application

This chapter assumes you have considered how to develop your application. It also assumes you are ready to run, debug, and deploy your application using the IDE. The chapter provides a high-level view that ties together the tasks you perform in test running and modifying your application. Then it offers some details on individual programming tasks.

See Chapter 4 for a description of developing your web application from standard components. Such components might include JSP pages, servlets, filters, and beans.

It is recommended that you work through the Forte for Java 4, Community Edition Tutorial before building your own web application with Forte for Java 4 IDE. The tutorial contains more information on many aspects of the web module development process.


Running and Debugging Tasks

This section provides an overview of the tasks involved in running a web module using the IDE. When working on a web application, it often makes sense to proceed in an iterative fashion. You redeploy and check that the application works each time a component or set of components is modified. You repeat this process each time you add a new component or set of components to your application. Each task refers to a section later in the chapter that provides more details. The IDE's online help for the JSP/Servlet module also provides information on these tasks.

To run a web module using the IDE:

1. Make modifications to the component (JSP page, servlet, and so forth). This process is covered for each component type in Chapter 4.

2. Configure the web module. The IDE takes care of much of the deployment configuration with default settings. Then it provides editors, called property sheets, for you to edit the deployment descriptor file. See Configuring the Web Module Deployment Descriptor.

3. Test run your application in the IDE. See Test Running Web Modules on the Internal Tomcat 4.0.1 Server.

4. Track data flow within HTTP transactions using the HTTP Monitor window. Use the monitor to examine data sent by JSP pages and servlets, and the data within the web application. The monitor can also be used during the debugging process to replay previous requests. For additional information on using the HTTP monitor, see Using the HTTP Monitor to Debug a Web Application.

5. If necessary, debug your JSP pages, servlets, and web modules using source-level debugging. For more, see Source-Level Debugging.

6. Package the web module as a WAR file and deploy it. A web application archive is a single file that contains all of the components of a web application. For details, see Packaging Your Web Applications.


Configuring the Web Module Deployment Descriptor

The deployment descriptor file is located in the web module's WEB-INF directory. It provides the necessary configuration information to the web module's deployment environment, that is, the servlet container. The deployment descriptor can contain descriptions of servlets, filters, or tag libraries that are used by the web application. It can also include requirements for external resources and security, environment parameters, and other component-specific and application-specific parameters.

In the IDE, you can modify the deployment descriptor file in two ways:

Some web modules are simple, containing only JSP files and servlets. To deploy simple web modules on the internal Tomcat 4.0.1 server, you might not need to change the deployment descriptor. Many changes are taken care of by the IDE, sparing you the effort. In some cases, however, you need to modify the following deployment descriptor elements:

Many other web application properties can be specified in the deployment descriptor. Refer to the Java Servlet Specification, v2.3 for details.



Note - In order for changes to the deployment descriptor to take effect, you must redeploy the web module. Use the Execute (Force Reload) action to perform this task.



Using Property Sheets to Edit the web.xml File

Use the web.xml property sheet to edit the various elements that make up the web.xml file. This property sheet is also referred to as the deployment descriptor editor. These properties appear on three tabbed panes:

You can modify the values in the deployment descriptor for each deployment situation. You do not have to recompile or recode your application. This feature is useful when you need to provide external server data. Examples might include the name of an SMTP (Simple Mail Transfer Protocol) mail server or a database server, user name and password information, or paths to locations for external resources such as HTML templates.

Registering Servlets and Filters

When you create a servlet or filter, the New wizard immediately asks for the important information. You might want to update the deployment descriptor entry to specify special features, such as:

For more information about declaring servlets and filters, see Declaring the Servlet in the Deployment Descriptor and Declaring the Filter in the Deployment Descriptor. For details on updating deployment descriptor entries for servlets and filters, see "Servlets Property Editor" and "Filters Property Editor" in the JSP/Servlet online help.

Registering Tag Libraries

Whether you need to register your tag library in the deployment descriptor depends on how it is packaged. You can use the Tag Libraries Property Editor for the deployment descriptor to view any entries for the tag libraries in the web module

Automatic Registration

If your tag library JAR file has a default TLD (that is, META-INF/taglib/tld), an entry for the tag library is made in the deployment descriptor file when the JAR file is added to the WEB-INF/lib directory.

If a tag library JAR file contains multiple TLD files, then it does not require a default TLD. The standard tag library (JSTL) is an example of this situation. In this case, an explicit tag library entry is not required in the deployment descriptor. The JSP translation extracts the URI fields from the TLD files in any JAR file in the WEB-INF/lib directory to create an implicit tag library mapping.

Automatic registration occurs as long as there is a taglib directive within the JSP page. For more information, see Inserting Custom Actions From a Tag Library Into a JSP Page.

Explicit Registration

Not all tag libraries have a default TLD specified. You can use the Tag Libraries Property Editor to explicitly create a tag library entry in the deployment descriptor.

For example, the following taglib directive makes the TLD located at /WEB-INF/tlds/myTagLib.tld accessible through the URI myTags:

<taglib>	<taglib-uri>/myTags</taglib-uri>	<taglib-location>/WEB-INF/tlds/myTagLib.tld</taglib-location></taglib>

For details, see Packaging and Deploying a Custom Tag Library.

If you remove a tag library declaration, it does not automatically remove the corresponding JAR file from the WEB-INF/lib directory.

Specifying the Default URI Within the Taglib Element

The Tag Libraries Property Editor is primarily used to indicate which tag libraries have been added. It also enables you to change the URI mappings of the tag libraries. Each entry corresponds to a taglib element in the deployment descriptor. Refer to the URI mapping at the top of your JSP file to use the specified tag library. The URI reference also ensures that custom tag library code completion works. For more information, see Using Tag Libraries.

Use the Tag Libraries Property Editor to add, edit, or remove references to the tag library JAR file from the selected web module. The addition or removal of items using this property editor does not affect the tag library JAR file in the WEB-INF/lib directory.

If you choose Add JSP Tag Library from the selected web module's contextual menu, an entry for each tag library is created in the deployment descriptor. In addition, when you create a new tag library within a web module, the IDE adds the deployment descriptor entry.

Using the IDE to Edit the web.xml File in the Source Editor

Expert users can edit the web.xml file directly by double-clicking the web.xml icon. You can also edit it using an external text editor. When you save your changes, the IDE automatically parses the file. It then displays any errors in the Output window on the XML Parser tab.


Using Tomcat 4.0

The Tomcat 4.0 Plugin enables you to use the Tomcat 4.0.1 web server within the IDE. A server plugin is a module of the IDE sometimes provided by a web server vendor. The plugin facilitates the use of the IDE in the configuration of applications and their deployment to the server. The Tomcat 4.0 plugin is installed in the IDE by default. Hence, the Tomcat 4.0 node appears under the Installed Servers node in the Server Registry on the Explorer's Runtime tab.

A Tomcat 4.0 web server comes pre-configured to work with the plugin in the IDE. It appears as the Internal node under the Tomcat 4.0 node. By default, this web server is used to compile and execute web components such as JSP pages and servlets. You can configure the Tomcat 4.0 plugin to integrate with other Tomcat 4.0 web servers installed on your computer. See "Adding a Tomcat 4.0 Installation" in the JSP/Servlet online help for details.

You can use Tomcat to:

  • Deploy and delete web modules and web module groups
  • Set general properties for installations of the server
  • Start, restart, and stop the server
  • Edit the configuration file for the server

Test Running Web Modules on the Internal Tomcat 4.0.1 Server

You can test run a web module within the IDE using the Execute action or Execute (Force Reload) action. Either action deploys the web module on the default web server, which is configured as Tomcat 4.0.1 in the IDE. It then executes the application from a client web browser using your system's default browser. The IDE deploys the web module to the context designated by the Context Root property of the web module's WEB-INF node. The context value must have a leading back slash, for example, /test. The IDE makes iterative testing quick and easy during development by performing the setup for you. The Execute (Force Reload) action restarts the server. Use Force Reload if you have modified servlets, filters, libraries, or other Java code.

When the IDE is executing, files are saved. The IDE recompiles any servlets, but it does not change JSP files until they are actually loaded.

To set a web module's execution properties, right-click the web module's WEB-INF directory. It is located on the Filesystems tab of the Explorer. Then choose Properties from the contextual menu.

If you want to execute several web modules as a group, you must first create a web module group. For details, see Creating and Executing a Web Module Group. A web module group is an IDE-specific construct. It enables you to specify a set of web modules to deploy together on a web server with a single action. Each module in the group must have a unique context root. The context root ensures that requests are properly sent to the correct module by the web server.

As you execute web modules and web module groups, you can use the HTTP Monitor. It enables you to examine the flow of record data. See Using the HTTP Monitor to Debug a Web Application for more information.

The Tomcat 4.0 Server Configuration File

The Tomcat 4.0. Server Configuration file, called server.xml, is automatically modified by the IDE when web applications are deployed or executed. You can also edit Tomcat 4.0. configuration information manually in the server configuration file. For more information, see "Editing the Tomcat 4.0 Server Configuration File" in the Tomcat 4.0 Plugin online help.

Setting Up the Web Server Environment for Database Access

You can configure a generic web module to use a database. Place the JDBC drivers for your database systems where the servlet container can find them. An example might be mm.mysql.jar for the open source MySQL database.

  • To copy the directory, mount the directory containing the JAR file for the driver. Then copy and paste it into the web module. If the file for the driver has a .zip extension, change the name to end in .jar before copying it to the web module's WEB-INF/lib directory. The Java Servlet Specification, v2.3 no longer recognizes zip files as libraries.
  • To add the JAR file as a shared resource to the internal Tomcat 4.0.1 server, copy it into the tomcat401_base/lib directory under the IDE root. Note that files in this directory are shared among all users of this IDE installation.
  • To add the JAR file as a shared resource to an external Tomcat 4.0 installation, copy the JAR file into the lib directory under the CATALINA_HOME directory of the installation. Typically, this directory is the same as the server installation's root directory. For other servers, follow the vendor's instructions.
See the External Execution Process property description in the "Setting Tomcat Installation Properties" section of the Tomcat 4.0 Plugin online help for details.

If you are using the bundled PointBase Network Server database, the JDBC driver is already configured to work with the internal Tomcat 4.0.1 server.



Note - Adding the database driver to your system classpath does not necessarily make it accessible to your web server.



You can test communications using your database driver with the Database Explorer in the IDE. This practice ensures that the driver you are using works properly with both the Java language and the IDE.

Executing a Single Web Module

To execute a single web module, select the WEB-INF node. Then choose the Execute action from the contextual menu. This action saves all the modified files in your web module and recompiles the class files. JSP pages are recompiled when they are obtained and used by the web server.

The web module executes and is displayed in your selected default browser. The execute action instructs the browser to request the root of the web module. This action causes the server to attempt to serve a welcome file within the root directory. This attempt has been specified in the web module's deployment descriptor. If the server cannot find one, it simply lists the contents of the directory.

When executing on the internal or external Tomcat server, utilize the HTTP Monitor. It enables you to track the requests to the web module and the data flow inside the web application. See Using the HTTP Monitor to Debug a Web Application for more information. If problems occur, check the Output window that appears upon execution.

Classpath Construction

When a web module is executed in the Tomcat server, a classpath is constructed. The classpath ensures that all necessary classes and libraries in the web module can be located. By default, the order of web module elements in the classpath for servlet execution is:

1. WEB-INF/classes

2. Any JAR files in WEB-INF/lib

3. Other classes or libraries, depending on your server's implementation of class loading

If necessary, you can modify the Tomcat execution classpath. See "Setting Tomcat 4.0 Installation Properties" in the Tomcat 4.0 Plugin module online help for details.

Creating and Executing a Web Module Group

The IDE provides a mechanism to deploy several web modules together so they can be run at the same time. You create a web module group node in the IDE and add web modules to it. Then you use the execute actions.

To create and execute a web module group, you perform three main tasks:

1. Create a web module group object.

2. Set a URL mapping for each of the web modules to be loaded as part of the web module group.

3. Specify a target server for the web module group. If no target server is specified, the default web server is used.

See "Creating a Web Module Group" in the JSP/Servlet online help for details on these tasks.

You can set a target server for an individual web module. You perform this task by editing the Target Server property for that web module. However, a component of that web module might be executed while the web module is running as part of a web module group. In this case, the web module runs within the server specified by the Target Server property for the web module group. For more information, see "Setting WEB-INF Properties" in the JSP/Servlet online help.



Note - that specifying a target server is optional. If no target server is specified, the default server from the server registry is used.



The web module group file should be placed outside a web module. This placement ensures that it is not inadvertently included when being packaged for deployment.

Executing on Tomcat Servers

You might have your own installation of the Tomcat 4.0 web server on your system. In this case, configure the IDE's Tomcat 4.0 plugin module to use that instance rather than the internal server. See "Adding a Tomcat 4.0 Installation" in the Tomcat 4.0 Plugin online help for details.

The integration with the Tomcat web server has two modes of operation:

  • Full mode. HTTP monitoring and JSP and servlet debugging features are enabled. The IDE adds some elements to the server's server.xml configuration file.
  • Minimum mode. HTTP monitoring and JSP and servlet debugging are not available. The server's configuration file is modified only to add the deployed module's context path.

You can set your own installation as the default web server. Alternatively, you can specify your installed server be used for a designated web module. For more information, see the section on setting the Target Server property in "Creating a Web Module Group" in the JSP/Servlet online help.


Debugging Web Applications

The IDE provides two tools for debugging web applications:

  • The HTTP Monitor
  • Source-level debugging for both JSP files and servlets

Using the HTTP Monitor to Debug a Web Application

The HTTP Monitor is a lightweight tool that can be used as an alternative or a complement to source-level debugging. It is provided by the IDE for collecting data related to the execution of JSP files and servlets in the servlet container. The data records generated by the HTTP Monitor streamline the work involved in debugging JSP files and servlets. The HTTP Monitor records information about each request that comes into the server. This data includes incoming and outgoing cookies, session information maintained on the server, the servlet environment information, and HTTP headers.

The HTTP Monitor provides a view into the data flow among web application components of the web application. You can use the monitor to examine the properties of the HTTP requests. You can also use it to inspect any data maintained on the server whenever a request is processed by a JSP page or a servlet. For example, you can find out if:

  • The JSP page or servlet received any form data with the request. If so, you can determine what the values were.
  • An HTTP session was associated with the request. If so, you can determine what attributes were set before or after the JSP page or servlet was activated.
  • The JSP page or servlet received or created any cookies.

If you discover a bug while test running, use the HTTP Monitor to view data records associated with requests leading up to it. You can quickly find out if the problem was caused by a JSP page or servlet not receiving the data it expected. In this case, you can determine which resource started the problem. By using the Edit and Replay feature, you can tweak requests before resending them. This technique enables you to determine if sending different data fixes the bug. Often this knowledge is enough to identify the lines of code causing the problem. If not, you might narrow down an individual JSP page or servlet to step through with the source-level debugger. For details, see Source-Level Debugging.

Once you have fixed the bug, use the HTTP Monitor again to replay the request or requests that exposed the problem. This technique can save time if reproducing the steps involves entering data through a browser, for example.

The HTTP Monitor enables you to save recorded request data. If you find a problem you do not have time to fix immediately, save the relevant records and go through the process described above later. You can also, for example, save a sequence of requests representing an application sanity test. You can then run it every time you change something.

In summary, use the monitor to:

  • View data, store information for future sessions, and replay and edit previous requests
  • Determine which component is sending or receiving incorrect data before you begin source-level debugging

For details on error sources in web applications, see Common Errors in Web Applications. For details on source-level debugging, see Source-Level Debugging.

Starting the HTTP Monitor

The HTTP Monitor consists of a top level window within the IDE, and a server-side component that runs on the execution server. To open the HTTP Monitor, choose HTTP Monitor from either the IDE's View menu or Debug menu. For more information, see "Monitoring Data Flow on the Web Server" in the HTTP Monitor module online help.

Viewing Monitor Data Records

The HTTP Monitor consists of two panels. On the left, the HTTP Monitor records panel contains a tree view of known records. On the right, the HTTP Monitor records display panel presents the data associated with the selected monitor record.

In the tree view, the All Records category contains two subcategories: Current Records and Saved Records. Individual monitor data records reside in either of these subcategories. Entries in Current Records are available only during the current IDE session. Current monitor data records persist across restarts of the web server. They are only cleared on a restart of the IDE or when deleted. Entries in Saved Records persist until deleted.

Sometimes, a data record is created as the result of one resource dispatching the request to another resource. An example of this situation is a JSP forwarding to a servlet. In this case, the record is shown as an expandable node in the tree. To see how the request was processed by any other resources activated by the forward or include actions, expand the node.

Monitor data records in all categories can be sorted according to various criteria using the buttons above the tree view. For details on sorting criteria, see "Using the HTTP Monitor Toolbar" in the HTTP Monitor online help.

For each selected monitor data record, corresponding information appears in the HTTP Monitor records display panel. The records display panel consists of these panes:

  • Request. Shows the request URI, method, query string, parameters or posted data, protocol, client IP address, scheme, exit status, and list of request attributes before and after the request.
  • Cookies. Shows a list of incoming and outgoing cookies. For incoming cookies, information includes the cookie name and the cookie value. For outgoing cookies, information includes the name, the value, the expiration time, which domain the cookie should be sent to. Outgoing cookie information also includes which path the cookie should be sent to and whether it requires a secure protocol.
  • Session. Shows status of any HTTP session associated with the request before and after the request's processing. The pane describes whether the session was created as a result of the request's processing. Session properties such as ID, creation time, last accessed time, and the maximum inactive interval are displayed. It also shows session attributes set before and after the request's processing.
  • Servlet. Shows the name of the servlet as configured, class name, package name, and optional servlet information. It also displays relative and translated paths.
  • Context. Shows the name of the servlet context created from the web module and the absolute path to the context. This pane displays all the context attributes set when the request started processing. It also shows any initialization parameters given to the request.
  • Client and Server. Shows data about the application that generated the HTTP request. The data includes which protocol it used, its IP address, and if the information is provided, which application was used. The pane displays what locales, encodings, character sets, and file formats the application supports. It also shows data about the servlet engine that processed the request. This data includes the Java version, platform, hostname, and port number of the HTTP service.
  • Headers. Shows the HTTP headers that came in with the request. The headers are constructed by the HTTP client, for instance, a browser. The exact nature of headers varies from client to client. They usually include information such as the nature of the client, for instance, software and operating system. They also contain language preferences and the file formats the browser accepts.

Replaying Requests

You can replay HTTP requests associated with the Current Records and Saved Records subcategories of the All records tree view. Replaying a request makes the server process a request identical to the request that was recorded. The response is shown in the IDE's default web browser, just as it is when you execute a web module.

This feature can simplify the process of testing the correction to a bug. For example, you might have found a bug and modified some code in a resource that processes form data. To verify the correction, you would usually load the form into the browser, enter data, and submit it. Using the Replay action on the original request record, you could bypass the need to reenter the data. Another example would be if you needed to step through several requests before you could reproduce a bug. The bug might be in a resource that is part of the implementation of a checkout. Moreover, users cannot enter the checkout unless they have placed something in the shopping cart. In that case, you could replay several recorded requests. This action would place the web application in a state where the bug correction could be confirmed.

See "Editing and Replaying Requests in the HTTP Monitor" in the HTTP Monitor online help for details.

Editing and Replaying a Specified Request

The Edit and Replay dialog box enables you to edit a number of properties prior to resending the request information. These properties include the request parameters and/or the query string, the cookies, and the headers. An option is also provided to send the request to a different server, if it fully supports the HTTP Monitor.

You can use the Edit and Replay dialog box to send requests to a different server.

Use the Edit and Replay feature to:

  • Check if a web component that is not functioning works with different input
  • Change items such as the locale setting of the client without having to modify your browser's settings

Specifying Session Cookies for Replay Requests

If you replay a request, the HTTP Monitor, by default, uses the session cookie the browser is sending, if it sends a cookie. The monitor does not use the session cookie recorded with the request. Using Tomcat 4.0, you can control this behavior so the recorded cookie, or a cookie you specify, is used instead. See "Editing and Replaying Requests in the HTTP Monitor" in HTTP Monitor online help for details.

Source-Level Debugging

When a JSP page is executed as part of a web application, a servlet is actually what is executed. The JSP page is translated into a servlet, called the generated servlet. The generated servlet is then compiled and run. When using the Tomcat server, the IDE maintains a mapping between lines in the original JSP source and lines in the generated servlet. This feature enables you to debug JSP pages from either:

  • The perspective of the JSP file itself
  • The source of the servlet into which the JSP file was translated

Source-level debugging consists of several enhancements to the standard IDE debugging environment. These enhancements enable JSP and generated servlet files to be viewed simultaneously. Breakpoints set in one are automatically reflected in the other. However, breakpoints removed from the generated servlet are not removed from the corresponding JSP source file.

A JSP file, with all its statically included files, maps to a single servlet file. (See Using the <%@include%> Directive for details.) Specifically, one line in the JSP file maps to one or more lines in the servlet file. The servlet also contains code generated for all JSP pages, with no explicit representation in the JSP source.

Using the Debugger

To debug your application using the IDE's source-level debugging features, you set breakpoints, view the generated servlet, and start the debugger, as described in the following sections.

Setting Breakpoints

Setting breakpoints in a regular servlet or class file is no different from debugging other Java classes. For JSP pages, you can set breakpoints in either the JSP source file or in the generated servlet.

If you set a breakpoint in a JSP source file, it is automatically reflected in the generated servlet. (Remember that no one-to-one-line correspondence exists between the two files). If you set a breakpoint in a generated servlet, it is reflected in the JSP page with one exception. If the breakpoint is in part of the servlet derived from a statically included JSP page, it is not reflected. Removing a breakpoint from the JSP file removes the corresponding breakpoint in the generated servlet. However, the reverse is not the case.

Viewing the Generated Servlet

From the Explorer, click the Filesystems tab. Select the JSP source file. Right-click to display the contextual menu. If the JSP file has not yet been compiled, that is, the View Servlet action is not enabled, choose Compile from the contextual menu. Once the JSP file has been compiled, choose View Servlet from the contextual menu.

The Source Editor opens with a view of the generated servlet code. If the JSP file is already opened in the editor, you can also view its generated servlet from the editor's contextual menu. Right-click inside the editor window, and select the Show code in servlet action.

By default, the generated servlet file appears in a new tabbed pane of the Source Editor.

Note that the generated servlet is not automatically updated if you make changes to the JSP source. After you make changes, run the View Servlet or the Show code in servlet action again to see the new version.



Note - Sometimes you encounter a compilation error while compiling a JSP page, and the problem is not obvious when you are looking at the JSP source code. In this situation, it often helps to look at the generated servlet. This practice can help in finding mistakes such as missing quotes.



Starting the Debugger

Start the debugger by selecting the resource you would like to debug in the Explorer. Then choose the Start item from the IDE's Debug menu. It is not necessary to stop and restart the debugger to debug a different resource. With the web module running, either follow a link in the browser window, or type the URL directly into the browser's location field.

When debugging a helper class that cannot be run on its own, you must start the debugger on a different resource, for example, on the web module's WEB-INF node.

To debug a web module group, select the WEB-INF directory from any web module within the web module group. Then choose Start from the Debug menu.

For more information about standard debugging in the Forte for Java IDE, see "Debugging a Program" in the Core IDE online help.

When you start the debugger, the HTTP Monitor window appears. See Using the HTTP Monitor to Debug a Web Application for more information on using the HTTP Monitor to aid in debugging.

Setting JSP Debugger Options

You can customize your JSP debugging sessions through the IDE's global options as follows:

  • Specify the class of files in which errors are to be shown with the JSP source file and generated servlet file open. From the Options window, expand the Building node. Select the JSP & Servlets node. Then in the Properties pane, choose Show in Servlet Source or Show in JSP Source from the combo box for the JSP Compiler Errors option.
  • Designate whether to skip static HTML lines between JSP tags in the JSP source, as well as the corresponding lines in the generated servlet source when debugging. Static HTML lines are lines that do not contain any JSP element or scripting language. From the Tools menu in the IDE's menu bar, choose Options. Then expand the Debugging and Executing node. Then choose JSP & Servlets Settings. In the Properties pane, set Skip Static Lines to True.

For details, see "JSP Debugger Options" in the JSP/Servlet online help.

Viewing Both JSP and Servlet Files During Debugging

You can view the JSP source file and its generated servlet file side by side during debugging. This features helps you detect JSP errors during the debugging cycle. You can set breakpoints and step through code with both files in sync.

Open the generated servlet in the Source Editor. (See Viewing the Generated Servlet for details.) With the JSP file still selected in the Explorer, choose Open from the contextual menu. By default, the JSP source file code appears in a new tabbed pane of the Source Editor. At this point, you can see the servlet code or the JSP code, but not both at the same time. Right-click the current view in the editor, and choose Clone View from the contextual menu. This action opens a new Source Editor window with a view on the same JSP code.

Now two editor windows are displayed side by side. One window provides a view of the JSP code. Another window offers a view of the servlet code. You must compile the JSP file in order to show the changes in the generated servlet. For details, see "Viewing JSP and Servlet Files During Debugging" in the JSP/Servlet online help.



Note - Debug commands apply to the view, that is, file, with focus at the time the command is issued. To issue a command on the alternate view, click that window to set focus. Then proceed with your command.




Packaging Your Web Applications

During development, a web module is typically executed in its unpacked form. This practice makes it easy to update frequently. However, when you are ready to deploy, you can package the web module into a Web ARchive (WAR) file. This practice facilitates the transfer process. Once you have created a WAR file, all files under the web module filesystem are included by default. For directions on using the IDE to package a web module directory into a WAR file, see "Packaging a Web Module" in the JSP/Servlet online help.

In the IDE, you can:

  • Create a WAR file from a web module
  • Specify WAR packaging options
  • View the contents of WAR files generated from web modules
  • Mount WAR files as web modules

Building a WAR File From a Web Module

You can build a WAR file from a web module in one of two ways:

  • Select the root of the web module in the Filesystems Explorer. Then choose Export WAR File from the Tools menu
  • Right-click the web module's WEB-INF node. Then choose Export WAR File from the contextual menu.

Then you must specify a name for the WAR file. All files under the web module filesystem are included in your WAR file by default.

For additional information, see "Packaging a Web Module" in the JSP/Servlet online help.

Specifying Options

Packaging options for web modules appear on Archive tab of the WEB-INF node property sheet. You can add files that are external to the web module to the WAR package. Files can be added from any filesystem mounted in the Explorer. Possible choices include all files, all files except .java (the default option), and all files except .java, .jar, and .form. Alternatively, you can specify a regular expression such as *.txt or Pro*. You can choose either the predefined filter or a regular expression, but not both the filter and the expression. For details, see "Editing Web Module Archive Properties" in the JSP/Servlet online help.

Viewing Contents

You can view the contents of a WAR package using the WAR Contents window. Files included in a WAR package are determined by properties set using the Archive tab of the WEB-INF property sheet.

The WAR Contents window lists the files to be included when the web module is exported as a WAR file. It also provides path and extension information for each file.

By default, the list is sorted alphabetically by path name. Sort the list alphabetically for another column by clicking the header for that column. For more information, see "Viewing the Contents of a WAR File" in the JSP/Servlet online help.


Packaging and Deploying a Custom Tag Library

For a JSP page to reference a custom tag library, the tag library must exist within the web module containing the JSP page. When you are using a tag library within a production web module, it is a good idea to package it as a JAR file. This practice makes it easier to use your tag library in other web modules. The tag library can be added to a web module in any of four ways:

  • By putting the tag library into the Tag Library Repository, then adding it to the desired web module. The JSTL already resides in the Tag Library Repository and can be added to JSTL libraries. See "Using the JSP Standard Tag Library" in the JSP/Servlet online help for more information.
  • By adding the JAR file from the filesystem to a web module.
  • By cutting and pasting the JAR file into the appropriate WEB-INF/lib directory. Then by modifying the Taglib element in the deployment descriptor. It must map to the JAR file containing the desired tag library. See "Editing the Web Module Deployment Properties" in the JSP/Servlet online help for more information about editing the deployment descriptor.
  • By testing the tag library in place. This method is convenient for testing your tag library as you develop it. For details, see Testing Tag Libraries.

Adding a tab library JAR file to a web module also mounts it in the Filesystems pane of the Explorer.

Packaging a Tag Library as a JAR File

You package a tag library into a JAR file to make it easier to deploy. To create the Tag Library JAR, choose Create Tag Library JAR from the tag library's contextual menu. When you create a Tag Library JAR, the IDE creates a file with a .jar extension. It also creates an associated jarContent file, which adds additional classes or packages to the library. The jarContent file is also referred to as the recipe file.

For information on the properties of the newly created JAR file, see "JAR Recipe Nodes in the Explorer" in the JSP/Servlet online help.



Note - Be sure that your tag handlers are generated and compiled before creating the tag library JAR file.



Deploying a Tag Library Using the Tag Library Repository

You can deploy a tag library using the Tag Library Repository.

To add a tag library from the Tag Library Repository to a web module, choose Add JSP Tag Library from the WEB-INF directory's contextual menu. Then choose the Find in Tag Library Repository item, which displays the Tag Library Repository Browser dialog box. Select one or more items from the list, and click the OK button. The appropriate JAR files for the selected tag libraries are added to the WEB-INF/lib directory along with any necessary entries in the deployment descriptor.

When the tag library JAR files are added to the web module, they are also mounted in the Filesystems tab of the Explorer

Deploying a Tag Library by Adding a JAR File From the Filesystem

If a tag library JAR is in another web module or mounted filesystem in the IDE, you can use the Add JSP Tag Library right arrow Find in Filesystem action. This action locates the JAR and copies it into the WEB-INF/lib directory of your web module. You can add a tag library JAR file from any mounted filesystem to a web module. Right-click the WEB-INF node. Choose Add JSP Tag Library, then Find in Filesystem. If necessary, the deployment descriptor is automatically updated to include an entry for the tag library. This entry is used to map the tag library to a URI for your JSP pages to use in accessing the tags

Deploying a Tag Library by Copying and Pasting a JAR File From Another Module or Filesystem

If there is a tag library JAR in another web module or mounted filesystem in the IDE, you can choose the Copy action from the contextual menu on the Explorer's WEB-INF node. Then paste the JAR file into the WEB-INF/lib directory of your web module. When copying and pasting a tag library JAR file into a web module's WEB-INF/lib directory, a taglib element in the deployment descriptor might be created. In most cases, the IDE adds the Ttaglib element automatically. You can verify that the correct information is present. To perform this task, follow the instructions in "Packaging and Deploying a Custom Tag Library" in the JSP/Servlet online help.


Including a Web Module Within a J2EE Web Application

When using the Enterprise Edition of the Forte for Java IDE, you can create a J2EE application from an existing EJB module or web module. Alternatively, you can create the application from an Explorer filesystem or package node. In both cases, after instructing the IDE to create the new application, the new J2EE application's node appears in the Explorer. Then you can begin adding modules to the application.



Note - You must assemble a web module with an EJB module in order to build an enterprise (J2EE) application.



A J2EE application is composed of EJB modules, or web modules, or both. You create J2EE applications in the IDE, either from an existing EJB module or from a filesystem in the Explorer. After creating an J2EE application, you can add web modules to it.

For details on adding a web module to a J2EE application, see "Adding an EJB or Web Module to a J2EE Application" in the J2EE Application Assembler online help.

For more information on assembling web modules into a web application, see Building J2EE Applications With Forte for Java.