bea.com | products | dev2dev | support | askBEA |
![]() |
![]() |
|
![]() |
e-docs > WebLogic Server > Developing WebLogic Server Applications > WebLogic Server Application Packaging |
Developing WebLogic Server Applications
|
WebLogic Server Application Packaging
The following sections describe how to package WebLogic Server components. You must package components before you deploy them to WebLogic Server.
WebLogic Server J2EE applications are packaged according to J2EE specifications. J2EE defines component behaviors and packaging in a generic, portable way, postponing run-time configuration until the component is actually deployed on an application server.
J2EE includes deployment specifications for Web applications, EJB modules, enterprise applications, client applications, and resource adapters. J2EE does not specify how an application is deployed on the target server—only how a standard component or application is packaged.
For each component type, the specifications define the files required and their location in the directory structure. Components and applications may include Java classes for EJBs and servlets, resource adapters, Web pages and supporting files, XML-formatted deployment descriptors, and JAR files containing other components.
An application that is ready to deploy on WebLogic Server may require WebLogic-specific deployment descriptors and, possibly, container classes generated with the WebLogic EJB, RMI, or JSP compilers.
For more information, refer to the J2EE 1.3 specification at: http://java.sun.com/j2ee/download.html#platformspec
A file created with the Java jar tool bundles the files in a directory into a single Java ARchive (JAR) file, maintaining the directory structure. The Java classloader can search for Java class files (and other file types) in a JAR file the same way that it searches a directory in its classpath. Because the classloader can search a directory or a JAR file, you can deploy J2EE components on WebLogic Server in either an "exploded" directory or a JAR file.
JAR files are convenient for packaging components and applications for distribution. They are easier to copy, they use up fewer file handles than an exploded directory, and they can save disk space with file compression. If your Administration Server manages a domain with multiple WebLogic Servers, you can only deploy JAR or EAR files, because the Administration Console does not copy expanded directories to Managed Servers.
The jar utility is in the bin directory of your Java Development Kit. If you have javac in your path, you also have jar in your path. The jar command syntax and behavior is similar to the UNIX tar command.
The most common usages of the jar command are:
The first flag specifies the operation: create, extract, or list (tell). The f flag must be followed by a JAR file name. Without the f flag, jar reads or writes JAR file contents on stdin or stdout which is usually not what you want. See the documentation for the JDK utilities for more about jar command options.
Components and applications have deployment descriptors—XML documents—that describe the contents of the directory or JAR file. Deployment descriptors are text documents formatted with XML tags. The J2EE specifications define standard, portable deployment descriptors for J2EE components and applications. BEA defines additional WebLogic-specific deployment descriptors for deploying a component or application in the WebLogic Server environment.
Table 3-1 lists the types of components and applications and their J2EE-standard and WebLogic-specific deployment descriptors.
When you package a component or application, you create a directory to hold the deployment descriptors—WEB-INF or META-INF—and then create the XML deployment descriptors in that directory.
You can create the deployment descriptors manually, or you can use WebLogic-specific Java-based utilities to automatically generate them for you. For more information about generating deployment descriptors, see Automatically Generating Deployment Descriptors.
If you receive a J2EE-compliant JAR file from a developer, it already contains J2EE-defined deployment descriptors. To deploy the JAR file on WebLogic Server, you extract the contents of the JAR file into a directory, add the WebLogic-specific deployment descriptors and any generated container classes, and then create a new JAR file containing the old and new files. Note that the JAR utility contains a "u" option, which allows you to change or add files directly to an existing JAR.
Automatically Generating Deployment Descriptors
WebLogic Server includes a set of Java-based utilities that automatically generate the deployment descriptors for the following J2EE components: Web applications, Enterprise JavaBeans (version 2.0).
These utilities examine the objects you have assembled in a staging directory and build the appropriate deployment descriptors based on the servlet classes, EJB classes, and so on. The utilities generate both the standard J2EE and WebLogic-specific deployment descriptors for each component.
WebLogic Server includes the following utilities:
Note: Although DDInit attempts to create deployment descriptor files that are complete and accurate for your component or application, the utilities must guess at the value of many of the required elements. Often this guess is wrong, causing WebLogic Server to return an error when you deploy the component or application. In this case, you must undeploy the component or application, edit the deployment descriptor using the Deployment Descriptor Editor of the Administration Console, and then redeploy it. For details on using the Deployment Descriptor Editor, see Editing Deployment Descriptors.
If ejb-jar.xml exists, DDInit uses its deployment information to generate weblogic-ejb-jar.xml.
For an example of DDInit, assume that you have created a directory called c:\stage that contains the WEB-INF directory, the JSP files, and other objects that make up a Web application but you have not yet created the web.xml and weblogic.xml deployment descriptors. To automatically generate them, execute the following command:
java weblogic.marathon.DDInit.WebInit c:\stage
The utility generates the web.xml and weblogic.xml deployment descriptors and places them in the WEB-INF directory, which DDInit will create if it does not already exist.
Editing Deployment Descriptors
BEA offers two tools for editing the deployment descriptors of WebLogic Server applications and components:
Use either editor to update existing elements in, add new elements to, and delete existing elements from the following deployment descriptors:
To edit XML files, use the BEA XML Editor, an entirely Java-based XML stand-alone editor. It is a simple, user-friendly tool for creating and editing XML files. It displays XML file contents both as a hierarchical XML tree structure and as raw XML code. This dual presentation of the document gives you a choice of editing:
BEA XML Editor can validate XML code according to a specified DTD or XML schema.
For more documentation about using the BEA XML Editor and to download it, visit BEA dev2dev Online.
EJBGen is an Enterprise JavaBeans 2.0 code generator or command-line tool that uses Javadoc markup to generate EJB deployment descriptor files. You annotate your Bean class file with javadoc tags and then use EJBGen to generate the Remote and Home classes and the deployment descriptor files for an EJB application, reducing to one the number of EJB files you need to edit and maintain.
For more information about EJBGen, see "EJBGen" in Programming WebLogic Enterprise JavaBeans
Using the Administration Console Deployment Descriptor Editor
The Administration Console Deployment Descriptor Editor looks very much like the main Administration Console: the left pane lists the elements of the deployment descriptor files in tree form and the right pane contains the form for updating a particular element.
When you use the editor, you can either update the in-memory deployment descriptor only, or update both the in-memory and disk files. When you click the Apply button after updating a particular element, or the Create button to create a new element, only the deployment descriptor in WebLogic Server's memory is updated; the change has not yet been written to disk. To do this, click the Persist button. If you do not explicitly persist the changes to disk, the changes are lost when you stop and restart WebLogic Server.
Editing EJB Deployment Descriptors
This section describes the procedure for editing the following EJB deployment descriptors using the Administration Console Deployment Descriptor Editor:
For detailed information about the elements in the EJB-specific deployment descriptors, refer to Programming WebLogic Enterprise JavaBeans.
To edit the EJB deployment descriptors:
http://host:port/console
Editing Web Application Deployment Descriptors
This section describes the procedure for editing the web.xml and weblogic.xml Web application deployment descriptors using the Administration Console Deployment Descriptor Editor.
See Developing Web Applications for WebLogic Server for detailed information on the elements in the Web application deployment descriptors.
To edit the Web application deployment descriptors:
http://host:port/console
Editing Resource Adapter Deployment Descriptors
This section describes the procedure for editing the ra.xml and weblogic-ra.xml resource adapter deployment descriptors using the Administration Console Deployment Descriptor Editor.
For detailed information about the elements in the resource adapter deployment descriptors, refer to Programming WebLogic J2EE Connectors.
To edit the resource adapter deployment descriptors:
http://host:port/console
Editing Enterprise Application Deployment Descriptors
This section describes the procedure for editing the Enterprise Application deployment descriptors (application.xml and weblogic-application.xml) using the Administration Console Deployment Descriptor Editor.
Refer to application.xml Deployment Descriptor Elements in Application Deployment Descriptor Elements, for detailed information about the application.xml and weblogic-application.xml files.
Note: The following procedure describes only how to edit the application.xml and weblogic-application.xml files; to edit the deployment descriptors in the components that make up the Enterprise application, see Editing EJB Deployment Descriptors, Editing Web Application Deployment Descriptors, or Editing Resource Adapter Deployment Descriptors.
To edit the Enterprise Application deployment descriptor:
http://host:port/console
If your Web application is accessed by a programmatic Java client, see Packaging Client Applications, which describes how WebLogic server loads your application classes.
To stage and package a Web application:
On Windows NT, execute the setenv.cmd command, located in the directory server\bin\setenv.cmd, where server is the top-level directory in which WebLogic Server is installed.
On UNIX, execute the setenv.sh command, located in the directory server/bin/setenv.sh, where server is the top-level directory in which WebLogic Server is installed.
java weblogic.ant.taskdefs.war.DDInit staging-dir
where staging-dir refers to the staging directory.
For more information on the Java-based DDInit utility for generating deployment descriptors, see Automatically Generating Deployment Descriptors.
Alternatively, you can create the web.xml and weblogic.xml files manually in the WEB-INF subdirectory manually.
Note: See Developing Web Applications for WebLogic Serverfor detailed descriptions of the elements of the web.xml and weblogic.xml files.
jar cvf myapp.war -C staging-dir
The resulting WAR file can be added to an Enterprise application (EAR file) or deployed independently using the Administration Console or the weblogic.Deployer command-line utility.
Packaging Enterprise JavaBeans
You can stage one or more Enterprise JavaBeans (EJBs) in a directory and package them in an EJB JAR file. If your EJB is accessed by a programmatic Java client, see Packaging Client Applications which describes how WebLogic Server loads your EJB classes.
To stage and package an Enterprise JavaBean (EJB):
On Windows NT, execute the setenv.cmd command, located in the directory server\bin\setenv.cmd, where server is the top-level directory in which WebLogic Server is installed.
On UNIX, execute the setenv.sh command, located in the directory server/bin/setenv.sh, where server is the top-level directory in which WebLogic Server is installed and domain refers to the name of your domain.
java weblogic.ant.taskdefs.ejb11.DDInit staging-dir
where staging-dir refers to the staging directory. Use this utility for EJB 1.1.
If you are creating EJB 2.0, execute:
java weblogic.ant.taskdefs.ejb20.DDInit staging-dir
For more information on the Java-based DDInit utility for generating deployment descriptors, see Automatically Generating Deployment Descriptors.
Alternatively, you can create the EJB deployment descriptor files manually. Create an ejb-jar.xml and weblogic-ejb-jar.xml files in the META-INF subdirectory. If the bean is an entity bean with container-managed persistence, create a weblogic-rdbms-cmp-jar—bean_name.xml deployment descriptor in the META-INF directory with entries for the bean. Map the bean to this CMP deployment descriptor with a <type-storage> attribute in the weblogic-ejb-jar.xml file.
Note: See Programming WebLogic Enterprise JavaBeansfor help compiling enterprise beans and creating EJB deployment descriptors.
jar cvf jar-file.jar -C staging-dir
This command creates a JAR file that you can deploy on WebLogic Server.
The -C staging-dir option instructs the jar command to change to the staging-dir directory so that the directory paths recorded in the JAR file are relative to the directory where you staged the enterprise beans.
Enterprise beans require container classes, classes the WebLogic EJB compiler generates to allow the bean to deploy in a WebLogic Server. The WebLogic EJB compiler reads the deployment descriptors in the EJB JAR file to determine how to generate the classes. You can run the WebLogic EJB compiler on the JAR file before you deploy the beans, or you can let WebLogic Server run the compiler for you at deployment time. See Programming WebLogic Enterprise JavaBeans for help with the WebLogic EJB compiler.
WebLogic Server supports the use of ejb-client.jar files. Create an ejb-client.jar file by specifying this feature in the bean's ejb-jar.xml deployment descriptor file and then generating the ejb-client.jar file using weblogic.ejbc. An ejb-client.jar contains the class files that a client program needs to call the EJBs contained in the ejb-jar file. The files are the classes required to compile the client. If you specify this feature, WebLogic Server automatically creates the ejb-client.jar.
For more information, refer to "Packaging EJBs for the WebLogic Server Container" in Programming WebLogic Enterprise JavaBeans
After you stage one or more resource adapters in a directory, you package them in a Java Archive (JAR). Before you package your resource adapters, be sure you read and understand the chapter entitled "WebLogic Server Application Classloading" in this guide, which describes how WebLogic Server loads classes.
To stage and package a resource adapter:
Note: Refer to the following Sun Microsystems documentation for information on the ra.xml document type definition at: http://java.sun.com/dtd/connector_1_0.dtd
Note: Refer to Programming WebLogic Server J2EE Connectors for information on the weblogic-ra.xml document type definition.
jar cvf jar-file.rar -C staging-dir
This command creates a RAR that you can deploy on a WebLogic Server or package in an enterprise application archive (EAR).
The -C staging-dir option instructs the JAR command to change to the staging-dir directory so that the directory paths recorded in the JAR are relative to the directory where you staged the resource adapters.
Packaging Enterprise Applications
An Enterprise archive contains EJB and Web modules that are part of a related application. The EJB and Web modules are bundled together, along with the Enterprise Application deployment descriptor files, in another JAR file with an EAR extension.
Enterprise Applications Deployment Descriptor Files
The META-INF subdirectory in an EAR file contains an application.xml deployment descriptor provided by the application assembler; the format definition of this deployment descriptor is provided by Sun Microsystems. The application.xml deployment descriptor identifies the modules packaged in the EAR file.
You can find the DTD for the application.xml file at http://java.sun.com/j2ee/dtds/application_1_2.dtd.
Within application.xml, you define items such as the modules that make up your application and the security roles used within your application. The following is the application.xml file from the Pet Store example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD
J2EE Application 1.2//EN'
'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>
<application>
<display-name>estore</display-name>
<description>Application description</description>
<module>
<web>
<web-uri>petStore.war</web-uri>
<context-root>estore</context-root>
</web>
</module>
<module>
<ejb>petStore_EJB.jar</ejb>
</module>
<security-role>
<description>the gold customer role</description>
<role-name>gold_customer</role-name>
</security-role>
<security-role>
<description>the customer role</description>
<role-name>customer</role-name>
</security-role>
</application>
A supplemental deployment descriptor, weblogic-application.xml contains additional WebLogic-specific deployment information. This deployment descriptor is optional and is only needed if you want to configure application scoping.
Application scoping refers to configuring resources for a particular enterprise application rather than for an entire WebLogic Server configuration. Examples of resources include the XML parser used by an application, the EJB entity cache, the JDBC connection pool, and so on. The main advantage of application scoping is that it isolates the resources for a given application to the application itself.
Another advantage of using application scoping is that by associating the resources with the EAR file, you can run this EAR file on another instance of WebLogic Server without having to configure the resources for that server.
Refer to weblogic-application.xml Deployment Descriptor Elements in Application Deployment Descriptor Elements, for weblogic-application.xml deployment descriptor elements.
Packaging Enterprise Applications: Main Steps
If your enterprise application is accessed by a programmatic Java client, see Packaging Client Applications, which describes how WebLogic Server loads your enterprise application classes.
To stage and package an Enterprise application:
On Windows NT, execute the setenv.cmd command, located in the directory server\bin\setenv.cmd, where server is the top-level directory in which WebLogic Server is installed.
On UNIX, execute the setenv.sh command, located in the directory server/bin/setenv.sh, where server is the directory in which WebLogic Server is installed.
java weblogic.ant.taskdefs.ear.DDInit staging-dir
where staging-dir refers to the staging directory.
For more information on the Java-based DDInit utility for generating deployment descriptors, see Automatically Generating Deployment Descriptors.
Alternatively, you can create the application.xml file automatically in the META-INF directory. See Application Deployment Descriptor Elements, for detailed information about the elements in this file.
jar cvf application.ear -C staging-dir
Although not required for WebLogic Server applications, J2EE includes a standard for deploying client applications. A J2EE client application module is packaged in a JAR file. This JAR file contains the Java classes that execute in the client JVM (Java Virtual Machine) and deployment descriptors that describe EJBs (Enterprise JavaBeans) and other WebLogic Server resources used by the client.
A de-facto standard deployment descriptor application-client.xml from Sun is used for J2EE clients and a supplemental deployment descriptor contains additional WebLogic-specific deployment information.
Note: See application-client.xml Deployment Descriptor Elements in Client Application Deployment Descriptor Elements, for help with these deployment descriptors.
Executing a Client Application in an EAR File
In order to simplify distribution of an application, J2EE defines a way to include client-side components in an EAR file, along with the server-side modules that are used by WebLogic Server. This enables both the server-side and client-side components to be distributed as a single unit.
The client JVM must be able to locate the Java classes you create for your application and any Java classes your application depends upon, including WebLogic Server classes. You stage a client application by copying all of the required files on the client into a directory and bundling the directory in a JAR file. The top level of the client application directory can have a batch file or script to start the application. Create a classes subdirectory to hold Java classes and JAR files, and add them to the client Class-Path in the startup script. You may also want to package a Java Runtime Environment (JRE) with a Java client application.
Note: The use of the Class-Path manifest entries in client component JARs is not portable, because it has not yet been addressed by the J2EE standard.
The Main-Class attribute of the JAR file manifest defines the main class for the client application. The client typically uses java:/comp/env JNDI lookups to execute the Main-Class attribute. As a deployer, you must provide runtime values for the JNDI lookup entries and populate the component local JNDI tree before calling the client's Main-Class attribute. You define JNDI lookup entries in the client deployment descriptor. (Refer to Client Application Deployment Descriptor Elements.)
You use weblogic.ClientDeployer to extract the client-side JAR file from a J2EE EAR file, creating a deployable JAR file. The weblogic.ClientDeployer class is executed on the Java command line with the following syntax:
java weblogic.ClientDeployer ear-file client
The ear-file argument is an expanded directory (or Java archive file with a .ear extension) that contains one or more client application JAR files.
Once the client-side JAR file is extracted from the EAR file, use the weblogic.j2eeclient.Main utility to bootstrap the client-side application and point it to a WebLogic Server instance as follows:
Special Considerations for Deploying J2EE Client Applications
The following is a list of special considerations for deploying J2EE client applications:
Note: To run the J2EE client application using weblogic.ClientDeployer, you need the weblogic.j2eeclient.Main class (located in the weblogic.jar file).
ejb-ref
javax.jms.QueueConnectionFactory
javax.jms.TopicConnectionFactory
javax.mail.Session
javax.sql.DataSource
Note: For more information on deploying, refer to Deploying WebLogic Server Applications.
Packaging J2EE Applications Using Apache Ant
The topics in this section discuss building and packaging J2EE applications using Apache Ant, an extensible Java-based tool. Ant is similar to the make command but is designed for building Java applications. Ant libraries are bundled with WebLogic Server to make it easier for our customers to build Java applications out of the box.
Developers write Ant build scripts using eXtensible Markup Language (XML). XML tags define the targets to build, dependencies among targets, and tasks to execute in order to build the targets.
For a complete explanation of ant capabilities, see: http://jakarta.apache.org/ant/manual/index.html
Packaging J2EE Deployment Units
As previously discussed, J2EE applications are packaged as JAR files containing a specific file extension depending on the component type:
These components are structured according to the J2EE specifications. In addition to the standard XML deployment descriptors, components may also be packaged with WebLogic Server-specific XML deployment descriptors.
Ant provides tasks that make the construction of these JAR files easier. In addition to the features of the JAR command, Ant provides specific tasks for building EAR and WAR files. Using Ant, you can specify the pathname as it appears in the JAR archive, which may differ from the original path in the file system. This ability is useful for packaging deployment descriptors (in which J2EE specifies an exact location in the archive), which may not correspond to the location in your source tree. See the Apache Ant online documentation pertaining to the ZipFileSet command for related information.
<war warfile="cookie.war" webxml="web.xml" manifest="manifest.txt">
<zipfileset dir="." prefix="WEB-INF" includes="weblogic.xml"/>
<zipfileset dir="." prefix="images" includes="*.gif,*.jpg"/>
<classes dir="classes" includes="**/CookieCounter.class"/>
<fileset dir="." includes="*.jsp,*.html">
</fileset>
</war>
Packaging J2EE deployment units requires the following steps:
You can achieve the same result by staging the files in a directory that directly corresponds to the structure of the WAR file and creating a JAR file from that directory. Using special features of the Ant JAR tasks eliminates the need to copy files into a specific directory hierarchy.
The following example builds a Web application and an EJB, and then packages them together in an EAR file:
<project name="app" default="app.ear">
<property name="wlhome" value="/bea/wlserver6.1"/>
<property name="srcdir" value="/bea/myproject/src"/>
<property name="appdir" value="/bea/myproject/config/mydomain/applications"/>
<target name="timer.war">
<mkdir dir="classes"/>
<javac srcdir="${srcdir}" destdir="classes" includes="myapp/j2ee/timer/*.java"/>
<war warfile="timer.war" webxml="timer/web.xml" manifest="timer/manifest.txt">
<classes dir="classes" includes="**/TimerServlet.class"/>
</war>
</target>
<target name="trader.jar">
<mkdir dir="classes"/>
<javac srcdir="${srcdir}" destdir="classes" includes="myapp/j2ee/trader/*.java"/>
<jar jarfile="trader0.jar" manifest="trader/manifest.txt">
<zipfileset dir="trader" prefix="META-INF" includes="*ejb-jar.xml"/>
<fileset dir="classes" includes="**/Trade*.class"/>
</jar>
<ejbc source="trader0.jar" target="trader.jar"/>
</target>
<target name="app.ear" depends="trader.jar, timer.war">
<jar jarfile="app.ear">
<zipfileset dir="." prefix="META-INF" includes="application.xml"/>
<fileset dir="." includes="trader.jar, timer.war"/>
</jar>
</target>
<target name="deploy" depends="app.ear">
<copy file="app.ear" todir="${appdir}/>
</target>
</project>
BEA provides a simple script to run Ant in the server/bin directory. By default, Ant loads the build.xml build file, but you can override this using the -f flag. Use the following command to build and deploy an application using the build script shown above:
![]() |
![]() |
![]() |
![]() |
||
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |