Creating WebLogic Server Applications
Contents
Best Practices
Package Applications as Part of an Enterprise Application
For both production and development purposes, BEA recommends that you package and deploy the stand-alone Web applications, EJBs, and resource adapters as part of an Enterprise application.
This practice allows for easier application migration, additions, and changes. For example, to add more than one Web application, EJB, or resource adapter module to an application, package the modules in an Enterprise application. Packaging and deploying stand-alone applications in an Enterprise application from the start saves you a lot of time. It also allows you to take advantage of the split development directory structure, which provides a number of benefits over the traditional single directory structure.
Exploded (Unarchived) Directory
For development and production purposes, it is convenient to deploy Enterprise applications in exploded (unarchived) directory format. This applies also to stand-alone Web applications, EJBs, and connectors packaged as part of an Enterprise application. Using this format allows you to update files directly in the exploded directory rather than having to unarchive, edit, and rearchive the whole application.
You can convert split development directory Enterprise applications to exploded EARs using the wlpackage Ant task.
Archived File (Using the jar Utility)
For production purposes, you can also package applications in an archived file using the Java jar utility. An archived file created using the jar utility bundles the files in a directory into a single Java ARchive (JAR) file, maintaining the directory structure. JAR files are convenient for packaging modules 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.
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 modules on WebLogic Server in either a JAR (archived) file or an exploded (unarchived) directory.
WebLogic Server requires you to adhere to the following programmatic naming conventions for application archive files:
- Enterprise JavaBean JAR archived files must end with the .jar extension.
- Resource adapter RAR archived files must end with the .rar extension.
- Web application WAR archived files end with the .war extension.
- Enterprise application EAR archived files end with the .ear extension.
Split Development Directory Structure
In a development environment, BEA recommends that you use the new WebLogic split development directory structure to build WebLogic Server applications. The split development directory structure is compatible with Enterprise applications only. BEA therefore recommends that you package stand-alone Web applications, EJBs, and connectors as part of an Enterprise application so that you can take advantage of this structure.
This structure is optimized for iterative development on a single WebLogic Server instance. Rather than having a single archived EAR file or an exploded Enterprise application directory structure, the split development directory structure provides two parallel directories. The source directory contains all of the source files (such as Java files, descriptors, JSP files, HTML, and so on) in a traditional EAR-like directory structure. All of the generated or compiled classes are stored in a separate output directory.
The split development directory structure provides several important benefits over the traditional structure:
- You no longer have to copy over large quantities of files (deployment descriptors, JSP files, image files, and so on) from the source file into the output directory where you have compiled the Java files.
- You can make changes to files and redeploy them in place without having to rebuild the application. Using the traditional JAR-centric directory structure, when you copy files into the output directory, you are unable to edit them there and have the server automatically detect these changes. This is not an issue with the split development directory structure.
- You have clean separation between source and output files. This allows for cleaning the build by just removing the output directory.
Using the split development directory structure, you specify the output directory when deploying the application to WebLogic Server. WebLogic Server automatically recognizes the deployment as a split development directory structure and uses information in the output directory to locate the source directory. WebLogic Server views the application as a union of the source and output directories. When it searches for a resource or class, it first checks the source directory. If it does not locate the class or resource, it then checks the output directory.
The split development directory structure is accompanied in WebLogic Server by a set of Ant tasks for building, packaging, and deploying applications as traditional, exploded EAR files for production use.
Example Split Development Directory
The following is a working example of a split development directory structure, taken from the BEA MedRec sample found at...
$WL_HOME/weblogic81/samples/server/medrec/
...that illustrates the medrec/ Enterprise application in a split development directory structure. It illustrates the source (src/) and output (build/) directories of the split development directory structure for an EJB (webServicesEJB/) and a Web application (patientWebApp/). Enterprise application descriptors are contained in the META-INF/ directory.
medrec/src/medrecEar/META-INF/application.xml medrec/src/medrecEar/META-INF/weblogic-application.xml medrec/src/medrecEar/webServicesEjb/META-INF/ejb-jar.xml medrec/src/medrecEar/webServicesEjb/META-INF/weblogic-ejb-jar.xml medrec/src/medrecEar/webServicesEjb/com/bea/medrec/webservices/MedRecWebServicesEJB.java medrec/src/medrecEar/webServicesEjb/com/bea/medrec/webservices/MedRecWebServicesHome.java medrec/src/medrecEar/webServicesEjb/com/bea/medrec/webservices/MedRecWebServicesEJB.java medrec/src/medrecEar/webServicesEjb/com/bea/medrec/webservices/... medrec/src/medrecEar/patientWebApp/WEB-INF/web.xml medrec/src/medrecEar/patientWebApp/WEB-INF/weblogic.xml medrec/src/medrecEar/patientWebApp/WEB-INF/classes... medrec/src/medrecEar/patientWebApp/WEB-INF/src... medrec/src/medrecEar/patientWebApp/*.jsp medrec/src/medrecEar/patientWebApp/images/*.gif medrec/build/medrecEar/webServicesEjb/com/bea/medrec/webservices/*.class medrec/build/medrecEAR/patientWebApp/WEB-INF/classes/... medrec/build/medrecEAR/patientWebApp/WEB-INF/lib/...
JAR Files and Java Utility Classes
Extend the Enterprise application to use third-party .jar files by placing them in...
APP-INF/lib/
Third-party JARs usually own their own code and are not recompiled. For example, XML parsers, logging implementations, and other utility JAR files are common.
You can also extend the Enterprise application to use Java utility classes. Java utility classes differ from third-party JARs in that the source files are part of the application and must be compiled. Java utility classes are typically libraries used by application modules such as EJBs or Web applications. The wlcompile Ant task invokes the javac compiler and compiles Java components into...
APP-INF/classes/build
The following classes are available throughout the application.
APP-INF/lib/exceptions.jar Shared MedRec exceptions APP-INF/lib/utils.jar Shared utilities APP-INF/lib/values.jar Shared value objects APP-INF/lib/log4j-1.2.4.jar Shared third-party JAR APP-INF/classes/com/bea/medrec/... Java utility classes
Split Development Directory Ant Tasks
The split development directory structure is an iterative process in that you can continue to build upon the existing application by using the following WebLogic Server Ant tasks:
wlcompile Invokes the javac compiler and compiles Java components into... APP-INF/classes/buildwlpackage Packages a split development directory application as a traditional, exploded EAR file. wldeploy Deploys any format of J2EE applications (exploded or archived) to WebLogic Server. wlappc Invokes the appc compiler, which generates JSPs and container-specific EJB classes for deployment.
wlcompile
Use the wlcompile Ant task to invoke the javac compiler to compile the application's Java components in a split development directory structure.
The following is the order in which events occur using this task:
- wlcompile compiles the Java components into an output directory:
/medrec/build/medrecEAR/APP-INF/classes/
- wlcompile builds the EJBs and automatically includes the previously built Java modules in the compiler's classpath. This allows the EJBs to call the Java modules without requiring you to manually edit their classpath.
- Finally, wlcompile compiles the Java components in the Web application with the EJB and Java modules in the compiler's classpath. This allows the Web applications to refer to the EJB and application Java classes without requiring you to manually edit the classpath.
The following is an example based upon the MedRec application. Source files located in...
$WL_HOME/weblogic81/samples/medrec/src/physicianEAR
...are compiled to the output directory...
$WL_HOME/weblogic81/samples/server/medrec/build/physicianEAR...
...as follows...
<wlcompile srcdir="/src/physicianEAR" destdir="/build/physicianEAR" />
Using includes and excludes Properties
The includes and excludes options accept the names of subdirectories in the Enterprise application source directory to include or exclude them from the compile stage.
<wlcompile srcdir="${medrec.ear.src.dir}"
destdir="${dest.dir}"
excludes="adminWebApp, xml, mdbEjbs, webServicesEjb"/>
<wlcompile srcdir="${medrec.ear.src.dir}"
destdir="${dest.dir}"
includes="xml, webServicesEjb"
wlcompile Ant Task Options
Option Description srcdir Source directory. destdir Build/output directory. classpath Change the classpath used by wlcompile. includes Include specific directories from the build. excludes Exclude specific directories from the build.
Nested javac Options
The wlcompile Ant task can accept nested javac options for more flexibility.
wlpackage
In a production environment, use the wlpackage Ant task to package the split development directory application as a traditional EAR file that can be deployed to WebLogic Server. Continuing with the MedRec example, you would package the application as follows:
<wlpackage toFile="/physicianEAR/physicianEAR.ear"
srcdir="/physicianEAR"
destdir="/build/physicianEAR"/>
<wlpackage toDir="/physicianEAR/explodedphysicianEar"
srcdir="/src/physicianEAR"
Creating the build.xml File
Once you have set up the directory structure, you create the build.xml file using the weblogic.BuildXMLGen utility.
weblogic.BuildXMLGen
weblogic.BuildXMLGen generates an Ant build.xml file in the split development directory structure. This utility analyzes the source (src/) directory and creates build and deploy targets for the Enterprise application as well as individual modules. It also creates targets to clean the build and generate new deployment descriptors.
After running weblogic.BuildXMLGen, you can use -projecthelp to view more information on the generated targets:
The syntax for weblogic.BuildXMLGen is...
java weblogic.BuildXMLGen [options] source directory
...where options include...
-help Print standard usage message -version Print version information -projectName project name Name of the Ant project -d directory Directory where build.xml is created. The default is the current directory. -file build.xml Name of the generated build file -username username User name for deploy commands -password password User password
wlddcreate Ant Task
The wlddcreate ant task is provided as a method for generating deployment descriptors for applications and application modules. It is an ant target provided as part of the generated build.xml file. It is an alternative to the weblogic.marathon.ddinit commands. The following is the wlddcreate target output:
<target name="descriptors"
depends="compile"
description="Generates application and module descriptors">
<ddcreate dir="${dest.dir}" />
</target>
Example MedRec build.xml File
The following is a build.xml file for our example medrec/ Enterprise application. It contains the following three targets (or actions):
build Calls wlcompile (which invokes the javac compiler) and compiles the application. package Takes the build output and generates a traditional exploded EAR. clean Deletes the output (build/) directory.
Note that each Ant build.xml can have multiple targets, which are basically actions. The above targets (actions) build, package, and clean the application. You specify the target as: ant <target>
<project name="medrec ear"
default="build">
<!-- Source directory from which a WLS-formatted EAR is formed-->
<property name="medrec.ear.src.dir"
value="." />
<!-- Build directory for the WLS-formatted EAR-->
<property name="dest.dir"
value="${medrec.ear.wlcompile.build.dir}" />
<!-- Archived, J2EE-formatted EAR, combining the -->
<!-- build and src elements of the medrec EAR -->
<property name="ear.file"
value="${medrec.ear.file}" />
<!-- Exploded J2EE-formatted EAR, combining the -->
<!-- build and src elements of the medrec ear -->
<property name="ear.exploded.dir"
value="${medrec.ear.exploded.dir}" />
<!-- Build split development directory modules -->
<target name="build.split.dir" depends="banner,prepare">
<!-- build worker modules-->
<wlcompile srcdir="${medrec.ear.src.dir}"
destdir="${dest.dir}"
excludes="adminWebApp, xml, mdbEjbs, webServicesEjb"/>
<!-- build dependent modules -->
<wlcompile srcdir="${medrec.ear.src.dir}"
destdir="${dest.dir}"
includes="xml, webServicesEjb"
classpath="${java.class.path};${dest.dir}/sessionEjbs"/>
<!-- build more dependent modules -->
<wlcompile srcdir="${medrec.ear.src.dir}" destdir="${dest.dir}" includes="mdbEjbs, adminWebApp"/>
</target>
<!-- Package the application as J2EE-formatted archived .ear -->
<target name="ear">
<wlpackage srcdir="${medrec.ear.src.dir}"
destdir="${dest.dir}"
toFile="${ear.file}"/>
</target>
<target name="clean.exploded.ear">
<delete dir="${ear.exploded.dir}"/>
</target>
</project>
Using the Split Development Directory Structure: Main Steps
The following example illustrates how you use the split development directory structure to build a WebLogic Server application (in this case, a Web application) and package and deploy it as part of an Enterprise application (EAR file).
Directory Structure
medrec/src/medrecEar/ META-INF/ application.xml weblogic-aplication.xml APP-INF/ lib/ classes/ myWebApp/ images/ WEB-INF/ web.xml weblogic.xml lib/ classes/ index.html index.jsp medrec/build/medrecEar/ META-INF/ APP-INF/ classes/ lib/ myWebApp/ images/ WEB-INF/ web.xml weblogic.xml lib/ classes/
Step One: Create the Enterprise Application Wrapper
- Create a directory for the root EAR file:
/src/myEAR/
- Set the environment...
- On Windows NT, execute the setWLSEnv.cmd command, located in the directory server/bin/, where server is the top-level directory in which WebLogic Server is installed.
- On UNIX, execute the setWLSEnv.sh command, located in the directory server/bin/, where server is the top-level directory in which WebLogic Server is installed and domain refers to the name of the domain.
- Package the Enterprise application in the /src/myEAR/ directory...
- Place application.xml and weblogic-application.xml in the META-INF/ directory.
You can automatically generate the Enterprise application descriptors using the DDInit Java utility by executing the following command:
- Edit the deployment descriptors as needed.
- Place the Enterprise application .jar files in:
/src/myEAR/APP-INF/lib/
- Place application.xml and weblogic-application.xml in the META-INF/ directory.
Step Two: Create the Web Application
- Create a directory for the Web application in the the root of the EAR file:
/src/myEAR/myWebApp
- Package the Web application in the /src/myEAR/myWebApp/ directory...
- Place web.xml and weblogic.xml in...
/src/myEAR/myWebApp/WEB-INF/
You can automatically generate the Web application descriptors using the DDInit utility by executing the following command:
- Edit the deployment descriptors as needed
- Place all HTML files, JSPs, images and any other files referenced by the Web application pages in the root of the Web application:
/src/myEAR/myWebApp/images/myimage.jpg
/src/myEAR/myWebApp/login.jsp
/src/myEAR/myWebApp/index.html - Place the Web application Java source files (servlets, tag libs, other classes referenced by servlets or tag libs) in:
/src/myEAR/myWebApp/WEB-INF/src/
- Place web.xml and weblogic.xml in...
Step Three: Creating the build.xml File
Once you have set up the directory structure, create build.xml using weblogic.BuildXMLGen...
Step Four: Execute the Split Development Directory Structure Ant Tasks
- Execute the wlcompile Ant task to invoke the javac compiler. This compiles the Web application Java components into an output directory:
/build/myEAR/WEB-INF/classes/
- Execute wlappc Ant task to invoke the appc compiler. This compiles any JSPs and container-specific EJB classes for deployment.
- Execute the wldeploy Ant task to deploy the Web application as part of an archived or exploded EAR to WebLogic Server.
- If this is a production environment, execute the wlpackage Ant task to package the Web application as part of an archived or exploded EAR. This places compiled versions of the Java source files in the build directory. For example:
/build/myEAR/myWebApp/classes
About Client Applications
J2EE specifies a standard for including client application code (a client module) in an EAR file. This allows the client side of an application to be packaged along with the other modules that make up the application.
The client module is declared in META-INF/application.xml using a <java> tag.
The <java> tag is often confused to be a declaration of Java code that can be used by the server-side modules. This is not its purpose however. It is used to declare client-side code that runs outside of the server-side container.
A client module is basically a JAR file containing a special deployment descriptor named...
META-INF/application-client.xml
This client JAR file also contains a Main-Class entry in its META-INF/MANIFEST.MF file to specify the entry point for the program.
Extracting a Client Application
WebLogic Server includes two utilities that facilitate the use of client modules. They are:
weblogic.ClientDeployer Extract the client module from the EAR and prepare it for execution. weblogic.j2eeclient.Main Execute the client code.
Use the weblogic.ClientDeployer utility to extract the client-side JAR file from a J2EE EAR file, creating a deployable JAR file. Execute the weblogic.ClientDeployer class on the Java command line using the following syntax:
java weblogic.ClientDeployer ear-file client1 [client2 client3 ...]
The ear-file argument is a Java archive file with an .ear extension or an expanded directory that contains one or more client application JAR files.
The client arguments specify the clients you want to extract. For each client you name, the weblogic.ClientDeployer utility searches for a JAR file within the EAR file that has the specified name containing the .jar extension.
For example, consider the following command:
java weblogic.ClientDeployer app.ear myclient
This command extracts myclient.jar from app.ear. As it extracts, the weblogic.ClientDeployer utility performs two other operations.
- It ensures that the JAR file includes a META-INF/application-client.xml file. If it does not, an exception is thrown.
- It reads from a file named myclient.runtime.xml and creates a client.properties file in the extracted JAR file. This is used by the weblogic.j2eeclient.Main utility to initialize the client application's component environment (java:comp/env).
Note: You create the <client>.runtime.xml descriptor for the client program to define bindings for entries in the module's META-INF/application-client.xml deployment descriptor.
Executing a Client Application
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 using the following command:
java weblogic.j2eeclient.Main clientjar URL [application args]
For example:
java weblogic.j2eeclient.Main myclient.jar t3://localhost:7001
The weblogic.j2eeclient.Main utility creates a component environment that is accessible from java:comp/env in the client code.
If a resource mentioned by the application-client.xml descriptor is one of the following types, the weblogic.j2eeclient.Main class attempts to bind it from the global JNDI tree on the server to java:comp/env using the information specified earlier in the myclient.runtime.xml file.
- ejb-ref
- javax.jms.QueueConnectionFactory
- javax.jms.TopicConnectionFactory
- javax.mail.Session
- javax.sql.DataSource
The user transaction is bound into java:comp/UserTransaction.
The <res-auth> tag in the application.xml deployment descriptor is currently ignored and should be entered as application. BEA does not currently support form-based authentication.
The rest of the client environment is bound from the client.properties file created by the weblogic.ClientDeployer utility.
The weblogic.j2eeclient.Main class emits error messages for missing or incomplete bindings.
Once the environment is initialized, the weblogic.j2eeclient.Main utility searches the JAR manifest of the client JAR for a Main-Class entry. The main method on this class is invoked to start the client program. Any arguments passed to the weblogic.j2eeclient.Main utility after the URL argument is passed on to the client application.
The client JVM must be able to locate the Java classes you create for the application and any Java classes the 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 that the use of the Class-Path manifest entries in client module JARs is not portable, as it has not yet been addressed by the J2EE standard.
|
|
|