Packaging Web Applications | Mastering BEA WebLogic Server: Best Practices for Building and Deploying J2EE Applications

You package Web applications for deployment in WebLogic Server by creating the correct Web application directory structure and placing in that structure the view components , images, class libraries, and descriptor files required for the application. In this section, we will briefly review the structure of a standard J2EE Web application, examine key elements in the web.xml and weblogic.xml descriptor files, and present a build process for creating Web applications using the Ant utility.

Web Application Directory Structure

The standard Web application directory structure, depicted in Figure 5.2, defines the proper location for all of the components required for the application. Viewable components, such as JSP pages, static HTML pages, images, and other content intended for viewing by client browsers, are placed directly below the root directory in the structure. Internal files, such as Java classes, libraries, and descriptors, are placed in the WEB-INF directory.

Figure 5.2: Standard Web application directory structure.

The viewable components can be placed directly in the root directory of the Web application or in subdirectories below the root directory to improve the overall organization of the site. It is very common, for example, to have supporting content such as images, style sheets, or JavaScript functions located in separate directories, as shown in Figure 5.3.

Figure 5.3: Place supporting files in separate directories.

HTML and JSP files can also be placed in separate directories to improve organization, as shown in Figure 5.4.

Figure 5.4: Use directories to organize the application.

Hyperlinks and directives, such as jsp:include , in the view pages must reflect any directory structure present in the Web application, so it is important to make these organizational decisions early in the development process. Recognize that a good hierarchical organization allows the use of directories in the url-pattern descriptor elements to better configure security, servlet mapping, filter mapping, and other features.

When organizing your Web applications, be aware of the important difference between separate directories in a Web application and separate Web applications:

Separate directories in the same Web application represent a purely organizational structure. Components in all directories of a Web application share the same HttpSession data, classloader, application-scoped variables , authentication information, servlet and JSP configuration, and all parameters defined at the Web application level in the web.xml or weblogic.xml descriptors.
Separate Web applications may look similar to separate directories from the point of view of the user , differing only by the context path in the URL (for example, /user/main.jsp versus /admin/main.jsp ). In the application server, however, separate Web applications are treated much differently than separate directories in the same Web application. Each Web application will use a different classloader, have its own set of descriptor files and application-scoped variables, and store separate HttpSession data for the user. The only information shared by both Web applications, essentially , is authentication information. Even this can be scoped to each Web application separately, if desired, creating completely independent applications.

Use separate directories in a single Web application when the directories represent different areas of the same site and you need a single HttpSession preserved across the directories. Use separate Web applications when there is a strong need to isolate the sections of the overall application from each other and there is no need to share HttpSession information.

Best Practice

Use separate directories in a single Web application to share context and session information. Choose separate Web applications to provide the maximum isolation between the sections of the overall application.

The bigrez.com application uses two separate Web applications, user and admin , rather than a single Web application with separate directory structures. We made this choice because the two sites are intended for completely different sets of users and have different security and auditing rules, and because there is no requirement to share HttpSession data across the two sites.

Internal Components

The WEB-INF directory contains all of the internal components, including configuration and supporting files for the application. Files located in WEB-INF are not accessible directly by the client browser.

As described in Chapter 1, any Java class files or resource files located in the WEB-INF/classes directory are loaded automatically by the Web application classloader and made available to all components in the Web application. In a similar manner, all Java archive ( .jar ) files placed in WEB-INF/lib are loaded automatically and made available to the Web application. Note that class files located in /classes are loaded before archives in /lib , an important distinction if individual classes are defined in both locations.

Note	Class files located in WEB-INF/classes are loaded before archives in WEB-INF/lib . If the same class is located in both places, the version in WEB-INF /classes will be used in the application.

The remaining files in WEB-INF are descriptor files used by the container to deploy and configure the Web application properly at run time. These files are discussed in the following section.

Web Application Descriptor Files

WebLogic uses two primary descriptor files to deploy the Web application properly: web.xml and weblogic.xml . See the online documentation available at http: // edocs .bea.com/wls/docs81/webapp/deployment.html for a complete listing of the elements and structure of these files. We ll examine the descriptor files in bigrez.com to help you understand key elements and best practices related to these files.

Standard web.xml Descriptor File

The web.xml descriptor file is defined by the J2EE specification and is used by WebLogic Server to control basic configuration and deployment of the application. Table 5.1 outlines the high-level sections of the web.xml file and lists the key elements used in each section.

Table 5.1: Sections of the web.xml Descriptor File
WEB.XML SECTION	PURPOSE AND KEY TOP-LEVEL XML ELEMENTS
Deployment attributes	Defines graphics and descriptions used by deployment and management tools. < icon > , < display- name > , < description > , < distributable >
Context parameters	Defines parameters and values placed in a Web application context, making them available in application components. < context-param >
Filter information and mapping	Provides deployment information, name, class, initialization parameters, and URL mappings for filters in the application. < filter > , < filter-mapping >
Application listeners	Defines listener classes used to intercept application events. < listener >
Servlet information and mapping	Provides deployment information, name, class, initialization parameters, security roles, and URL mappings for servlets in the application. < servlet > , < servlet-mapping >
Session configuration	Defines the time-out value for HttpSession information. < session-config >
MIME mapping	Defines MIME types for file extensions. < mime-mapping >
Welcome pages	Provides a list of default pages for unspecified page requests . < welcome-file-list >
Error pages	Defines the error page to be displayed in case of specific HTTP error code or Java exception. < error-page >
JSP tag libraries	Identifies and maps tag library definition ( .tld ) file to a specific URI name. < taglib >
Resource references	Defines an external resource available in the Web application. < resource-ref >
Security information	Defines the security authorizations required to access sets of Web pages, the technique used to authenticate a user, and security roles valid in the application. < security-constraint > , < loginconfig > , < security-role >
Environment entries	Defines a data value available in the environment. < env-entry >
EJB references	Defines EJB components available to Web application components using environment lookups. < ejb-ref > , < ejb-local-ref >

The bigrez.com application consists of two separate Web applications, user and admin . Each application has a web.xml descriptor file containing the elements required for proper operation of the Web components in the application. Please download these files from http://www. wiley .com/compbooks/masteringweblogic and examine them before proceeding.

We ll now walk through the web.xml file for the administration site and highlight some sections worth noting in that file. We won t examine the web.xml file for the user site because it contains a subset of the elements in the administration version.

The first section in web.xml defines a filter used to log all activity on the administration site:

 <!-- define auditing filter to log all admin activity --> <filter>   <filter-name>AuditFilter</filter-name>   <display-name>AuditFilter</display-name>   <description></description>   <filter-class>com.bigrez.ui.admin.AuditFilter</filter-class> </filter> <filter-mapping>   <filter-name>AuditFilter</filter-name>   <url-pattern>/Master.jsp</url-pattern> </filter-mapping> <filter-mapping>   <filter-name>AuditFilter</filter-name>   <url-pattern>*.do</url-pattern> </filter-mapping>

The AuditFilter is invoked for all requests matching the URL patterns /Master.jsp or *.do . The pattern Master.jsp is used rather than *.jsp to avoid invoking the filter for all JSP pages included using jsp:include directives. The doFilter method in the AuditFilter class simply logs the request and its parameters to the standard logging facility and invokes the next filter, if any, in the chain:

 public void doFilter(ServletRequest request,                      ServletResponse response, FilterChain chain)     throws IOException, ServletException {     HttpServletRequest req = (HttpServletRequest)request;     StringBuffer auditentry = new StringBuffer();     auditentry.append(req.getRemoteAddr() +   + req.getRemoteUser() +                         + req.getRequestURI());     Enumeration e = req.getParameterNames();     if (e.hasMoreElements()) {         while (e.hasMoreElements()) {             String name = (String)e.nextElement();             auditentry.append(+ name + = +                                req.getParameter(name));         }     }     LOG.info(auditentry.toString());     // continue processing any other filters     chain.doFilter(request, response); }

The next section of the administration web.xml file defines the three servlets active in the application and provides the required startup and mapping information:

ActionServlet is the standard controller servlet used by Struts to process HTML form submissions and other actions. We ve mapped this servlet to the URL pattern *.do , provided the location of the file containing application resources, provided the location of the struts-config.xml file, and configured the servlet to load during startup in order to preload the configuration information.
PageDisplayServlet was discussed in detail in Chapter 3 as our solution for page assembly. This servlet is mapped to the URL pattern *.page to implement the assembly technique described in that discussion.
InitializationServlet is used as a startup class to preload selected information in to the Web application context for use in drop-down lists in the display pages. Note that the servlet is not mapped to any URL patterns, so it will never be accessed from a client HTTP request.

We ve used a servlet as an initialization or startup class rather than defining a server-level StartupClass object for a number of reasons:

A server-level startup class must be defined in the system classpath for the class to be available during server startup. Application classes should generally not be loaded in the system classpath because this practice inhibits redeployment of the application and is the root cause of many NoClassDefFoundError exceptions.
A class located in the system classpath can use only classes that are available in that classloader. This restriction often necessitates moving additional classes to the system classpath, which in turn use other classes that must also be promoted to the system classpath, a vicious cycle that is difficult to break.
Classes present in the system classpath cannot be deployed automatically by WebLogic Server to managed servers in the domain (Chapter 11 discusses these concepts). The classes must be manually copied to each server in the domain and made available in the system classpath during server startup.

Servlets are a much better alternative for startup classes because they avoid the system classpath issues completely, have visibility to all classes defined or available in the Web application, and are reinitialized whenever their hosting Web application is redeployed. The Web application containing the initialization servlet may also be configured to always deploy after any EJB components in the same overall application, thereby allowing the initialization servlet to access the EJB components reliably. Use the Deployment Order attribute associated with each application component to control the order of deployment in a combined EJB and Web application.

Best Practice

Use servlets as startup or initialization classes rather than defining server-level StartupClass classes. Servlet-based initialization classes reload when the Web application is redeployed and avoid the problems associated with classes located in the system classpath.

In the next section of web.xml we define the default welcome page, Home.page , and the error page to display when an HTTP 500 error code falls out of a servlet or JSP invocation:

 <welcome-file-list>   <welcome-file>Home.page</welcome-file> </welcome-file-list> <error-page>   <error-code>500</error-code>   <location>/Master.jsp?page=ErrorPage.jsp</location> </error-page>

Note that although the welcome page definition can use the .page syntax, the error page must invoke the Master.jsp directly to avoid losing the error information in the HTTP request.

The next section declares the existence of specific JSP tag libraries and indicates the location of each tag library descriptor ( .tld ) file in the WEB-INF directory. The format of these tag library descriptor files is beyond the scope of this discussion. Consistent with our best practices from Chapter 1, we are using libraries supplied by other sources, and we have not created any custom tag libraries of our own, so these files are simply copies of the .tld files supplied with the Struts framework.

The administration site employs standard J2EE security to control access to pages in the application, and the next few sections of web.xml contain the elements necessary to enable and configure this security. These elements, security-constraint , login-config , and security-role , are explained in detail in Chapter 4 and will not be discussed here. The login page, Login.jsp , is also listed and described in Chapter 4.

That s all there is to the administration site web.xml file.

Locating EJB Components

Home interfaces for EJB components are looked up by the application using an InitialContext object and a string representing either the global JNDI name or the reference name given to the component in the JNDI Environment Naming Context (ENC). Avoid hard-coding global JNDI names in the application code because this ties the code directly to the deployment details and limits the flexibility to change JNDI names . Instead, use lookups similar to the following:

 Context jndiContext = new InitialContext(); Object obj = jndiContext.lookup(java:comp/env/ejb/RateHomeLocal);

The java:comp/env/ejb/... ENC syntax requires a mapping element in the web.xml file to map this reference name to an actual bean in the application. An element similar to the following is therefore required for each EJB component referenced using the ENC syntax:

 <ejb-local-ref>   <ejb-ref-name>ejb/RateHomeLocal</ejb-ref-name>   <ejb-ref-type>Entity</ejb-ref-type>   <local-home>com.bigrez.ejb.RateHomeLocal</local-home>   <local>com.bigrez.ejb.RateLocal</local>   <ejb-link>RateEJB</ejb-link> </ejb-local-ref>

The mapping may be accomplished using ejb-link elements in web.xml , as shown here, or may use reference-descriptor elements in weblogic.xml to map the reference names to global JNDI names. We recommend the easier and more portable ejb-link elements.

Best Practice

Use the java:comp/env/ejb/... ENC syntax to look up EJB home interfaces to eliminate strong coupling between application code and JNDI names. Map the reference names to deployed beans using ejb-link elements in the web.xml descriptor file.

The bigrez.com application uses a Locator utility class to acquire and cache references to EJB home interfaces in Web application components and business- tier code. Many examples in the previous chapter looked similar to this:

 RateHomeLocal ratehome =      (RateHomeLocal)  Locator.getHome("RateHomeLocal");

The Locator class is very useful in the application code because it abstracts the process for retrieving and caching home interfaces and provides a simple syntax requiring no knowledge of the EJB deployment. The Locator class looks for the specified home interface in two ways:

It prepends java:comp/env/ejb/ to the supplied name and searches in the JNDI ENC for the desired home interface.
It searches for the supplied name as a global JNDI name.

As a Web application deployer, you therefore have a choice: allow the Locator class to find EJB home interfaces using the JNDI names directly or include ejb-ref and ejb-local-ref descriptor elements in the web.xml descriptor file to make home interfaces available using the java:comp/env/ejb/... syntax. The application code does not change based on your decision; it is simply a matter of deployment preference.

The web.xml files for bigrez.com do not include ejb-local-ref elements for EJB components, so Locator lookups will rely on global JNDI names by default. The two-step nature of the Locator utility gives us the flexibility to add selected ejb-local-ref elements in the future if there is a need to map the original name to a different bean, but there is no need to precreate all of these elements initially. A performance penalty is associated with this two-step process, naturally. The JNDI lookup throws an exception if the first search, using the java:comp/env/ejb/... syntax, fails to find the home interface, and the lookup must then be repeated using the global JNDI name. Repeating this two-step process for every request would have serious repercussions on performance. Caching of home interfaces in the Locator class eliminates this inefficiency on all subsequent requests for the same home interface.

The bottom line is that application code should not be aware of the referencing technique used to map names to EJB home interfaces. It is generally best to use the java :comp/env/ejb/... syntax in your home lookup code and create the necessary mapping elements in web.xml , as described in the best practice. Using a Locator class that tries to find the home interface multiple ways is also a reasonable solution.

weblogic.xml Descriptor File

The weblogic.xml descriptor file is a WebLogic Server-specific file used to control WebLogic Server-specific features and provide extensions to the basic configuration and deployment features in web.xml . Table 5.2 outlines the high-level sections of the weblogic.xml file and lists the key elements used in each section. See the online documentation at http: // edocs.bea.com/wls/docs81/webapp/deployment.html for a complete listing.

Table 5.2: Sections of the weblogic.xml Descriptor File
WEBLOGIC.XML SECTION	PURPOSE AND KEY TOP-LEVEL XML ELEMENTS
Deployment attributes	Defines information used by deployment and management tools. < description > , < weblogic-version >
Context root information	Defines the context root for the Web application. Used when the Web application is not deployed in an enterprise application ( .ear ) file. < context-root >
Security role/principal mapping	Assigns specific principals in the security realm to a role defined in the web.xml descriptor, supplementing any realm assignments. < security-role-assignment >
Resource references	Provides the physical location (JNDI name) of resources and EJB components declared in the web.xml file using resource-ref, ejb-ref , and ejb-local-ref elements. < reference-descriptor >
Directory mapping information	Defines alternate locations for files matching specific URL patterns. < virtual-directory-mapping >
URL matching class	Defines the class used to map URLs to servlets with additional path information. < url-match-map >
Session configuration	Defines detailed HttpSession configuration parameters such as persistence technique, cookie name, and so on. < session-descriptor >
JSP configuration	Defines configuration parameters for JSP generation and compilation. < jsp-descriptor >
Container configuration	Defines miscellaneous parameters controlling container behavior for forwards and HTTP redirects. < container-descriptor >
Character set parameters	Defines character set mappings for incoming request data. < charset-params >

The weblogic.xml descriptors for both sites in bigrez.com require only a handful of elements to configure their respective Web applications properly. Listing 5.1 presents the administration site version of this file.

Listing 5.1: Administration site weblogic.xml descriptor file.

 <!DOCTYPE weblogic-web-app PUBLIC  "-//BEA Systems, Inc.//DTD Web Application 8.1//EN"  "http://www.bea.com/servers/wls810/dtd/weblogic-web-jar.dtd"> <weblogic-web-app>   <security-role-assignment>     <role-name>admin</role-name>     <principal-name>BigRezAdministrators</principal-name>   </security-role-assignment>   <security-role-assignment>     <role-name>hoteladmin</role-name>     <principal-name>HotelAdministrators</principal-name>   </security-role-assignment>   <session-descriptor>     <session-param>       <param-name>PersistentStoreType</param-name>       <param-value>memory</param-value>     </session-param>   </session-descriptor>   <jsp-descriptor>     <jsp-param>       <param-name>pageCheckSeconds</param-name>       <param-value>1</param-value>     </jsp-param>     <jsp-param>       <param-name>debug</param-name>       <param-value>true</param-value>     </jsp-param>     <jsp-param>       <param-name>keepgenerated</param-name>       <param-value>true</param-value>     </jsp-param>   </jsp-descriptor> </weblogic-web-app>

We ve defined only three sections in this file, and within these sections only a small number of elements. We ll walk through these sections first and then briefly describe why none of the other sections applies to the bigrez.com application.

The security-role-assignment section maps the roles defined in the web.xml file to principals, either groups or users, in the WebLogic Server environment. This topic is discussed in more detail in Chapters 4 and 10.

The session-descriptor section contains a single element defining the PersistenceStoreType to be memory :

 <session-descriptor>     <session-param>       <param-name>  PersistentStoreType  </param-name>       <param-value>  memory  </param-value>     </session-param>   </session-descriptor>

We re willing to accept the default values for all of the other session-related param-eters defined in this section. In fact, memory itself is the default value for the PersistentStoreType parameter, but we ve included it in this file as a reminder to ourselves to change the value to replicated when we get ready for a clustered production release of the application.

The jsp-descriptor section contains some parameters defining both nondefault values and values we must revisit and modify when making a production release. The pageCheckSeconds parameter, for example, should be set to the value -1 in production to disable all page checking and recompilation.

The following list identifies sections we did not require in the weblogic.xml file and explains our rationale for excluding them to give you an idea about when they might be required in your development efforts:

Context root information. We will be deploying the user and administration Web applications in an enterprise application ( .ear ) file. The context root will be defined in the application.xml file.

Resource references. We ve chosen to access EJB components using JNDI names and a Locator utility class, so no ejb-ref or ejb-local-ref elements are necessary in web.xml , and no matching ejb-reference-description elements are required here.

Directory mapping information. Images are placed in the user and administration Web applications rather than mapped to a separate directory using this section.

Most Web applications require very little configuration information in the weblogic.xml file. Unlike the WebLogic Server-specific EJB descriptors, which are almost always necessary and are usually very long and complex, the default values for weblogic.xml are often sufficient.

Precompiling JSP Components

At some point in the packaging process you have a decision to make: Should JSP pages in the application be processed and compiled by the server when the page is first accessed by a user, or should all pages be precompiled before deploying the application? Precompiling improves site performance and ensures that all JSP pages in the site compile before deployment takes place. Without precompiling the JSP pages, syntax errors in scriptlet code and custom-tag elements will not be caught until a user accesses the page.

Best Practice

All production and test deployments should include precompiled JSP pages. Development deployments intended for use on the developer s workstation may use precompiled pages or on-the-fly compilation.

As discussed in Chapter 1, WebLogic Server provides a utility called weblogic.jspc , which can be used to precompile JSP pages in the Web application. Precompiling pages essentially simulates the page parsing, servlet generation, and servlet compiling that occur when a JSP page is accessed during site operation.

Although you can use the weblogic.jspc utility on a deployed, exploded Web application located in the applications directory of a WebLogic Server domain, a better technique includes the precompilation step in the build process used to create and package the Web application. In this technique, the precompiled JSP classes are created in a staging area for the application and packaged in a manner very similar to other Java classes.

The bigrez.com example application contains two separate Web applications, user and admin . As shown in Figure 5.5, these Web applications are located in the directories web-user and web-admin below the root working directory for the overall application.

Figure 5.5: Web applications located in working directory structure.

This type of development environment structure is documented and described in Chapter 13 when we cover development best practices. For the purposes of this discussion, the key item to note is that the Web applications themselves are located in the working directory hierarchy. All JSP files, descriptors, and other files are in the web-user and web-admin directories, providing a natural staging area for precompiling JSP pages and for packaging the Web applications.

WebLogic Server 8.1 introduces a new application compiler, weblogic.appc , capable of compiling enterprise-application ( .ear ) files, EJB archive ( .jar ) files, Web application ( .war ) files, and exploded versions of these files. You can use weblogic.appc to validate the descriptors and precompile the JSP files in a Web application by invoking the utility and passing it the root directory for the application:

 java -classpath ... weblogic.appc src/web-user

Many options and parameters are available with weblogic.appc; see the BEA online documentation at http://edocs.bea.com/wls/docs81/webapp/basics.html for details.

Integrating weblogic.appc in your build.xml file is accomplished using a new Ant task, wlappc , also introduced in WebLogic Server 8.1. The build.xml file for bigrez.com includes targets for precompiling the JSP files in the web-user and web-admin directories using this new wlappc task:

 <taskdef name=wlappc classname=weblogic.ant.taskdefs.j2ee.Appc/> <target name=jspc-user>   <!-- Pre-compile JSP pages to src/web-user/WEB-INF/classes -->   <wlappc source=${webuser}            classpathref=jspc.user.classpath verbose=true>   </wlappc> </target> <target name=jspc-admin>   <!-- Pre-compile JSP pages to src/web-admin/WEB-INF/classes -->   <wlappc source=${webadmin}            classpathref=jspc.admin.classpath verbose=true>   </wlappc> </target>

In previous versions of WebLogic Server these targets would have invoked the weblogic.jspc utility as shown here:

 <target name=jspc-user>   <java classname=weblogic.jspc fork=yes         classpathref=jspc.user.classpath>     <arg line=-depend -compileAll -k -webapp ${webuser}         -d ${webuser}/WEB-INF/classes/>   </java> </target> <target name=jspc-admin>   <java classname=weblogic.jspc fork=yes         classpathref=jspc.admin.classpath>     <arg line=-depend -compileAll -k -webapp ${webadmin}        -d ${webadmin}/WEB-INF/classes/>   </java> </target>

The webuser and webadmin properties are defined in build.xml to reference the appropriate subdirectories of the root directory:

 <property name="webuser" value="${src}/web-user"/> <property name="webadmin" value="${src}/web-admin"/>

These jspc targets scan the Web application directories for all files ending in .jsp and perform the same servlet-generation and compilation steps performed by the application server at run time. The weblogic.appc compiler requires the same descriptor files, library archive files, and Java class files as the run-time container requires. The WEB-INF directory must therefore contain the appropriate descriptors, and the classpath for weblogic.appc must include all required directories and archive files.

The jspc tasks create a set of .class files in the WEB-INF/classes/jsp_servlet directory under each Web application. These files are the precompiled JSP servlet classes and should be packaged and deployed in this same location in the final Web application archive file or exploded structure.

Note that the generated code in the precompiled class is very picky about the timestamp of the associated JSP file. If the JSP file in the deployed Web application is older or newer than the file used to create the precompiled class, the precompiled class will be ignored at run time, and the normal on-the-fly JSP compilation will occur. To avoid this problem, be careful to preserve the file timestamp when copying JSP files from the area used to create the precompiled classes to an exploded application structure or staging area. In the dist task in the bigrez.com build process, for example, the preservelastmodified attribute is included in the copy task to ensure that the JSP files retain the proper timestamps:

 <target name="dist" depends="compile">   <!-- Copy all of the webapplication files to the proper webapps -->   <copy todir="${webapp.user.dir}"  preservelastmodified="true"  >     <fileset dir="${webuser}" includes="**/*.*"/>   </copy>   <copy todir="${webapp.admin.dir}"  preservelastmodified="true"  >     <fileset dir="${webadmin}" includes="**/*.*"/>   </copy>   ... </target>

Best Practice

Preserve JSP file timestamps when copying to the staging area or exploded Web application to ensure precompiled classes are used at run time.

The complete bigrez.com build file, build.xml , is available in the downloadable example code for your reference. Chapter 8 discusses the packaging and deployment of the entire bigrez.com enterprise application using the targets in build.xml .

There is one additional best practice to discuss related to precompiling JSP pages. It is a rather mundane recommendation, but it can be costly if you do not follow it. Any partial pages or snippets of scriplet code included in the actual JSP pages using < %@ include file= ... % > should have a file extension other than .jsp . The .jspf file extension is recommended in the JSP specification, but any extension will work.

Why is using a different extension important? The weblogic.appc compiler typically scans the Web application directory and compiles all files that match the desired file name ( *.jsp ) and will probably not be able to compile any partial pages it encounters. They were never intended to be stand-alone pages yielding their own servlet classes ”they are simply snippets of HTML or JSP code included in a master JSP page. Many developers wait to begin precompiling their JSP pages until late in the development cycle and learn this lesson the hard way.

Note that this practice applies only to the static < %@ include file= snippet .jspf % > directive and not to the dynamic < jsp:include file= header.jsp / > directive. The dynamic directive assumes the target page is a stand-alone JSP page capable of being converted to a Java servlet, so the target page should be included in the precompilation process and should retain the .jsp file extension.

Best Practice

Use the .jspf file extension for all partial pages and JSP snippets included in JSP pages using the static < %@ include file= ... % > directive to avoid precompilation problems.

Creating an Exploded Web Application

To create an exploded Web application, you basically copy the Web application directory structure contained in the work area of your application to the appropriate location in the WebLogic Server domain. The deployed version of the application therefore retains all of the structure and individual files discussed in the previous sections.

Typically, a set of copy tasks is created in the build.xml script for the application that copy the Web application components, along with appropriate Java classes compiled to a build directory, to the destination directory in the WebLogic Server directory structure.

In bigrez.com , we are deploying the user and administration Web applications in exploded format in an exploded enterprise application ( .ear ) file as part of the development build process. We ll defer the discussion of the exploded .ear format to Chapter 8 and simply state that the proper locations for the two exploded Web applications become the following:

 /mastering/user_projects/bigrezdomain/applications/rezapp/  user  /mastering/user_projects/bigrezdomain/applications/rezapp/  admin

These locations are defined at the top of the build.xml file using properties defined in build.properties :

 build.xml:   <property name="domain.dir" value="${DOMAIN_HOME}/${DOMAIN}"/>   <property name="applications" value="${domain.dir}/applications"/>   <property name="deploy.dir" value="${applications}/${APPLICATION}"/>   <property name="  webapp.user.dir  " value="${deploy.dir}/user"/>   <property name="  webapp.admin.dir  " value="${deploy.dir}/admin"/> build.properties:   WEBLOGIC_HOME=c:/bea/weblogic81   DOMAIN_HOME=c:/mastering/user_projects   DOMAIN=bigrezdomain   APPLICATION=rezapp

Note that a Web application deployed as a stand-alone application in the WebLogic Server domain, rather than as a part of an enterprise application ( .ear ) file, would be deployed directly to the applications directory.

The copy tasks used by bigrez.com to deploy the exploded Web applications are part of the dist task:

 <target name="  dist  " depends="makeapp,ejbjar">   <!-- Copy all of the webapplication files to the proper webapps -->   <copy todir="${webapp.user.dir}" preservelastmodified="true">     <fileset dir="${webuser}" includes="**/*.*"/>   </copy>   <copy todir="${webapp.admin.dir}" preservelastmodified="true">     <fileset dir="${webadmin}" includes="**/*.*"/>   </copy>   <!-- Copy the user webapp classes to the user/WEB-INF/classes -->   <copy todir="${webapp.user.dir}/WEB-INF/classes">     <fileset dir="${build}"               includes="**/ui/**/*.class,**/form/**/*.class"              excludes="**/admin/**/*.class" />   </copy>   <!-- Copy the admin webapp classes to the admin/WEB-INF/classes -->   <copy todir="${webapp.admin.dir}/WEB-INF/classes">     <fileset dir="${build}"               includes="**/ui/**/*.class,**/form/**/*.class"              excludes="**/user/**/*.class" />   </copy>   <!-- Copy the EJB jar file  -->   <copy file="${ejb.jar.filename}" todir="${deploy.dir}" />   <!-- Copy properties files to the webapp/WEB-INF/classes -->   <copy todir="${webapp.user.dir}/WEB-INF/classes">     <fileset dir="${src}" includes="**/ui/user/*.properties" />   </copy>   <!-- Copy properties files to the webapp/WEB-INF/classes -->   <copy todir="${webapp.admin.dir}/WEB-INF/classes">     <fileset dir="${src}" includes="**/ui/admin/*.properties" />   </copy>   <!-- Copy EAR descriptor files to application META-INF -->   <copy todir="${deploy.dir}/META-INF">     <fileset dir="${basedir}/dd">        <include name="application.xml,weblogic-application.xml" />     </fileset>   </copy>   <!-- Copy utility archives to application lib directory -->   <copy todir="${deploy.dir}/lib">     <fileset dir="${basedir}/lib" includes="log4j.jar" />   </copy>  </target>

These copy tasks are responsible for moving all of the Web application components, descriptors, properties files, precompiled JSP classes, and supporting Java classes from the working area to the proper deployment directory. Note that the copy tasks for the user and admin support classes are careful to copy only the appropriate package hierarchies to the destination directory. We developed both types of support classes in a single work area directory structure, segregated only by the user or admin in the package name, and we use that package name difference to copy the correct files to each Web application destination.

Creating a Web Application Archive File

A Web application archive file, or .war file, contains all of the Web application components, descriptors, and supporting classes in a single file. The internal structure of the .war file is identical to the equivalent exploded Web application deployment directory.

Creating a .war file is easy enough in theory: You simply execute the appropriate jar command to include all of the desired Web application components and supporting files in the archive. In practice, you need a mechanism to assemble the proper components and files in a staging area in preparation for the standard jar utility, or you need a better jar technique that allows you to piece together components and supporting classes from various locations in a single archive. Either solution works, but we prefer the latter.

The recommended archive technique uses the war task in Ant to build the archive from a variety of files. The war task, like the basic jar Ant task, allows the definition of multiple fileset embedded elements, each with flexible and powerful controls for including and excluding files from the archive. The war task adds a number of special elements that automatically place the specified files in their proper locations in the Web application directory structure.

In the bigrez.com build process, the .war files for each Web application are created using the following two tasks in the build.xml file:

 <target name="war-user" depends="compile">     <!-- Create user.war webapp archive file -->     <war destfile="${basedir}/user.war"          webxml="${webuser}/WEB-INF/web.xml">       <fileset dir="${webuser}"                includes="**/*.*"                excludes="**/*.java, WEB-INF/web.xml"/>       <classes dir="${build}"                includes="**/ui/**/*.class, **/form/**/*.class"                excludes="**/admin/**/*.class" />       <classes dir="${srcjava}"                includes="**/ui/user/*.properties" />     </war>   </target>   <target name="war-admin" depends="compile">     <!-- Create admin.war webapp archive file -->     <war destfile="${basedir}/admin.war"          webxml="${webadmin}/WEB-INF/web.xml">       <fileset dir="${webadmin}"                includes="**/*.*"                excludes="**/*.java, WEB-INF/web.xml"/>       <classes dir="${build}"                includes="**/ui/**/*.class, **/form/**/*.class"                excludes="**/user/**/*.class" />       <classes dir="${srcjava}"                includes="**/ui/admin/*.properties" />     </war>   </target>

That s all you need to create the Web application archive from the Web application components in our work area and the supporting classes in the build area. The simplicity of this step is a direct result of the directory structure and practices we ve adopted in the development environment.