Sun Java System Web Server 7.0 Update 7 Developer's Guide to Java Web Applications

Chapter 9 Deploying Web Applications

This chapter describes how web applications are assembled and deployed in Web Server. The chapter has the following sections:

Web Application Structure

Web applications have a directory structure, which is fully accessible from a mapping to the application's document root (for example, /hello). The document root contains JSP files, HTML files, and static files such as image files.

A WAR file (web archive file) contains a complete web application in compressed form.

A special directory under the document root, WEB-INF, contains everything related to the application that is not in the public document tree of the application. No file contained in WEB-INF can be served directly to the client. The contents of WEB-INF include:

The web application directory structure follows the structure outlined in the Java EE specification. The following example shows a sample directory structure of a simple web application.

+ hello/
       |--- index.jsp
       |--+ META-INF/
       |  |--- MANIFEST.MF
       --+ WEB-INF/
          |--- web.xml
          --- sun-web.xml


Deployment Tools

Using Sun Java Studio Enterprise 8.1

Web Server supports Sun Java Studio Enterprise 8.1, Standard Edition. You can use Sun Java Studio to assemble and deploy web applications. Sun Java Studio Enterprise 8.1 is based on NetBeans™ software, and integrated with the Sun Java platform. Sun Java Studio Enterprise 8.1 also supports NetBeans 5.5.

Sun Java Studio support is available on all platforms supported by Sun Java Studio Enterprise 8.1. The plug-in for the Web Server is obtained in the following ways:

Note –

The Sun Java Studio Enterprise 8.1 for Web Server works only with a local Web Server (that is, with the IDE and the Web Server on the same machine).

For information about using the web application features in Sun Java Studio Enterprise 8.1, explore the resources at

The behavior of the Sun Java Studio Enterprise 8.1 plug-in for Web Server is the same as that for Sun Java System Application Server 8. If you’re using the Web Application Tutorial at the site listed above, for instance, you would set the Web Server instance as the default, and then take the same actions described in the tutorial.

For more information about Sun Java Studio Enterprise 8.1, visit

Note –

For basic information about using Sun Java Studio Enterprise 8.1 to debug web applications, see Using Developer Tools for Debugging.

Using NetBeans IDE 5.5

NetBeans IDE 5.5 is an integrated development environment to create, deploy, and software Java EE web applications. This section describes how to use the NetBeans IDE 5.5 to create and deploy the web applications for Web Server.

Procedure To Install NetBeans IDE 5.5

  1. Download NetBeans IDE 5.5 from and install it.

  2. After installation, launch the NetBeans IDE 5.5.

  3. Download the latest plug-in.

  4. Extract the org-netbeans-modules-j2ee-sun-ws7.nbm file.

  5. Select Update Center of NetBeans, from the Tools menu.

  6. Select Install Manually Downloaded Modules (.nbm Files) and click Next.

  7. Add the downloaded .nbm files and click Next.

  8. Select Web Server and click Next.

  9. Select the Include option and click Yes to install the plug-in.

    The Web Server 7.0 plug-in is installed in the IDE.

Procedure To Register Web Server 7.0 in the NetBeans IDE 5.5

  1. Start the NetBeans.

  2. Select Server node in the Runtime tab. Press mouse button and choose Add Server from the popup menu.

  3. Select the Web Server to register the Web Server and click Next.

  4. Provide the details of the Web Server installed on the local system or remote machine.

    Note –

    The plug-in requires a local Web Server installation on the same machine, even if you are registering a remote Web server. The local installation is required for some of the Web Server jar files.

  5. (Optional) If the Web Server contains multiple configuration, select the configuration.

    • Select the Web Server node form the IDE drop-down list.

    • Choose the configuration to use.

    Note –

    The drop-down list contains configuration which have at least one virtual server and one instance.

  6. Once the server is registered, it is listed in the Server node of the Runtime tab. Right click and choose Start.

  7. You can expand the nodes and see all the web applications and resources.

Procedure Deploying Web Applications

  1. Start the NetBeans.

  2. Select New Project from the File menu.

  3. Select Web in the category list, and in the projects list, select web application. Then click Next.

  4. From the Server drop-down list, select Web Server.

  5. Click Next to complete the web project creation.

    Once the project is created, web project is displayed in the Projects tab. You can find all basic files created in the Web Server specific sun-web.xml deployment descriptor .

    The web application is now ready to compile, deploy.

Creating Web Deployment Descriptors

Web Server web applications include two deployment descriptor files:

The easiest way to create the web.xml and sun-web.xml files is to deploy a web application using Sun Java Studio Enterprise 8.1. For sample web.xml and sun-web.xml files, see Sample Web Application XML Files

Deploying Web Applications

You can deploy a web application using either the Admin console or the command-line interface.

Procedure To Deploy Using Admin Console

Before You Begin

Select the virtual server, in which you need to deploy the web application.

  1. Access the Admin Console.

  2. Click the Add Web Application tab in the home page.

    The Add Web Application screen appears.

  3. Specify the location or package file path to upload to the Web Server.

  4. Type the URI for your web application.

    Specify the URI. This URI is the application's context root and is relative to the server host.

  5. Select JSP pre-compilation.

  6. Click OK.

    The Web Application page appears.

  7. Click Save.

  8. Click the Deployment Pending link in the top right of the screen.

    The Configuration Deployment screen displays.

  9. Click Deploy.

    The web application is deployed.

    For more information about using the Administration Console, see the Sun Java System Web Server 7.0 Update 7 Administrator’s Guide

Deploying Using wadm

Note –

Before you can manually deploy a web application, make sure that the server_root/bin directory is in your path.

You can use the wadm utility at the command line to deploy a WAR file into a virtual server web application environment as follows:

wadm [--user=admin-user] [--password-file=admin-pswd-file][--host=admin-host][--port=admin-port][--no-ssl][--rcfile=rcfile][--no-prompt][--commands-file=]filename

For more information about how to add, enable, and disable web applications, see the add-webapp(1).

The following table describes the command parameters. The left column lists the parameter, and the right column describes the parameter.

Table 9–1 Command Parameters




Specify the user name of the authorized Web Server administrator. 


Specify the password file. The password file contains the password to authenticate administrators to the administration server. This file must contain the line wadm_password=password. If you do not specify this option, you will be prompted for a password while executing this command.


Specify the name of the machine where the administration server is running. The default host is localhost.


Specify the port number of the administration server. The default non-SSL port is 8800 and the default SSL port is 8989. 


Specify this option to use a plain text connection to communicate with the administration server. The default connection is SSL. 


Specify the name of the rcfile that has to be loaded while starting the wadm utility. rcfile can contain environment commands like set and unset, or a JACL script that needs to be run while starting wadm. The default file is ~/.wadmrc


If you specify this option, wadm will prompt you for password while executing this command. Use this option if you have defined all passwords in a password file and specified the file using the --password-file option.

When you execute the wadm command, two things happen:

The following shows a sample command.

wadm add-webapp --user=admin --password-file=admin.pwd --host=serverhost --port=8989 --config=config1 --vs=config1_vs_1 --uri=/testapp /abc/sample.war

After you have deployed an application, you can access it from a browser as follows:


The following table describes the parts of the URL. )

Table 9–2 Parts of the URL




One of the urlhosts values for the virtual server.


(Optional) Only needed if the virtual server uses a non default port. 


The same path you used to deploy the application. This is also the context path. 


(Optional) The page in the application that end users are meant to access first. 

The following two examples show sample URLs:

Deploying Using JSR 88

JSR 88 defines the contracts that enable the tool of multiple providers to configure and deploy applications on any platform product. The implementation requires both tools and Java EE platform products.

You can write your own JSR 88 client to deploy an application to the Web Server. For more information about JSR 88, see

Auto-Deploying Web Applications

Using auto-deployment, you can quickly deploy one or more web applications just by copying them to a designated directory. The server auto-deploys web applications that are in the form of web archives (.war files) or in a directory in which a web archive has been exploded.

The following table illustrates the correlation between the name of the web archive or directory and the context path at which the application is automatically deployed.

Web Application 


Context Path 


Web Archive 






Web Archive 


Auto-deployment does not require the administration server to be up and running. Web applications that are auto-deployed are accessible on all the active virtual servers that have been configured in the server. Auto-deployment is intended for use in a development environment.

Note –

During startup, the web applications for server.xml are deployed before any of the web applications in the auto-deploy directory.

ProcedureAuto-Deploying a Web Application

  1. Copy the web application (.war file or directory) to the following directory:


    where, instance_dir is the path to the installation directory of this server instance.

  2. Start the instance. If the instance is already running, type the reconfig command:


    All web applications in the instance_dir/auto-deploy directory are automatically deployed to all the virtual servers in the instance.

ProcedureRemoving an Auto-Deployed Web Application

  1. Delete the corresponding .war file or sub-directory in the directory:


  2. Start the instance. If the instance is already running, type the reconfig command:


    The deleted web applications are no longer accessible.

    You can also configure the server to periodically check the instance_dir/auto-deploy directory, for new or removed applications and automatically reflect these changes in the running instance. The dynamic-reload-interval attribute controls how often the server checks the auto-deploy directory for changes.

    For information on how to set the dynamic-reload-interval attribute through Admin console, see Dynamic Reloading of Web Applications. For information on how to set the dynamic-reload-interval attribute through CLI, see set-servlet-container-prop(1).

Managing Web Applications

Once deployed, the application or module exists in the central repository and can be referenced by a number of server instances. Initially, the server instances or clusters that you deployed as targets reference the application or module. To change the server instances and clusters that reference an application or module after it is deployed, change an application or modules targets using the Admin Console or change the application references using the wadm.

Because the application is stored in the central repository, adding or deleting targets adds or deletes the same version of an application on different targets. However, an application deployed to more than one target can be enabled on one target and disabled on another target. Therefore, even if an application is referenced by a target, it is not available to you unless it is enabled on that target. In Web Server you can enable or disable a web application either using the Admin Console or command-line interface.

ProcedureTo Enable or Disable a Deployed Web Application

  1. Access the Admin Console.

  2. Select the server instance and click the edit Virtual Server tab.

  3. Click the Web applications tab.

  4. In the Web Applications table, select the web application.

    • To enable the application, click Enable.

    • To disable the application, click Disable.

    Tip –

    Use the enable-webapp and disable-webapp commands to enable or disable the web application through the command-line interface. For more information, see the enable-webapp(1) and disable-webapp(1) man pages.

  5. Click Save.

Enabling Web Applications

Web Server allows you to enable or disable a web application. You can do so in either of the following ways, as discussed in this section:

Enabling and Disabling Using the Admin Console

To enable or disable a deployed web application using the Admin Console, perform the following steps:

ProcedureTo Remove a Deployed Web Application

  1. Access the Admin Console.

  2. Select the server instance and click the edit Virtual Server tab.

  3. Click the Web applications tab.

  4. In the Web Applications table, select the web application or applications you want to remove and click Remove.

    Tip –

    To remove a deployed web application through the command-line interface, use the remove-webapp command. For more information, see the remove-webapp(1) man page.

  5. In the dialog box that appears, click OK.

Dynamic Reloading of Web Applications

To set dynamic reloading of web application, you must do the following:

ProcedureTo Set Dynamic Reloading of Web Application

  1. Access the Admin Console. Select the server instances and click the Edit Configuration tab.

  2. Click the Java tab.

  3. Click the Servlet Container tab.

  4. In the Dynamic Reload Interval field, type an integer, that specifies the interval (in seconds) after which a deployed application will be checked for modifications and reloaded if necessary.

    • To enable dynamic reloading, you must specify a value greater than 0.

    To disable dynamic reloading set the field to —1

  5. Click Save.

    Tip –

    To configure through the CLI, use the set-servlet-container-prop(1) command.

ProcedureTo Load a New Servlet or Reload a Deployment Descriptor

  1. Create an empty file named .reload at the root of the deployed module.

    For example:


    where vs_id is the virtual server ID in which the web application is deployed, and uri is the value of the uri attribute of the webapp/ element.

  2. Type touch .reload to explicitly update the .reload file's timestamp each time you make the above changes.

    For JSPs, changes are reloaded automatically at a frequency set in the reload-interval property of the jsp-config element in the sun-web.xml file. To disable dynamic reloading of JSPs, set the reload-interval property to -1.


Web Server classloaders help you determine where and how you can position supporting JAR and resource files of your modules and applications.

In a Java Virtual Machine (JVM), the classloaders dynamically load a specific Java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the classloaders loads the relevant class into the environment.

Classloaders in the Web Server runtime follow the hierarchy shown in the following figure.

Figure 9–1 Classloader Runtime Hierarchy

Classloader Runtime Hierarchy

This hierarchy is a delegation hierarchy not a Java inheritance hierarchy. In the delegation design, a classloader delegates classloading to its parent before attempting to load a class itself. If the parent classloader cannot load a class, the findClass()method is called on the classloader subclass. In effect, a classloader is responsible for loading only the classes not available to the parent.

The exception is the web application classloader, which follows the delegation model in the Servlet specification. The web application Classloader looks in the local classloader before delegating to its parent. You can make the web application Classloader delegate to its parent first by setting delegate="true" in the class-loader element of the sun-web.xml file. For more information, see Classloader Element.

The following table describes Web Server classloaders.

Table 9–3 Web Server Classloaders




The Bootstrap Classloader loads the JDK classes. Only one instance of this classloader exists in the entire server. 


The System Classloader loads the core Web Server classes. It is created based on the class-path-prefix, server-class-path, and class-path-suffix attributes of the <jvm/> element in the server.xml file.

The environment classpath is included if env-classpath-ignored="false" is set in the <jvm/> element. Only one instance of this classloader exists in the entire server.

If any changes are made to these attributes or classes, the server must be restarted for the changes to take effect.  

For more information about the <jvm/> element in server.xml, see the Sun Java System Web Server 7.0 Update 7 Administrator’s Configuration File Reference.


The Common Classloader loads classes in the instance_dir/lib/classes directory, followed by JAR and ZIP files in the instance_dir/lib directory. The directories are optional. If they don't exist, the Common Classloader is not created. If any changes are made to these classes, restart the server.

Web Application

The Web Application Classloader loads the servlets and other classes in a specific web application from WEB-INF/lib and WEB-INF/classes and from any additional classpaths specified in the extra-class-path attribute of the class-loader element in sun-web.xml. For more information, see Classloader Element.

An instance of this classloader is created for each web application. If dynamic reloading has been enabled, any changes made to these attributes or classes are reloaded by the server without the need for a restart. For more information, see Dynamic Reloading of Web Applications


The JSP Classloader loads the compiled JSP classes of JSPs. An instance of this classloader is created for each JSP file. Any changes made to a JSP are automatically detected and reloaded by the server unless dynamic reloading of JSPs has been disabled by setting the reload-interval property to -1 in the jsp-config element of the sun-web.xml file. For more information, see jsp-config Element.