Packaging and Deployment

As a J2EE-compliant web container, WebLogic Server can host a number of web applications. Each web application is a logical collection of servlets, JSPs, client-side applets, and static web resources such as HTML pages, images, multimedia documents, etc. In addition, a web application may use filters, JSP tag libraries, utility Java classes, and JavaBean components. Each web application is executed in its own runtime environment provided by the web containera handle to this environment is provided by ServletContext. We refer to JSPs and servlets as web components. These web components also have access to external resources and WebLogic enterprise services such as deployed EJB components, JDBC data sources, JMS destinations, XML parser factories, and much more through access to ServletContext.

2.1.1 Structure of a Web Application

A web application is structured as a hierarchy of directories the root directory serves as the document root for all resources in the web application. These directories contain all the JSPs, servlets, and other, static resources such as images that are referenced by the application. A special directory named WEB-INF holds all resources that aren't part of the public document tree of the application. So, a web client will not have direct access to any file stored under the WEB-INF directory, which is quite useful for protecting from clients specific resources in the web application. However, the contents of the WEB-INF directory are exposed to the server side. Both the methods getResource() and getResourceAsStream( ) of the ServletContext object and the forward( ) and include( ) methods of the RequestDispatcher object can access the contents of the WEB-INF folder.

The WEB-INF folder also includes the following files:

• A web.xml deployment descriptor, which is the standard J2EE XML document that describes the contents of the web application
• A weblogic.xml deployment descriptor, which contains the WebLogic-specific deployment information about the web application
• A classes subdirectory, which is the base directory for all compiled servlets, filters, precompiled JSPs, implementation classes for custom JSP tags, and utility classes
• A lib folder, which is the location for all JAR files that may be useful to the web application, including custom JSP tag libraries

Example 2-1 lists the contents of a typical web application.

Example 2-1. Directory layout for a simple web application

/index.html
/home.jsp
/error.jsp
/demos/products.swf
/images/banner.jpg
/WEB-INF/web.xml
/WEB-INF/weblogic.xml
/WEB-INF/classes/com/oreilly/bar/MyServlet.class
/WEB-INF/classes/com/oreilly/bar/MyFilter.class
/WEB-INF/classes/com/oreilly/bar/MyTagImpl.class
/WEB-INF/lib/mylibs.jar

2.1.2 Assembling a WAR

A web archive (WAR) can be created very simply by placing the contents of the WAR in a staging directory for instance, wardir and then using the jar tool that comes with your JDK to create the archive:

jar cvf mywar.war -C wardir

Alternatively, you can use a standard Ant task:

This has an advantage over the jar command because the different components of the WAR are not required to be in any particular fixed directory structure before creation. The war task can be part of an Ant script, which is used to build and deploy the web application.

Chapter 19 shows how you can use WebLogic's tools to package web service components within a WAR file.

2.1.3 XML Deployment Descriptors

A web application needs a standard J2EE web.xml descriptor and an optional WebLogic-specific weblogic.xml descriptor before it is ready for deployment. You can use these XML documents to define the web components and set up the operating environment for the web application. The web.xml descriptor is defined in the Servlet specification. It can be used to specify application-specific initialization parameters, servlets, filters and event listeners, MIME types, sessions tag libraries, security, and references to external resources.

Some web applications may require a weblogic.xml descriptor, which defines deployment properties specific to the runtime environment in WebLogic Server. In WebLogic Server 8.1, the weblogic.xml descriptor must be a valid XML document conforming to the DTD, published at http://www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd. You can use this deployment descriptor to specify:

• HTTP session parameters (for the session tracking cookie, session persistence, and URL rewriting).
• JSP parameters (compilation settings for WebLogic's JSP compiler).
• Container attributes (configure whether you require reauthentication for forwarded requests and whether redirects use absolute or relative URLs).
• Character-set mappings and parameters.
• JNDI names for references to external resources defined in the web.xml descriptor file (including EJBs, data sources, security realms, etc.).
• Custom classes for URL pattern matching.
• Security role assignments to one or more principals in the realm.
• Virtual directories for mapping other document roots for a specific set of requests. For example, images for a web application may be stored in a separate location and need not be under the document root for the web application. If one or more virtual directories have been mapped, WebLogic Server will inspect the virtual directories for the resource before looking at the document root for the web application.

All of these issues are covered in this chapter and in Chapter 3.

Chapter 12 provides a number of techniques that may be used to edit deployment descriptors of web applications.

2.1.4 WebLogic's JSP Compiler

WebLogic's internal JSP compiler translates JSP pages into servlet classes. By default, WebLogic automatically compiles JSPs without any user intervention. This compilation occurs when a JSP has been requested and the servlet class file has not yet been generated or the servlet class is older than the actual JSP page. This means that the compilation occurs automatically whenever a new JSP is invoked, or when the client has invoked a JSP that has been modified since the last time it was compiled. Therefore, you don't ever need to invoke the JSP compiler directly (although you may want to, as detailed in this section). Later, we shall see how you can register a JSP page as a servlet, and set it to load and initialize when the server starts up. In that case, the JSP compilation occurs during startup, even before a request is received from a client browser.

You also can configure WebLogic Server to precompile all JSP pages when a web application is deployed (or redeployed) or when the server starts up. To enable JSP precompilation, you need to set a JSP configuration parameter within the jsp-descriptor element in the weblogic.xml descriptor file:

 
 precompile 
 true
 

Alternatively, you may directly compile all JSPs, thereby avoiding the need for compilation while the server is running. This functionality is made available through the weblogic.appc compiler. The JSP compiler parses and translates the JSP files, generating Java source files, which it then compiles. The following command will validate the descriptors in the given WAR, compile the JSP files, and update the WAR with the resulting class files:

java weblogic.appc -keepgenerated -verbose myWebApp.war

You can also simply point it to a directory containing a web application:

java weblogic.appc -keepgenerated webappDirectory

Table 2-1 lists various options available to the JSP compiler.

Table 2-1. JSP compiler options

Option	Description	Default
-classpath	This option customizes the classpath used by the JSP compiler. On a Windows NT/2000 platform, the classpath must be a semi-colon-separated list of the names of directories, ZIP, and/or JAR files. On Unix platforms, the classpath must be a colon-separated list of names.	none
-compiler	This option specifies the compiler to be used for compiling .java files. It defaults to the first javac binary in your PATH environment variable.	javac
-output file	Usually the compiler updates the web archive, adding to its current contents. If you want to send the output to a different WAR, specify the filename here.	none
-forceGeneration	By default, the compiler compiles only those files that it thinks should be compiled, judging by timestamps. If you supply this option, it will recompile everything.	false
-g	This option instructs the compiler to include debugging information in the class file.	none
-keepgenerated	This instructs the compiler to not delete the intermediate .java source file once the JSP file has successfully compiled. In the absence of JSP debugging tools, this flag is extremely useful for tracking down bugs in your JSP code.	none
-O	This tells the compiler to compile generated .java files with the optimization flag on (overrides -g flag).	none
-verbose	This option determines whether the JSP compiler runs in a verbose mode.	false
-verboseJavac	This option passes the verbose flag to the Java compiler when compiling intermediate .java files.	false

You also can define JSP compiler settings for the web application in the WebLogic-specific weblogic.xml deployment descriptor, as detailed in the following section.

2.1.5 Deploying a Web Application

A web application can be packaged in two ways before it is ready for deployment:

Exploded directory format

Here the contents of the web application are placed in a folder. This is recommended during the development stages, when you must directly modify the resources within the web application, without the need for repackaging.

Archived format

Alternatively, you can create a WAR, where the contents of the web application are bundled into a JAR file with a .war extension. This approach is recommended for a production environment.

Thus, you have the flexibility of deploying your web application in exploded format, if it is undergoing constant changes during development stages. Otherwise, you may package the contents within a standard WAR file, and then simply deploy the web application in a production environment. In fact, WebLogic provides two modes of operation that impact how you deploy your web applications:

Development mode

Enable this mode during the development stages, when your web application is under construction and the team members are concurrently making changes to its contents. Its key benefit is the ease with which you can directly modify the resources within the web application, and then instantly see the results of the changes without having to redeploy the entire web application.

Production mode

Use the production mode when you need to make infrequent changes to your web applications. Typically, you will package the web application in archived format when deploying it to a server running in this mode. So, if you update any Java class files or modify any of the deployment descriptors, you must redeploy the entire WAR. Unfortunately, redeploying a web application means WebLogic loses all active HTTP sessions associated with that web application. If the web application is targeted to other Managed Servers, your network must also endure a surge in traffic while all changes are propagated to all the servers.

On top of this, you can decide whether a web application will be deployed as a standalone application or as a J2EE module within an enterprise application, alongside other web applications, EJB components, resource adapters, and library JARs. Refer to Chapter 12 for more information on how to package enterprise applications and later introduce them to a WebLogic environment. Chapter 12 also introduces WebLogic's split directory development structure, which can be used as an alternative to deploying web applications during development.

The applications folder under the domain's root directory provides a convenient store for standalone applications that are deployed to WebLogic. In the development mode, you can deploy a web application to WebLogic simply by placing the WAR file (or a directory, if it exists in an exploded format) under the domain's applications directory. WebLogic also supports an auto-deploy feature in the development mode, which greatly eases the task of updating your web applications:

• If your web application is packaged as a WAR file, you can redeploy the web application simply by modifying the WAR file (or replacing it with a new copy).
• If your web application exists in the exploded form, any changes you make to resources within the web application are automatically reflected without having to redeploy it. Any changes to static files (such as HTML pages, images, etc.) and JSP pages are automatically picked up by WebLogic.
• You can refresh compiled Java classes used by the web application. This means that you can hot-deploy changes to servlets, filters, JSP tag implementations, and classes located under the WEB-INF/classes folder without the need for redeployment.

Another neat little trick WebLogic provides is its ability to redeploy the web application whenever you touch a REDEPLOY file in the WEB-INF directory. All of these features are supported by default in the development mode. The value of the command-line parameter weblogic.ProductionModeEnabled determines whether WebLogic operates in the development mode. The following command shows how to start a server in the production mode:

java -classpath %CLASSPATH% -Dweblogic.Name=myserver -Dbea.home=%BEA_HOME% 
 -Dweblogic.management.username=%WL_USER% -Dweblogic.management.password=%WL_PW% 
 -Djava.security.policy=... -Dweblogic.security.SSL.trustedCAKeyStore=... 
 -Dweblogic.ProductionModeEnabled=true ...
weblogic.Server

Chapter 12 looks at how to use the Administration Console or WebLogic's Deployer tool to manage deployed applications in a WebLogic environment.

2.1.6 Class Loaders

WebLogic Server provides a separate class loader for each web application deployed as part of an EAR. This class loader ensures that all servlets and classes in a web application are loaded within the same scope. This eliminates the possibility of classes loaded from the web application conflicting with WebLogic Server implementation classes. For instance, even though WebLogic needs XML parsers to process deployment descriptors, a web application can still load parsers supporting different SAX or DOM versions, without conflicting with the server's copy. So, separating the scope of classes in a web application from the server's bootstrap classes resolves this issue quite elegantly.

WebLogic provides an option for changing the default class-loading mechanism for a web application. This option, called Prefer Web-Inf Classes, can be set by modifying the weblogic.xml descriptor file:

 true

In WebLogic 7.0, this option is available in the Configuration/Other tab of a web application. The default mechanism in most class-loading hierarchies is that if a child class loader is asked for a class, and it doesn't have it in memory, it asks its parent to load the class. Only if the parents fail does the child load the class. So, if we have a servlet in a web application that requires a class that has not been loaded by the web application class loader, the web application should pass the request on to its parent class loader. By setting the prefer-web-inf-classes element to true, WebLogic changes the class-loading logic to allow the web application class loader to immediately try and load the class, without first asking the parent. This rather delicate setting could be used in esoteric cases where you want the web application class files to take priority over parent class loaders, perhaps the EAR class loader, because of possible class implementation differences.

A second issue related to class loading is that the J2EE standard specifies that any class loader for a web application is required to load classes from the classes folder before loading any classes from the JARs in the lib folder. For instance, if a class exists both in the classes folder and in JARs in the lib folder, WebLogic Server will always load the class from the classes folder.

Usually, the contents of the /WEB-INF/classes folder won't conflict with the JARs located under the /WEB-INF/lib folder. The classes folder will typically contain the servlet and utility classes, whereas the lib folder will contain other supporting library JARs needed by the web application, including tag library JARs.

The Class-Path entry in the manifest file META-INF/MANIFEST.MF for a WAR also can be used to reference any supporting JARs. This manifest entry for extending the CLASSPATH to include other WAR dependencies must follow the standard JAR manifest format. You can find more information on the standard extension mechanism for JAR files at http://java.sun.com/j2se/1.4/docs/guide/extensions/spec.html. Chapter 12 provides an extensive overview of WebLogic's classloader hierarchy.