Deployment

Background

Before describing how to organize your source code directories, it is useful to examine the runtime organization of a web application. Prior to the Servlet API Specification, version 2.2, there was little consistency between server platforms. However, servers that conform to the 2.2 (or later) specification are required to accept a Web Application Archive in a standard format, which is discussed further below.

A web application is defined as a hierarchy of directories and files in a standard layout. Such a hierarchy can be accessed in its "unpacked" form, where each directory and file exists in the filesystem separately, or in a "packed" form known as a Web ARchive, or WAR file. The former format is more useful during development, while the latter is used when you distribute your application to be installed.

The top-level directory of your web application hierarchy is also the document root of your application. Here, you will place the HTML files and JSP pages that comprise your application's user interface. When the system administrator deploys your application into a particular server, he or she assigns a context path to your application (a later section of this manual describes deployment on JBossWeb). Thus, if the system administrator assigns your application to the context path /catalog, then a request URI referring to /catalog/index.html will retrieve the index.html file from your document root.

Standard Directory Layout

To facilitate creation of a Web Application Archive file in the required format, it is convenient to arrange the "executable" files of your web application (that is, the files that JBossWeb actually uses when executing your app) in the same organization as required by the WAR format itself. To do this, you will end up with the following contents in your application's "document root" directory:

• *.html, *.jsp, etc. - The HTML and JSP pages, along with other files that must be visible to the client browser (such as JavaScript, stylesheet files, and images) for your application. In larger applications you may choose to divide these files into a subdirectory hierarchy, but for smaller apps, it is generally much simpler to maintain only a single directory for these files.
  
  
• /WEB-INF/web.xml - The Web Application Deployment Descriptor for your application. This is an XML file describing the servlets and other components that make up your application, along with any initialization parameters and container-managed security constraints that you want the server to enforce for you. This file is discussed in more detail in the following subsection.
  
  
• /WEB-INF/jboss-web.xml - The JBoss Web Application Deployment Descriptor for your application. This is an XML file describing the JBossWeb extensions to /WEB-INF/web.xml. See jboss-web.xml for more.
  
  
• /WEB-INF/classes/ - This directory contains any Java class files (and associated resources) required for your application, including both servlet and non-servlet classes, that are not combined into JAR files. If your classes are organized into Java packages, you must reflect this in the directory hierarchy under /WEB-INF/classes/. For example, a Java class named com.mycompany.mypackage.MyServlet would need to be stored in a file named /WEB-INF/classes/com/mycompany/mypackage/MyServlet.class.
  
  
• /WEB-INF/lib/ - This directory contains JAR files that contain Java class files (and associated resources) required for your application, such as third party class libraries or JDBC drivers.

When you install an application into Tomcat (or any other 2.2/2.3-compatible server), the classes in the WEB-INF/classes/ directory, as well as all classes in JAR files found in the WEB-INF/lib/ directory, are made visible to other classes within your particular web application. Thus, if you include all of the required library classes in one of these places (be sure to check licenses for redistribution rights for any third party libraries you utilize), you will simplify the installation of your web application -- no adjustment to the system class path (or installation of global library files in your server) will be necessary.

Much of this information was extracted from Chapter 9 of the Servlet API Specification, version 2.3, which you should consult for more details.

Shared Library Files

If you want to share libraries between webapps put them in a ear file with the libraries you want to share.

Out of the box, a standard JBossWeb installation includes a variety of pre-installed shared library files, including:

• The Servlet 3.0 and JSP 2.2 APIs that are fundamental to writing servlets and JavaServer Pages.
  
  
• An XML Parser compliant with the JAXP (version 1.2) APIs, so your application can perform DOM-based or SAX-based processing of XML documents.
  
  

Web Application Deployment Descriptor

As mentioned above, the /WEB-INF/web.xml file contains the Web Application Deployment Descriptor for your application. As the filename extension implies, this file is an XML document, and defines everything about your application that a server needs to know (except the context path, which is assigned by the system administrator when the application is deployed).

The complete syntax and semantics for the deployment descriptor is defined in Chapter 13 of the Servlet API Specification, version 3.0. Over time, it is expected that development tools will be provided that create and edit the deployment descriptor for you. In the meantime, to provide a starting point, a basic web.xml file is provided. This file includes comments that describe the purpose of each included element.

NOTE - The Servlet Specification includes a Document Type Descriptor (DTD) for the web application deployment descriptor, and JBossWeb enforces the rules defined here when processing your application's /WEB-INF/web.xml file. In particular, you must enter your descriptor elements (such as <filter>, <servlet>, and <servlet-mapping> in the order defined by the DTD (see Section 13.3).

JBoss Web Application Deployment

A /WEB-INF/jboss-web.xml file can be used to define JBossWeb specific configuration options, such as loggers, data sources, session manager configuration and more. This XML file is describe in jboss-web.xml.

Deployment With JBossWeb

In order to be executed, a web application must be deployed on a servlet container. This is true even during development. We will describe using Tomcat 5 to provide the execution environment. A web application can be deployed in JBossWeb by one of the following approaches:

• Copy unpacked directory hierarchy into a subdirectory in directory ${jboss.server.base.dir}/standalone/deployments/. JBossWeb will assign a context path to your application based on the subdirectory name you choose. We will use this technique in the build.xml file that we construct, because it is the quickest and easiest approach during development. you have to create a file named like myapp.war.dodeploy to start the deployement scanner on the myapp.war directory.
  
  
• Copy the web application archive file into directory ${jboss.server.base.dir}/standalone/deployments/. When JBossWeb is started, it will automatically expand the web application archive file into its unpacked form, and execute the application that way. This approach would typically be used to install an additional application, provided by a third party vendor or by your internal development staff, into an existing JBossWeb installation. The web-app will be automaticaly deployed.
  
  
• Use the command line or the Web Management Interface of AS7. web applications. For example something like:

  [standalone@localhost:9999 /] deploy /home/jfclere/jbossweb_sandbox/webapps/myapp.war
  'myapp.war' deployed successfully.
  

  In the above example myapp.war will be deployed under the context /myapp
  
  

Deploying your app on other servlet containers will be specific to each container, but all containers compatible with the Servlet API Specification (version 2.2 or later) are required to accept a web application archive file. Note that other containers are NOT required to accept an unpacked directory structure (as Tomcat does), or to provide mechanisms for shared library files, but these features are commonly available.