Packaging Applications Targeted for WebLogic Server


The J2EE standard defines the specifications in which J2EE applications can be packaged in a standard, generic, and portable way. It defines these standards for Web applications, enterprise JavaBeans, resource adaptors, enterprise applications, and client applications. However, the J2EE specification defines only the application packaging standards and does not specify how a J2EE application should be deployed to a J2EE server. Any J2EE-compliant server can implement its own deployment behavior to give maximum flexibility to the J2EE developer. This section discusses the packaging of the most common J2EE applications: Web applications, EJBs, and enterprise applications. We also discuss the directory structure for assembling these applications as well as the deployment descriptors for each type of application.

Applications that must be deployed to WebLogic Server should be packaged according to the J2EE standard. Packaging a J2EE application requires a specific directory structure containing Java classes, deployment descriptors, and other third-party JARs.

Web Applications

A Web application consists of application files such as servlet classes, JSPs, static HTML pages, image files, and tag libraries. It also contains a standard J2EE deployment descriptor file named web.xml and a WebLogic-specific deployment descriptor named weblogic.xml . These deployment descriptor files together define various parameters for the Web container to configure the Web Application at runtime.

The Web Application Directory Structure

The directory structure for assembling a Web application is defined by the Servlet specification, as follows :

  • webAppName/

    This is the document root of the Web application, and all the static files in the Web application are contained within it. These files include JSPs, HTML files, image files, and any other static files. These files can also be included within subdirectories within the document root. For example, it's common practice to have all the image files within a Web application included in an images directory inside the document root. The JSP and HTML files within the document root can then access the image files relative to the document root.

    Note

    In the default installation of WebLogic Server, this directory is named DefaultWebApp , under user_domains/< domain_name>/ applications .


  • webAppName/META-INF

    This directory contains the manifest file for archiving.

  • webAppName/WEB-INF

    All files under WEB-INF are private, and are not served to a client. The WEB-INF directory contains the deployment descriptor files and, optionally , two other directories named classes and lib .

  • webAppName/WEB-INF/classes

    This directory contains servlet classes and other utility classes required by the servlets.

  • webAppName/WEB-INF/lib

    This directory contains JAR files used by the Web application, such as tag libraries.

  • webAppName/WEB-INF/web.xml

    This is the standard deployment descriptor for a Web application defined by the Servlet specification. It contains parameters for configuring servlets, URL-patterns, security constraints, life cycle listeners, filters, and so forth.

  • webAppName/WEB-INF/weblogic.xml

    This is the WebLogic-specific deployment descriptor that's used by the Web container to define various JSP attributes, HTTP session parameters, security roles, and more.

A Web application can be deployed as a collection of files that use this directory structure (exploded directory format). The exploded directory deployment method is typically used during the development stages of a Web application. Alternatively, the Web application can be assembled in the preceding directory structure in order to stage the WAR file for the jar command. A file created with the Java jar tool bundles the files in a directory into a single Java archive file, maintaining the directory structure. The WAR file can then be deployed alone or packaged in an Enterprise Archive (EAR file) with other application components, including other Web applications and EJB components . This archive method of deployment is recommended for production environments.

Web Application Deployment Descriptors

Deployment descriptors are XML documents that define the contents of the Web application and contain other parameters the Web container will use while configuring and deploying the application to WebLogic Server.

The web.xml descriptor is a required descriptor as per the Servlet specification, and contains all the configuration parameters needed to deploy a Web application. For example, the web.xml descriptor contains parameters for

  • Configuring servlets and mapping them to specific URL patterns

  • Servlet initialization parameters

  • Declaring JSP tag libraries

  • Declaring MIME type mappings

  • Declaring welcome file lists

  • Declaring error pages

  • Defining security constraints

  • Defining lifecycle listeners

  • Defining filters

The weblogic.xml descriptor is an optional descriptor file. This file declares parameters that are specific to the WebLogic Server Web container. Some of the parameters this file contains are for

  • Declaring JSP parameters such as pagecheckseconds , keepgenerates , workingDir , and so on

  • HTTP session parameters such as session timeout, persistence type, and others

  • Declaring security role mappings

  • Declaring JNDI mappings

You can create deployment descriptors manually using an XML editor, or you can use WebLogic-specific Java-based utilities to automatically generate them for you, as discussed in the next section.

Generating Web Application Deployment Descriptors Automatically

WebLogic Server includes a Java-based utility called WebInit that can be used to generate both the J2EE standard web.xml descriptor and the WebLogic-specific weblogic.xml descriptor. The utility should be pointed at the directory where you've assembled the Web application in the prescribed directory structure we previously discussed.

To generate the deployment descriptors automatically, follow these steps:

  1. Set the local environment using the setWLSEnv.cmd script (Windows) or setWLSEnv.sh script (Unix).

  2. Run the utility by executing the following command on the command line:

       
      java weblogic.marathon.ddinit.WebInit  webAppName   

    where webAppName is the document root of your Web application directory.

The utility examines the objects present in the directory structure and then adds the appropriate elements to the deployment descriptors based on the servlet classes, lifecycle listeners, filters, JSPs, tag libraries, and other parameters it finds. The deployment descriptors are created on a best guess effort and therefore may be wrong. So, after generating them using the WebInit utility, they should be verified for consistency. If there are parameters that are incorrect or need to be changed, you can edit the deployment descriptor using the Administration Console, WebLogic Builder tool, or any other XML editor.

To showcase this utility, let's say you have a simple HelloWorld Web application that's comprised of one servlet, which is contained in the following directory:

 
 D:\bea\user_projects\mydomain\applications\HelloApp 

The only missing files are the deployment descriptors inside the WEB-INF directory. The output of running the WebInit utility on the HelloApp directory is as follows:

 
 java weblogic.marathon.ddinit.WebInit HelloApp [ModuleInit]: Searching for class files [ModuleInit]: 1 classes found [ModuleInit]: found servlet class: 'objectmind.servlets.MyServlet' [ModuleInit]: Discovered module type for D:\bea\user_projects\mydomain\applications\HelloApp [ModuleInit]: Found Web components. Initializing descriptors [ModuleInit]: Writing descriptors filters=0 servlets=1 tags=0 

At the end of the run, web.xml and weblogic.xml are created in the WEB-INF directory of the HelloApp directory.

Packaging Web Applications

To stage and package a Web application, follow these steps:

  1. Develop the servlets, JSPs, static files, and tag libraries that make up the Web application.

  2. Assemble the Web application files in the appropriate directory structure described previously by placing each file in its prescribed directory.

  3. Create the deployment descriptors: web.xml and weblogic.xml (optional). These can be created manually or automatically using WebLogic-specific utilities, as discussed in the previous section.

  4. To archive the Web application in a WAR file, use the following command from the root directory of the Web application directory:

       
      jar -cvf  myWebApp  .war  

    where myWebApp is the name of the WAR file that you want to create.

The Web application archive is now ready for deployment to the server. To deploy the Web application in an exploded format, you can copy the entire directory structure of the Web application to the < domainName> /applications directory. WebLogic Server will automatically deploy the Web application if it is running in development mode. Alternatively, you can also use the Administration Console to stage the application from the current directory and then deploy it. Application deployment is discussed in detail later in this chapter in the "Deploying Applications to WebLogic Server" section.

Enterprise JavaBean Applications

Enterprise JavaBean Applications consist of three Java classes: the remote interface, the home interface, and the bean class. Besides these Java classes, EJB applications also contain deployment descriptors depending on the type of the bean. The EJB container uses these deployment descriptors to configure and deploy the bean at runtime.

The Enterprise JavaBean Application Directory Structure

EJBs are deployed as a JAR archive file or they can be bundled inside of an enterprise application (EAR file). As with Web applications, in order to be packaged correctly, EJB applications must follow a specific directory structure, which in this case is defined by the EJB Specification, as follows:

  • StagingDir/

    The staging directory contains the class files for the EJBs, for example:

    • The home interface for the EJB

    • The remote interface for the EJB

    • The class that implements the remote interface

    The staging directory is also where the JAR archive file is ultimately built. The staging directory folder itself is not included in the JAR archive file. However, its contents constitute the root of the JAR file.

  • StagingDir/META-IN

    This directory contains the following deployment descriptors related to the EJB application:

    • ejb-jar.xml A standard deployment descriptor

    • weblogic-ejb-jar.xml A WebLogic-specific deployment descriptor

    • weblogic-cmp-rdbms-jar.xml (optional) A WebLogic-specific descriptor for object-to-relational mapping of CMP entity EJBs.

EJB Application Deployment Descriptors

WebLogic Server EJB applications contain the following deployment descriptor files:

  • ejb-jar.xml This descriptor file is mandatory per the EJB Specification. The file defines the classes that make up the EJB: the bean implementation class, the home and remote interfaces, and the primary-key class for CMP beans. It also defines the container-managed fields for the CMP beans, transaction demarcation types, and finder queries for CMP beans.

  • weblogic-ejb-jar.xml This descriptor is WebLogic Serverspecific and contains various attributes that define the clustering, caching, concurrency, and transaction behavior for the bean. The JNDI name for the bean is also defined in this descriptor.

  • weblogic-cmp-rdbms-jar.xml This descriptor is also WebLogic Serverspecific and is used only in the case of container-managed entity beans. The JDBC datasource that the container will use for this bean is defined in this file as well as the table that the bean represents. The descriptor also contains the mapping between the CMP fields in the bean to the corresponding columns in the database table that the bean represents.

Generating EJB Application Deployment Descriptors Automatically

WebLogic Server includes a Java-based utility called EJBInit, which creates the J2EE standard ejb-jar.xml deployment descriptor as well as the WebLogic-specific weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml descriptors. The utility should be pointed at the EJB application's staging directory, which contains the compiled EJB classes placed in a directory structure that corresponds to their respective package names .

To generate the deployment descriptors for the EJB automatically, follow these steps:

  1. Set the local WebLogic Server environment using the setWLSEnv.cmd script (Windows) or setWLSEnv.sh script (Unix).

  2. Run the utility by executing the following command from the command line:

       
      java weblogic.marathon.ddinit.EJBInit staging_directory  

The EJBInit utility examines the classes in the staging directory structure and then adds the appropriate elements to the deployment descriptors based on the EJB classes it finds. The deployment descriptors are created on a best guess effort; therefore, they might be incorrect. For this reason, after the descriptors are generated using the EJBInit utility, they should be verified for consistency. If parameters are incorrect or need to be changed, you can edit the deployment descriptor using the Administration Console, the WebLogic Builder tool, or any other XML editor.

For example, the results of running the EJBInit utility on a sample AccountEJB application, which contains a CMP entity bean are as follows:

 
 [ModuleInit]: SEARching for class files [ModuleInit]: 5 classes found [ModuleInit]: Discovered module type for D:\releases\70platformsp1\weblogic700\ samples\server\src\myexamples\deployment\containerManaged\build [ModuleInit]: Found EJB components. Initializing descriptors [ModuleInit]: Found EJBHome: examples.ejb20.basic.containerManaged.AccountHome [ModuleInit]: Bean class: examples.ejb20.basic.containerManaged.AccountBean [ModuleInit]: Setting prim-key-class to 'java.lang.String' [ModuleInit]: Added CMP field 'accountId' [ModuleInit]: Setting primkey-field to 'accountId' [ModuleInit]: Added CMP field 'balance' [ModuleInit]: Added CMP field 'accountType' [ModuleInit]: Creating weblogic rdbms descriptor [ModuleInit]: Adding Entity bean 'AccountBean' [ModuleInit]: [ModuleInit]: Creating relations [ModuleInit]: Writing descriptors [ModuleInit]: Building module with newly created descriptors [ModuleInit]: Finished building module [EJBJARCMBean] Writing descriptors 

At the end of the run, the ejb-jar.xml , weblogic-ejb-jar.xml , and weblogic-cmp-rdbms-jar.xml deployment descriptor files are created in the META-INF dir.

Packaging EJB Applications

To stage and package an EJB application, follow these steps:

  1. Develop the necessary EJB classes The home interface, remote interface, and the bean implementation class for the EJB. Compile them into a staging directory. The compiled classes should be placed within directories matching their Java package names.

  2. Create the required deployment descriptors ejb-jar.xml , weblogic-ejb-jar.xml , and weblogic-cmp-rdbms-jar.xml (for CMP beans). These descriptor files can be created manually or you can automatically generate them using WebLogic-specific utilities, as described in the previous section. These descriptor files should be placed inside the META-INF directory in the staging directory.

  3. Ensure that the EJB class files and the descriptor files are correctly placed in the staging directory, as discussed previously.

  4. Archive the staging directory files into a JAR file using the following command from the root of the staging directory:

       
      jar -cvf  myEJB  .jar  

You can run ejbc on this archive to generate the container classes depending on the parameters specified in the deployment descriptors. If you deploy the archive without running ejbc on it, WebLogic Server runs ejbc on the archive automatically to generate the container-specific classes.

Enterprise Applications

An enterprise application is an archive file that typically packages a Web application archive (WAR file) with one or more additional resources such as EJB applications ( .jar ), Java applications ( .jar ), and resource adapters ( .rar ) into a single deployable archive file ( .ear ).

Besides these module archives, the EAR file also contains a deployment descriptor named application.xml , which defines the modules packaged in the enterprise archive file and the order in which they should be deployed to WebLogic Server. The format of application.xml is defined by the J2EE Specification.

The Enterprise Application Directory Structure

To be packaged correctly, enterprise applications must follow a specific directory structure, which is defined by the J2EE Specification, as follows:

  • myEAR /

    This is the document root of the enterprise application directory, which contains all the Web and EJB application modules ( .war and .jar files), as well as any utility class files ( .jar ) required by the enterprise application

  • myEAR /META-INF

    This directory contains the following deployment descriptor files related to the enterprise application:

    • application.xml A J2EE standard enterprise application descriptor

    • weblogic-application.xml A WebLogic-specific application descriptor

Enterprise Application Deployment Descriptors

As briefly mentioned in the previous section, WebLogic Server Enterprise applications contain the application.xml and the weblogic-application.xml deployment descriptors.

The application.xml file is a J2EE standard deployment descriptor for configuring an enterprise application. It contains information about the archive modules that comprise an enterprise application. You can also define security roles for your application within this descriptor file.

The structure of an application.xml file that corresponds to the following enterprise application directory is listed in Listing 27.1:

 
 MyEAR/ (Document root of the Enterprise Application) webApp1.war (Web Application archive) webApp2.war (Another Web Application module) ejb1.jar (EJB archive) ejb2.jar (Another EJB module) myUtilityClasses.jar (Utility classes archive) META-INF/ (Contains the deployment descriptor files) application.xml (Standard Enterprise Application descriptor) weblogic-application.xml (WebLogic specific application descriptor) 
Listing 27.1 A Sample Structure of an application.xml File
 <?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>myEAR</display-name> <description>myEAR</description> <module> <ejb>ejb1.jar</ejb> </module> <module> <ejb>ejb2.jar</ejb> </module> <module> <web> <web-uri>webApp1.war</web-uri> <context-root>webApp1</context-root> </web> </module> <module> <web> <web-uri>webApp2.war</web-uri> <context-root>webApp2</context-root> </web> </module> <module> <java>myUtilityClasses.jar</java> </module> <security-role> <description> platinum customers</description> <role>platinumCustomerRole</role> </security-role> </application> 

Each component in application.xml is defined within a < module ></ module > element. Depending on the type of the module, it can be defined within the elements <ejb> , <web> , or <java> . When the application archive is deployed to WebLogic Server, the modules are deployed in the order in which they're defined in the application.xml file. The preceding descriptor also defines a security-role element that defines the name of the role that's used for authorization within the application. The role name can be mapped to WebLogic Server users and groups in weblogic-application.xml .

The weblogic-application.xml descriptor file is WebLogic-specific and is required only if you want to configure application scoping or to map the security roles defined in the application.xml to WebLogic users and groups.

Application scoping is a WebLogic-specific feature provided to configure resources for a particular application at the application level instead of configuring resources for the entire WebLogic Server. These resources include XML parsers, XML entity mappings, JDBC connection pools, security realms, and so forth. This helps in partitioning the resources between different applications deployed on the same WebLogic Server. For example, you might need to use a particular XML parser for one application and a different one for the other application. Application scoping enables you to configure this requirement. Another advantage of the scoping feature is that you can deploy an enterprise application archive directly onto another instance of WebLogic Server without having to configure the resources on that server.

Packaging Enterprise Applications

To stage and package an enterprise application, follow these steps:

  1. Create a staging directory that will serve as the root of the enterprise application.

  2. Copy the Web application archives ( .war ) and EJB application archives ( .ear ) into the root of the staging directory.

  3. Copy any resource adaptor archives ( .rar ) and utility archives, if required, to the same directory.

  4. Create a META-INF directory inside the root of the staging directory.

  5. Create the application.xml deployment descriptor in the META-INF directory to include all the modules within the application as described in the previous section.

  6. Create the weblogic-application.xml deployment descriptor, if required.

  7. Create the enterprise archive file ( .ear ) by using the following command from within the root of the application's staging directory:

       
      jar -cvf  myApplication  .ear  

The enterprise archive file is now ready for deployment to WebLogic Server. You can deploy it using the WebLogic Console, or by using the weblogic.Deployer utility, or by just auto-deploying it through the < domainName >/applications directory if WebLogic Server is configured to be in development mode.



BEA WebLogic Platform 7
BEA WebLogic Platform 7
ISBN: 0789727129
EAN: 2147483647
Year: 2003
Pages: 360

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net