Web Modules

In the Java EE architecture, web components and static web content files such as images are called web resources. A web module is the smallest deployable and usable unit of web resources. A Java EE web module corresponds to a web application as defined in the Java Servlet specification.

In addition to web components and web resources, a web module can contain other files:

• Server-side utility classes (database beans, shopping carts, and so on). Often these classes conform to the JavaBeans component architecture.

• Client-side classes (applets and utility classes).

A web module has a specific structure. The top-level directory of a web module is the document root of the application. The document root is where JSP pages, client-side classes and archives, and static web resources, such as images, are stored.

The document root contains a subdirectory named /WEB-INF/, which contains the following files and directories:

• web.xml: The web application deployment descriptor

• Tag library descriptor files (see Tag Library Descriptors, page 229)

• classes: A directory that contains server-side classes: servlets, utility classes, and JavaBeans components

• tags: A directory that contains tag files, which are implementations of tag libraries (see Tag File Location, page 214)

• lib: A directory that contains JAR archives of libraries called by server-side classes

If your web module does not contain any servlets, filter, or listener components then it does not need a web application deployment descriptor. In other words, if your web module only contains JSP pages and static files then you are not required to include a web.xml file. The hello1 example, first discussed in Packaging Web Modules (page 39), contains only JSP pages and images and therefore does not include a deployment descriptor.

You can also create application-specific subdirectories (that is, package directories) in either the document root or the /WEB-INF/classes/ directory.

A web module can be deployed as an unpacked file structure or can be packaged in a JAR file known as a web archive (WAR) file. Because the contents and use of WAR files differ from those of JAR files, WAR file names use a .war extension. The web module just described is portable; you can deploy it into any web container that conforms to the Java Servlet Specification.

To deploy a WAR on the Application Server, the file must also contain a runtime deployment descriptor. The runtime deployment descriptor is an XML file that contains information such as the context root of the web application and the mapping of the portable names of an application's resources to the Application Server's resources. The Application Server web application runtime DD is named sun-web.xml and is located in /WEB-INF/ along with the web application DD. The structure of a web module that can be deployed on the Application Server is shown in Figure 25.

Figure 25. Web Module Structure

Packaging Web Modules

A web module must be packaged into a WAR in certain deployment scenarios and whenever you want to distribute the web module. You package a web module into a WAR by executing the jar command in a directory laid out in the format of a web module, by using the ant utility, or by using the IDE tool of your choice. This tutorial shows you how to use NetBeans 5.5 or ant to build, package, and deploy the sample applications.

To build the hello1 application with NetBeans 5.5, follow these instructions:

1.	In NetBeans 5.5, select FileOpen Project.
2.	In the Open Project dialog, navigate to: <INSTALL>/javaeetutorial5/examples/web/
3.	Select the hello1 folder.
4.	Select the Open as Main Project checkbox.
5.	Click Open Project Folder.
6.	In the Projects tab, right-click the hello1 project and select Build Project.

To build the hello1 application using the ant utility, follow these steps:

1.	In a terminal window, go to <INSTALL>/javaeetutorial5/examples/web/hello1/.
2.	Run ant. This target will spawn any necessary compilations, copy files to the <INSTALL>/javaeetutorial5/examples/web/hello1/build/ directory, create the WAR file, and copy it to the <INSTALL>/javaeetutorial5/examples/web/hello1/dist/ directory.

Deploying a WAR File

You can deploy a WAR file to the Application Server in a few ways:

• Copying the WAR into the <JavaEE_HOME>/domains/domain1/autodeploy/ directory.

• Using the Admin Console.

• By running asadmin or ant to deploy the WAR.

All these methods are described briefly in this chapter; however, throughout the tutorial, we use ant and NetBeans 5.5 for packaging and deploying.

Setting the Context Root

A context root identifies a web application in a Java EE server. You specify the context root when you deploy a web module. A context root must start with a forward slash (/) and end with a string.

In a packaged web module for deployment on the Application Server, the context root is stored in sun-web.xml.

To edit the context root, do the following:

1.	Expand your project tree in the Projects pane of NetBeans 5.5.
2.	Expand the Web Pages and WEB-INF nodes of your project.
3.	Double-click sun-web.xml.
4.	In the editor pane, click Edit As XML.
5.	Edit the context root, which is enclosed by the context-root element.

Deploying a Packaged Web Module

If you have deployed the hello1 application, before proceeding with this section, undeploy the application by following one of the procedures described in Undeploying Web Modules (page 45).

Deploying with the Admin Console

1.	Expand the Applications node.
2.	Select the Web Applications node.
3.	Click the Deploy button.
4.	Select the radio button labeled "Package file to be uploaded to the Application Server."
5.	Type the full path to the WAR file (or click on Browse to find it), and then click the OK button.
6.	Click Next.
7.	Type the application name.
8.	Type the context root.
9.	Select the Enabled box.
10.	Click the Finish button.

Deploying with asadmin

To deploy a WAR with asadmin, open a terminal window or command prompt and execute

   asadmin deploy full-path-to-war-file

Deploying with ant

To deploy a WAR with ant, open a terminal window or command prompt in the directory where you built and packaged the WAR, and execute

   ant deploy

Deploying with NetBeans 5.5

To deploy a WAR with NetBeans 5.5, do the following:

1.	In NetBeans 5.5, select FileOpen Project.
2.	In the Open Project dialog, navigate to your project and open it.
3.	In the Projects tab, right-click the project and select Deploy Project.

Testing Deployed Web Modules

Now that the web module is deployed, you can view it by opening the application in a web browser. By default, the application is deployed to host localhost on port 8080. The context root of the web application is hello1.

To test the application, follow these steps:

1.	Open a web browser.
2.	Enter the following URL in the web address box: http://localhost:8080/hello1
3.	Enter your name, and click Submit.

The application should display the name you submitted as shown in Figure 23 and Figure 24.

Listing Deployed Web Modules

The Application Server provides two ways to view the deployed web modules:

• Admin Console

  1. Open the URL http://localhost:4848/asadmin in a browser.
     
     

  2. Expand the nodes ApplicationsWeb Applications.
     
     

• asadmin

  1. Execute
     
     

     asadmin list-components

Updating Web Modules

A typical iterative development cycle involves deploying a web module and then making changes to the application components. To update a deployed web module, you must do the following:

1.	Recompile any modified classes.
2.	If you have deployed a packaged web module, update any modified components in the WAR.
3.	Redeploy the module.
4.	Reload the URL in the client.

Updating a Packaged Web Module

This section describes how to update the hello1 web module that you packaged.

First, change the greeting in the file <INSTALL>/javaeetutorial5/examples/web/hello1/web/index.jsp to

   <h2>Hi, my name is Duke. What's yours?</h2>

To update the project in NetBeans 5.5:

• Right-click on the project and select Build Project.

• Right-click on the project and select Deploy Project.

To update the project using the Ant build tool:

• Run ant to copy the modified JSP page into the build directory.

  • Run ant deploy to deploy the WAR file.

To view the modified module, reload the URL in the browser.

You should see the screen in Figure 26 in the browser.

Figure 26. New Greeting

Dynamic Reloading

If dynamic reloading is enabled, you do not have to redeploy an application or module when you change its code or deployment descriptors. All you have to do is copy the changed JSP or class files into the deployment directory for the application or module. The deployment directory for a web module named context_root is <JavaEE_HOME>/domains/domain1/applications/j2eemodules/context_root. The server checks for changes periodically and redeploys the application, automatically and dynamically, with the changes.

This capability is useful in a development environment, because it allows code changes to be tested quickly. Dynamic reloading is not recommended for a production environment, however, because it may degrade performance. In addition, whenever a reload is done, the sessions at that time become invalid and the client must restart the session.

To enable dynamic reloading, use the Admin Console:

1.	Select the Applications Server node.
2.	Select the Advanced tab.
3.	Check the Reload Enabled box to enable dynamic reloading.
4.	Enter a number of seconds in the Reload Poll Interval field to set the interval at which applications and modules are checked for code changes and dynamically reloaded.
5.	Click the Save button.

In addition, to load new servlet files or reload deployment descriptor changes, you must do the following:

1.	Create an empty file named .reload at the root of the module: <JavaEE_HOME>/domains/domain1/applications/j2ee-modules/ context_root/.reload
2.	Explicitly update the .reload file's time stamp each time you make these changes. On UNIX, execute touch .reload

For JSP pages, changes are reloaded automatically at a frequency set in the Reload Poll Interval field. To disable dynamic reloading of JSP pages, set the Reload Poll Interval field value to 1.

Undeploying Web Modules

You can undeploy web modules in four ways:

• NetBeans 5.5

  1. Ensure the Sun Java System Application Server is running.
     
     

  2. In the Runtime window, expand the Sun Java System Application Server instance and the node containing the application or module.
     
     

  3. Right-click the application or module and choose Undeploy.
     
     

• Admin Console

  1. Open the URL http://localhost:4848/asadmin in a browser.
     
     

  2. Expand the Applications node.
     
     

  3. Select Web Applications.
     
     

  4. Click the checkbox next to the module you wish to undeploy.
     
     

  5. Click the Undeploy button.
     
     

• asadmin

  1. Execute
     
     

     asadmin undeploy context_root

• ant

  1. In the directory where you built and packaged the WAR, execute
     
     

     ant undeploy