Application Packaging and Predeployment

Deployment is the process of placing and activating applications within WebLogic Server or cluster configurations. Prior to deployment, applications must be packaged. Packaging entails staging, creating deployment descriptors, and archiving the application. We'll discuss packaging Web and enterprise applications.

Packaging Web Applications

As detailed in Chapter 6, “Introduction to WebLogic Web Applications,” Web applications are packaged within WAR files. WAR files are created using the Java archive utility jar command and designating a .war extension for the archive. WAR files contain all files necessary to execute the Web application, which may include JSP(s), JSP tag libraries, servlets (see Chapter 14, “Writing WebLogic Server Servlets,” for details on servlet registrations), other supporting Java classes, HTML(s), image files, and so on. To package a Web application, you must assemble the target application files (HTMLs, JSPs, servlets, and so forth) within a staging directory. All servlets and supporting Java class files should be marshaled under the Web application's WEB-INF/classes directory. JSP and HTML files are placed within the applications top-level staging directory. The Web application's deployment descriptors must be created and placed under the directory WEB-INF, as shown here:

/WebAppName (staging directory)
  JSP(s) (subdirectories allowed)
  HTML(s)       "
  images       "
  non-Java files  "
 /WEB_INF
  web.xml
  weblogic.xml
  /Classes
    Servlets
    Other Java Classes
  /lib
    JSP Tag Libraries

There are two deployment descriptors for a Web application: web.xml and weblogic.xml. The web.xml is the J2EE standard for defining a Web application. This descriptor defines non-server-specific items such as servlet mappings, deployment-time attributes, context parameters, filters, filter mappings, listeners, MIME mappings, welcome pages, error pages, JSP tag libraries mappings, security, and other non-server-specific items. A partial listing of a web.xml that can be used for the global auctions application is shown in Listing 7.1.

Listing 7.1 Partial Web.xml

<?xml version="1.0" ?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http:/
/java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
 <welcome-file-list>
  <welcome-file>index.jsp</welcome-file>
 </welcome-file-list>

 <servlet>
  <servlet-name>FindItemsServlet</servlet-name>
  <servlet-class>com.gams.servlets.system.FindItemsServlet</servlet-class>
 </servlet>

 <security-constraint>
  <web-resource-collection>
  <web-resource-name>MySecureBit0</web-resource-name>
   <url-pattern>/AdminRequestProcessor</url-pattern>
   <http-method>GET</http-method>
   <http-method>POST</http-method>
  </web-resource-collection>
  <auth-constraint>
   <role-name>administrator</role-name>
  </auth-constraint>
  <user-data-constraint>
   <transport-guarantee>NONE</transport-guarantee>
  </user-data-constraint>
 </security-constraint>

 <login-config>
  <auth-method>FORM</auth-method>
  <realm-name>default</realm-name>
  <form-login-config>
   <form-login-page>/login.jsp</form-login-page>
   <form-error-page>/error.jsp</form-error-page>
  </form-login-config>
 </login-config>

 <security-role>
  <role-name>administrator</role-name>
 </security-role>

 <ejb-ref>
  <ejb-ref-name>ejb/opcadminfacade</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>com.sun.j2ee.blueprints.opc.admin.ejb.OPCAdminFacadeHome</home>
  <remote>com.sun.j2ee.blueprints.opc.admin.ejb.OPCAdminFacade</remote>
 </ejb-ref>
...
 <taglib>
  <taglib-uri>
   itemDisplay.tld
  </taglib-uri>
  <taglib-location>
    /WEB-INF/lib/itemDisplay-tags.jar
   </taglib-location>
 </taglib>
</web-app>

The weblogic.xml deployment descriptor contains WebLogic-specific connectivity items such as HTTP session or cookie parameters, JSP parameters, resource references (for DataSources, EJBs, security realm), security role assignments, character set mappings, and container attributes. A partial listing of a weblogic.xml that can be used for the global auctions application is shown in Listing 7.2.

Listing 7.2 Partial Weblogic.xml

<!DOCTYPE weblogic-web-app PUBLIC "-//BEA
Systems, Inc.//DTD Web Application 7.0//EN"
"http://www.bea.com/servers/wls700/dtd/weblogic700-web-jar.dtd">

<weblogic-web-app>
 <description>WebLogic Descriptor</description>
  <security-role-assignment>
  <role-name>administrator</role-name>
  <principal-name>admin</principal-name>
 </security-role-assignment>
 <session-descriptor>
  <session-param>
   <param-name>PersistentStoreType</param-name>
   <param-value>replicated</param-value>
  </session-param>
 </session-descriptor>
 <reference-descriptor>
  <ejb-reference-description>
   <ejb-ref-name>ejb/opcadminfacade</ejb-ref-name>
    <jndi-name>ejb/remote/opcApplication/opcadminfacade</jndi-name>
  </ejb-reference-description>
 </reference-descriptor>
 <jsp-descriptor>
   <jsp-param>
    <param-name>
     pageCheckSeconds
    </param-name>
    <param-value>
     1
    </param-value>
   </jsp-param>
   <jsp-param>
    <param-name>
     verbose
    </param-name>
    <param-value>
     true
    </param-value>
   </jsp-param>
 </jsp-descriptor>
</weblogic-web-app>

After the Web application's files are properly arrayed, the application should be archived within a WAR (Web Archive) file, as shown here:

$ jar cv0f gams.war *.html *.jsp WEB-INF

Note the 0 option in the preceding line. Some HTMLs or JSPs might not function if compressed.

Packaging Enterprise Applications

Enterprise applications contain Web modules, Web applications, EJBs (see Chapter 20, “Enterprise JavaBeans and WebLogic Server,” for information on packaging EJBs), and other Web modules and files required to execute the enterprise-level application. To package an enterprise application, you must assemble the target application files (WAR files, EJB JAR files, deployment descriptor, and so on) within a staging directory. The enterprise application's deployment descriptor must be created and placed under directory META-INF, as shown here:

/EntAppName (staging directory)
  EJB.jar
  WebApp.war
  /APP-INF
   SharedFiles.jar
  /META_INF
   application.xml
   weblogic-application.xml

There are two deployment descriptors for an enterprise application: weblogic-application.xml and application.xml. The weblogic-application.xml specifies WebLogic-specific application deployment information, such as classpath hierarchies, which are discussed later within this section. The application.xml file is the J2EE standard for identifying modules and defining security roles to be used within the enterprise application. A sample listing of an application.xml file that can be used for the global auctions application is shown in Listing 7.3.

Listing 7.3 Sample application.xml

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN'
 'http://java.sun.com/dtd/application_1_3.dtd'>

<application>
 <display-name>gams</display-name>
 <description>Global Auctions Management Systems</description>
 <module>
  <ejb>customer.jar</ejb>
 </module>
  <module>
   <ejb>item.jar</ejb>
 </module>
  <module>
   <ejb>processbid.jar</ejb>
 </module>
 <module>
  <web>
   <web-uri>gams.war</web-uri>
   <context-root>gams</context-root>
  </web>
 </module>
 <security-role>
  <role-name>administrator</role-name>
 </security-role>
</application>

After the enterprise application's files are properly arrayed, the application should be archived within an EAR (Enterprise Archive) file, as shown here:

$ jar cv0f gams.ear *.war *.jar META-INF

In reference to deploying enterprise applications on WebLogic Server: To facilitate hot deployments, WebLogic uses separate class loaders for Web modules deployed within the enterprise application. Therefore, individual Web components cannot see each other's class files. If your Web components (modules) are using the same files, there are three general strategies to employ using WebLogic Server 8.1:

• Place the common or shared files within an archive (JAR file) at the enterprise application level, within APP-INF/lib. Any archives placed here are automatically added to the application's classpath, which is visible to all application modules (see item_A.ear—included in your distribution).

• Place the common or shared files within an archive at the enterprise application level. You must reference that archive within the manifest files of the application module archives. For example, within our example GAMS application, we have a Web application (item.war) that uses some of the same classes that an EJB module (item.jar) does. To avoid class loader/classpath issues, we've moved the common files from each module and placed these files within a shared JAR file called itemUtil.jar. This file is placed under the enterprise application root directory. Then the manifest.mf file of each module's archive is updated to reference the shared JAR file, using its Class-Path attribute as shown here:

  Class-Path: itemUtil.jar
  

  To execute this update, place the Class-Path reference within a text file. Then, using the jar command, execute the following command:

  $jar umf myTextFile WebApp.war (or EJB.jar)
  

  The target module's archive manifest file will be updated with the classpath attribute. This should be done to all enterprise application modules that use any of the common files (see item_B.ear—included in your distribution).

• Define a classloader-structure within the application's weblogic-application.xml. The following classloader-structure (an excerpt from weblogic-application.xml) will make our utility JAR, itemUtil.jar, available to all modules within our item application (item.jar and item.war):

  <classloader-structure>
   <module-ref>
    <module-uri>itemUtil.jar</module-uri>
   </module-ref>
   <classloader-structure>
    <module-ref>
     <module-uri>item.jar</module-uri>
    </module-ref>
    <module-ref>
     <module-uri>item.war</module-uri>
    </module-ref>
   </classloader-structure>
  </classloader-structure>
  

  CAUTION

  Failure to address this common/shared file issue will result in NoClassDefFoundError(s).

  
  

  For more detailed information on WebLogic class loading, refer to http://e-docs.bea.com/wls/docs81/programming/classloading.html.

Creating and Editing Application Deployment Descriptors

Deployment descriptors may be generated automatically using the WebLogic DDInit utility as shown here:

$ java weblogic.ant.taskdefs.war.DDInit c:\...\stagingDirectory (for Web Applications)
$ java weblogic.ant.taskdefs.ear DDInit c:\...\stagingDirectory (for Enterprise Applications)

Existing deployment descriptors can be edited using the WebLogic Builder application.

Start WebLogic Builder as detailed later in the section “Deploying Applications Using WebLogic Builder.” Navigate to and open an application archive. Edit selected elements as shown in Figure 7.1.

Deployment descriptors may also be edited manually using any text editor or the provided BEA XML editor. For more information about creating or editing deployment descriptors refer to the BEA documentation site at http://edocs.beasys.com/wls/docs81/programming/packaging.html or http://e-docs.bea.com/wls/docs81/webapp/deployment.html.

Deployment Descriptor Security Elements

To promote application security, the web.xml and weblogic.xml files provide security implementation elements.

web.xml Security Elements

Within the web.xml file, the <security-constraint> tag (refer to Listing 7.1) is used to protect specific resources based on a URL pattern and an HTTP action. This tag may appear zero or more times within a web.xml file. An excerpt from web-app2_3.dtd regarding this tag is shown here:

<!ELEMENT security-constraint (display-name?, web-resource-collection+,
auth-constraint?, user-data-constraint?)>

Within each <security-constraint> tag, the <display-name> tag is optional. The <web-resource-collection> may appear one or more times. The <auth-constraint> tag is optional, as is the <user-data-constraint> tag.

The <web-resource-collection> tag restricts specified resources. Both the <url-pattern> and the <http-method> tags may appear one or more times. The url-pattern may refer to a directory, filename, or servlet mapping. In the following example, all resources in the admin directory are specified as restricted and available only with the HTTP POST method:

<web-resource-collection>
    <web-resource-name>Admin Pages</web-resource-name>
    <description>Only accessible by authorized administrators</description>
    <url-pattern>/admin/*</url-pattern>
    <http-method>POST</http-method>
</web-resource-collection>

The <auth-constraint> tag as shown in the following snippet defines roles that may access restricted resources. One or more roles may be assigned access. In the following example, the roles of admin and backoffice are specified to have access to resources:

<auth-constraint>
    <description>These are the roles who have access</description>
    <role-name>admin users</role-name>
    <role-name>back office users</role-name>
</auth-constraint>

The <user-data-constraint> shown in the following snippet may be used to indicate that this collection of Web resources should be communicated between the client and the server using no guarantees (NONE), certify that information cannot be changed in transit (INTEGRAL), or encrypted (CONFIDENTIAL). In most cases, the presence of the INTEGRAL or CONFIDENTIAL flag indicates that the use of SSL is required. If the <user-data-constraint> tag isn't present, these Web resources will not rely on SSL for communication.

<user-data-constraint>
    <description>This is how the user data must be transmitted</description>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>

Each <security-constraint> tag and its inner tags within a web.xml indicate one or more sets of protected resources as specified by URL patterns and HTTP methods, the roles that can access them, and whether or not SSL is required for access.

The roles mentioned within the <auth-constraint> tag must be declared within <security-role> tags in the following manner:

<security-role>
    <description>admin</description>
    <role-name>admin users</role-name>
</security-role>
<security-role>
    <description>backoffice</description>
    <role-name>back office users</role-name>
</security-role>

The web.xml file is also used to specify login behavior as shown here:

<login-config>
  <auth-method>BASIC</auth-method>
</login-config>
<login-config>
  <auth-method>FORM</auth-method>
  <form-login-config>
   <form-login-page>login.jsp</form-login-page>
   <form-error-page>error.jsp</form-error-page>
  </form-login-config>
 </login-config>
<login-config>
  <auth-method>CLIENT-CERT</auth-method>
</login-config>

weblogic.xml Security Elements

The roles specified in web.xml are abstract; they must be mapped to actual WebLogic Server users and groups. This occurs within the weblogic.xml file. The <security-role-assignment> tag (refer to Listing 7.2) is used to map a J2EE role to WebLogic Server users and groups. In the following example, the user jeffm and the group Managers are tied to the role called admin users:

<security-role-assignment>
    <role-name>admin users</role-name>
    <principal-name>jeffm</principal-name>
    <principal-name>Managers</principal-name>
</security-role-assignment>

Editing Security Elements

To edit security elements, use WebLogic Builder as shown in Figure 7.1. Click on the application name at the top of the directory tree. In the right pane (editing panel), select the Security Roles tab and enter role names and descriptions as needed. Next, select the target Web application (item.war in Figure 7.1) from the directory tree and select Security Constraints. In the editing panel, click the Add button (a new window appears) and populate security elements as needed.

For example, to create a new security constraint, select the Resources/Pages tab. Enter a Web resource name. This equates to the <display-name> tag. Then add constraints and other security elements as needed. Be sure to add the appropriate security roles (Roles tab). When you're finished, click the OK button in the lower right corner. This will write the modified information back to the web.xml or weblogic.xml file as needed.