In This Chapter
This section introduces a much overlooked and frequently misunderstood topic on how WebLogic Server uses Java ClassLoaders to load system resources and, most importantly, your application resource files. Understanding the role that WebLogic Server ClassLoaders play in the course of deploying your J2EE applications to WebLogic Server enables you to not only package your J2EE application classes correctly, but also to leverage WebLogic Server’s capability to provide such features as application partitioning, dynamic redeployment, and undeployment.
A ClassLoader is a Java class that’s responsible for locating and loading system and application Java classes into the Java Virtual Machine (JVM) as they’re required at runtime. Loading a class represents reading the bytecode implementation of the class and loading it into the JVM runtime. Multiple ClassLoaders are associated with a JVM, with each ClassLoader assigned to a classpath that serves as the search path for locating and loading the required classes into memory.
The ClassLoaders provided with a JVM runtime are known as System ClassLoaders, and are typically arranged in a parent-child hierarchy. For example, when you start the JVM in Java Development Kit (JDK) 1.3, three System ClassLoaders are created by default with the following hierarchy:
At the very top of the hierarchy is the bootstrap ClassLoader, which is created by the JVM and loads all the JDK internal classes including classes of the core API, such as
java.lang,java.io, and so on.The bootstrap ClassLoader is a parent to the extensions ClassLoader, which loads classes in the extension directory of the JDK, as defined by the value of the
java.ext.dirsJava system property. The classes in the extension directory are used to extend the functionality of the core platform and include both native code libraries and Java classes.The extensions ClassLoader is a parent to the system classpath ClassLoader, which loads the classes from the classpath specified by the JVM via the
CLASSPATHenvironment variable or the-classpathJava option.
Note
Application-specific ClassLoaders, which are discussed in the next section, are children to the system ClassLoader.
To load a class, ClassLoaders use a delegation model. For example, if a ClassLoader is requested to load a class, the ClassLoader implementation first verifies whether a specific class has already been loaded in memory instead of always reading the class from its classpath. If the class is not found in memory, the parent ClassLoader is typically requested to fulfill the request. The parent ClassLoader in turn asks its parent to fulfill the request. This goes upward until the request reaches the top of the hierarchy. If the topmost ClassLoader cannot fulfill the request, the request for loading the class traverses down the hierarchy to the initial ClassLoader that made the request. If this ClassLoader cannot fulfill the request to load the class, the ClassLoader throws a ClassNotFoundException. Also, if a class exists in both the parent and child ClassLoaders, the parent version is loaded.
Note
Depending on the ClassLoader implementation, a ClassLoader might attempt to resolve a class by checking its parent before or after checking itself.
The relationship among ClassLoaders signifies that classes loaded by a particular ClassLoader can reference other classes only as long as those other classes can be loaded by the same ClassLoader or any of its ancestors. For this reason, a ClassLoader has no visibility into classes loaded by its children or sibling ClassLoaders. A class of a specific type can be loaded by two sibling ClassLoaders. However, in that case, each ClassLoader has its own version of the class that will not be type-compatible with the other.
WebLogic Server provides application ClassLoaders to load classes in your applications including servlets, Enterprise JavaBeans, JavaServer Pages (JSP) files, JavaBeans, and other supporting class libraries. They also enable WebLogic Server to provide such features as application partitioning, hot deployment, hot redeployment, and hot undeployment of applications.
Classloading in the context of WebLogic Server is centered on the concept of an application. For this reason, before discussing the topic of classloading specific to WebLogic Server, it’s essential that you understand what WebLogic Server considers to be an application.
An application in WebLogic Server can consist of any of the following components:
Web Applications: JSPs, servlets, HTML pages, images, and related files. These files are packaged into a JAR file with a
.warextension.Enterprise JavaBeans: Entity, session, and message-driven beans. These are packaged into a JAR file with a
.jarextension.Connector Archives: Connector components. These are packaged into a JAR file with a
.rarextension.Enterprise Archives: All or any of the preceding three components are packaged into a JAR file with an
.earextension.
Each of these packaged components also contains XML deployment descriptors, which instruct the hosting Web or EJB container of WebLogic Server on how to deploy the respective applications. The packaging of applications and deployment descriptor specifics are discussed in detail in the “Packaging Applications Targeted for WebLogic Server” section.
With this brief overview on the types of WebLogic Server applications, we can now look at the classloading mechanism used by WebLogic Server to load these applications.
The Java ClassLoaders that are part of the JDK do not have any standard mechanism for undeploying or unloading a set of classes, or even for loading new versions of classes. A technique that all application servers use to get around this constraint is to create an application-specific ClassLoader as a child of the system classpath ClassLoader. Hence, when an application is deployed to WebLogic Server, the server creates a set of ClassLoaders to load that specific application. These ClassLoaders are arranged in a hierarchical fashion, and every application receives its own ClassLoader hierarchy. Because these application ClassLoaders can see only their parent ClassLoader (system classpath), WebLogic Server is able to host multiple isolated applications within the same JVM.
Note
If a class is in the system classpath, it cannot be modified in any way while WebLogic Server is running.
When an enterprise (EAR) application is deployed to WebLogic Server, it automatically creates two new ClassLoaders: one for EJBs and one for Web applications. The EJB ClassLoader, also known as the base ClassLoader, is a child of the system ClassLoader and the Web application ClassLoader is a child of the base ClassLoader.
The base application ClassLoader is created by WebLogic Server to load all the classes in the EJB JAR files contained in the application archive file (.ear). According to the Servlet specification, Web applications must be loaded on their own ClassLoader, which allows each Web application to have its own classpath and also guarantees that there will be no class name conflicts between the Web applications. For this reason, the JSPs and servlets from the Web application WAR file are loaded by the Web application ClassLoader.
Because JSPs and servlets typically make use of the EJB interfaces, rather than vice versa, this arrangement allows the JSPs and servlets to find the EJB interfaces as they’re loaded by the parent ClassLoader. This application ClassLoader hierarchy makes it easier to redeploy the JSPs and servlets (Web tier) classes without redeploying the EJB JAR file (EJB tier). During the development phase, changes in the Web tier are generally more common than changes to the EJB tier.
To illustrate this classloading hierarchy, suppose that an EAR file called application1.ear is deployed to WebLogic Server. This application1.ear contains an EJB in a JAR file: ejb1.jar. The EAR also contains a Web application, webApp1.war, which has JSPs and servlets that call the EJB remote methods. The classloading hierarchy for this EAR is shown in Figure 27.1.
Now, if you have two applications, application1.ear and application2.ear, the classloading hierarchy would be as shown in Figure 27.2.
Figure 27.2. A classloading hierarchy for two J2EE applications—application1.ear and application2.ear.
In this hierarchy, the application ClassLoaders for application1.ear and application2.ear are children to the system ClassLoader and are therefore siblings of each other. So, if JSPs and servlets within webapp2.war were to call remote methods of an EJB in EJB1.jar, you would be required to package the home and remote interfaces of that EJB within the webapp2.war file. This is because classes have visibility into only their parent ClassLoader, not their children or sibling ClassLoaders.
If you deploy the WAR and JAR files separately, WebLogic Server creates sibling ClassLoaders for them, respectively. The Web Application ClassLoader loads classes from the WEB-INFlib and WEB-INFclasses directories of the Web application. The servlets and JSPs are loaded in their own ClassLoaders, which are children to the parent Web application ClassLoader. This allows WebLogic Server to reload the JSPs and servlets individually, instead of reloading the entire Web application.
WebLogic Server provides a parameter named PreferWebInfClasses that enables you to override the default classloading behavior with respect to Web applications. By default, this parameter is set to false, which implies that a class loaded by the system or the application ClassLoader will have preference over one loaded by the WebApplication ClassLoader. This is consistent with the ClassLoader hierarchy explained previously. However, some users might want to override this behavior; for example, while loading XML parser classes in their Web applications.
In these cases, setting the PreferWebInfClasses parameter to true loads the classes located in the WEB-INFclasses directory in preference to the ones loaded by the WebApplication’s parent ClassLoaders. Because this element is part of the WebAppComponentMBean, you can set its value for a Web application through the Administration Console. However, you should be careful while casting these classes, because it’s generally not a good idea to excessively mix instances of classes loaded from different ClassLoaders.
The two common parameter-passing models in Java are pass by value and pass by reference. In the pass by value model, the parameters and the return values are copied for each method call. In the pass by reference model, the actual reference or the pointer to the object is passed when a method is called. The called method operates on the reference and therefore modifies the actual object. Because no copying of parameters is involved, the pass by reference model is more performance-based than the pass by value model.
WebLogic Server uses this efficient call by reference parameter-passing model to optimize performance when the caller to a method and the method being called are in the same application. For example, when a JSP/servlet class calls a remote method on an EJB within the same application, WebLogic Server uses the call by reference model.
By default, when the caller and the method being called are in different JVMs, or even in different applications in the same JVM, WebLogic Server uses the pass by value mechanism, which involves RMI marshalling and unmarshalling.
Keeping this optimization in mind, it’s always a good practice to package the WAR and JAR files together into an EAR file—that is, package them into one application. This has two advantages:
As explained earlier, a ClassLoader hierarchy is created such that the JSPs and servlets from the Web application can find the EJB remote interfaces (loaded in the application ClassLoader). This prohibits the need to copy and package the EJB’s home and remote interfaces within the WAR file.
When the WAR file and the EJB JAR file it calls into are in the same application, WebLogic Server can make use of the call by reference optimization.
In practice, J2EE applications make use of utility classes and third-party packages. There are some best practices you can follow while packaging these applications so that the applications are partitioned well and can be redeployed without dependencies:
If you have to use utility classes that you would need in several applications in WebLogic Server, you must package them as a JAR file with each application. This is the recommended method because you can reload the utility classes in case they change, without redeploying the complete application.
You might also add the shared utility classes to the system classpath of WebLogic Server. The classes are loaded by the system classpath ClassLoader, and are therefore available to all the application ClassLoaders, which are its children. However, unless you restart WebLogic Server, this doesn’t enable you to reload the utility classes if they’re modified.
If you need to bundle resource adapter classes with your EJBs or Web applications, you must bundle them within the corresponding application archive.
While developing J2EE applications, you might require some utility archives or third-party libraries to be bundled along with your application. The J2EE specification allows the use of a manifest file entry named Class-Path to specify the supporting JARs as a part of the J2EE application.
To include the utility classes using the Class-Path entry, you should create a manifest file named MANIFEST.MF that references the utility JAR files. The manifest file must be located in the META-INF directory of your application archive and should contain the following entries:
Manifest-version: 1.0 Class-Path: utility1.jar,utility2.jar,utility3.jar
The first line of the manifest file must always contain the Manifest-version, which should be followed by a new line character. On the next line, you can specify the Class-Path attribute with the utility JARs you want to bundle along with the application.
The Class-Path entry refers to other archive files relative to the current archive. Thus, multiple Web application WAR files and an EJB JAR file can share a common JAR archive. This obviates the need to bundle a common JAR archive with every application.
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.
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 directory structure for assembling a Web application is defined by the Servlet specification, as follows:
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
imagesdirectory inside the document root. The JSP and HTML files within the document root can then access the image files relative to the document root.This directory contains the manifest file for archiving.
All files under
WEB-INFare private, and are not served to a client. TheWEB-INFdirectory contains the deployment descriptor files and, optionally, two other directories namedclassesandlib.This directory contains servlet classes and other utility classes required by the servlets.
This directory contains JAR files used by the Web application, such as tag libraries.
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.xmlThis 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.
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
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 onHTTP 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.
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:
Set the local environment using the
setWLSEnv.cmdscript (Windows) orsetWLSEnv.shscript (Unix).Run the utility by executing the following command on the command line:
java weblogic.marathon.ddinit.WebInit webAppNamewhere
webAppNameis 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:eauser_projectsmydomainapplicationsHelloApp
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:eauser_projectsmydomainapplicationsHelloApp [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.
To stage and package a Web application, follow these steps:
Develop the servlets, JSPs, static files, and tag libraries that make up the Web application.
Assemble the Web application files in the appropriate directory structure described previously by placing each file in its prescribed directory.
Create the deployment descriptors:
web.xmlandweblogic.xml(optional). These can be created manually or automatically using WebLogic-specific utilities, as discussed in the previous section.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.warwhere
myWebAppis 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 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.
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:
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.
This directory contains the following deployment descriptors related to the EJB application:
ejb-jar.xml—. A standard deployment descriptorweblogic-ejb-jar.xml—. A WebLogic-specific deployment descriptorweblogic-cmp-rdbms-jar.xml(optional)—. A WebLogic-specific descriptor for object-to-relational mapping of CMP entity EJBs.
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 Server–specific 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 Server–specific 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.
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:
Set the local WebLogic Server environment using the
setWLSEnv.cmdscript (Windows) orsetWLSEnv.shscript (Unix).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: eleases70platformsp1weblogic700 samplesserversrcmyexamplesdeploymentcontainerManageduild [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.
To stage and package an EJB application, follow these steps:
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.
Create the required deployment descriptors—.
ejb-jar.xml,weblogic-ejb-jar.xml, andweblogic-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 theMETA-INFdirectory in the staging directory.Ensure that the EJB class files and the descriptor files are correctly placed in the staging directory, as discussed previously.
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.
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.
To be packaged correctly, enterprise applications must follow a specific directory structure, which is defined by the J2EE Specification, as follows:
This is the document root of the enterprise application directory, which contains all the Web and EJB application modules (
.warand.jarfiles), as well as any utility class files (.jar) required by the enterprise applicationThis directory contains the following deployment descriptor files related to the enterprise application:
application.xml—. A J2EE standard enterprise application descriptorweblogic-application.xml—. A WebLogic-specific application descriptor
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)
Example 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.
To stage and package an enterprise application, follow these steps:
Create a staging directory that will serve as the root of the enterprise application.
Copy the Web application archives (
.war) and EJB application archives (.ear) into the root of the staging directory.Copy any resource adaptor archives (
.rar) and utility archives, if required, to the same directory.Create a
META-INFdirectory inside the root of the staging directory.Create the
application.xmldeployment descriptor in theMETA-INFdirectory to include all the modules within the application as described in the previous section.Create the
weblogic-application.xmldeployment descriptor, if required.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.
WebLogic Server 7.0 introduces new features, which guarantee homogeneous deployment across clusters, different application staging strategies, application ordering, tracking a deployment task, and an improved deployment API as well as new tools that facilitate deployment. The following subsections discuss all these new features.
WebLogic Server 7.0 introduces a new deployment model called two-phase deployment, which helps to maintain consistency in the deployment of applications across servers in a WebLogic cluster. This deployment model guarantees that an application is either deployed on all the servers in a cluster or none, thus preventing inconsistent deployment of applications.
Using the two-phase deployment model, the deployment of applications occurs in two phases: the prepare phase and the activate phase.
Prepare phase: In this phase, the applications are validated and distributed to the target servers. Necessary error checking is completed to ensure that the application and its components are in a state from which they can be reliably deployed to the target WebLogic Servers. In other words, applications are prepared for deployment. The client cannot access the application yet.
Activate phase: In this phase, the actual deployment of the application and its components takes place. The application is activated on the target WebLogic Servers and made available to the clients. Only after the successful completion of this phase are the clients able to access the application. This phase proceeds only if the prepare phase of the deployment has been successful on all the servers in the WebLogic cluster.
If either of the phases—prepare or activate—fails on any WebLogic Server in a cluster, the WebLogic cluster deployment fails.
For example, consider what would happen in a typical failure scenario in which you have two WebLogic Servers (m1 and m2) in a WebLogic cluster. The prepare phase succeeds on both the servers, which means the application has been validated and the files have been copied over to the target servers. The commit succeeds on m1, but fails on server m2 for some reason. In this failure case, the application deployment on m1 would be rolled back, which would result in a homogeneous deployment state. That is, the application would not be deployed on any of the servers in the cluster. The user can then check to see why the deployment failed on m2, correct the problem, and start the deployment task again. The two-phase deployment feature hence prevents inconsistent deployment states across clustered WebLogic Servers.
During the prepare phase of a two-phase deployment, application files are copied from the source on the Administration Server to a staging directory on the managed server. This copying of application files to a location on the file system from where they can be deployed is called application staging. Staging consists of three factors:
Should the application files be copied?
Where should the application files be copied?
By whom should the application files be copied?
Each server has a staging mode, which controls these factors. We’ll discuss how the staging mode can be set later in this section. The three staging modes in WebLogic Server are as follows:
nostage: In this mode, the application files aren’t copied to any location. The application is deployed from the source directory itself. This is the default staging mode for the Administration Server.
stage: In this mode, the application files are copied by the Administration Server to a preconfigured staging directory on those managed servers to which the application is targeted. This is the default staging mode for managed servers.
external_stage: In this mode, the application files are copied to the managed server’s staging directory, but not by WebLogic Server. The server assumes that a user or some third-party tool will perform the distribution of application files.
The staging mode controls whether the application files are copied, the location to which they’re copied, and by whom. You can set the staging mode through the Administration Console using the following steps:
Start the Administration Server and access the Administration Console.
Select the domain name in the navigation tree in the left pane.
Click the server’s node in the left pane for which you have to set the staging mode and staging directory.
Click the Configuration, Deployment tab in the right panel. From the displayed screen, as illustrated in Figure 27.3, select the staging mode you require from the drop-down list box.
Figure 27.3. Set the staging mode, staging directory, and upload directory for an Administration Server.
On the screen shown in Figure 27.3, you can also set the following attributes:
Staging Directory: This is the directory on the server to which the application files are copied during the prepare phase of the two-phase deployment. If an absolute path isn’t specified, the path is relative to the root directory; that is, the directory from which the server instance is started.
Upload Directory: This is the directory where all the uploaded applications are placed. This attribute can be configured only for the Administration Server because applications can be uploaded only to the Administration Server.
Click the Apply button so that the preceding settings are saved in the configuration file of the Administration Server. Because these attributes are not dynamic, you must restart the server for the changes to take effect.
The attributes discussed earlier are MBean attributes of weblogic.management.configuration.ServerMBean. These can also be set using the JMX API or the weblogic.Admin utility. Each application also has a StagingMode attribute, which can be set on its corresponding application MBean to override the server’s StagingMode attribute. This can be performed via the Administration Console. To set this attribute for a Web application, use the following procedure:
Start the Administration Server and access the Administration Console.
Expand the Deployments node in the navigation tree on the left pane.
Expand the Web Applications node to list all the Web applications configured in the domain.
Click on the Web application for which you want to override the
StagingModeattribute.Select the
StagingModeattribute for the Web application in the right pane.
WebLogic Server 7.0 deploys or starts services before it deploys applications. Services such as JDBC and JMS are started before deploying applications such as Web applications and EJBs. The reason for this order is that these services are sometimes necessary for some of the applications to be deployed correctly. For example, JDBC connection pools and data sources are needed for CMP entity EJBs, and message-driven beans might require a JMS destination to be bound to the JNDI tree before initialization. Web applications might acquire JDBC connections or look up EJBs or JMS objects in the server’s JNDI tree during initialization if the load-on-startup element is present.
The following is the deployment order for applications, from first to last:
Connectors
EJBs
Web applications
You can set the ordering of applications for the servers in a domain by setting the deployment order attribute in the Administration Console. The server uses this attribute to determine when it should deploy an application relative to other applications of the same type. This attribute is a number and applications with the lowest number are deployed first. There’s no guarantee with regard to the order of deployment among applications that have equal deployment order attributes specified. The ordering is relative between the applications on the same server and not among servers.
The ordering of components within an application EAR file is controlled by the order in which the application components (EJBs and Web applications) are declared in the application.xml deployment descriptor. For example, consider the following application.xml snippet from the J2EE Blueprint PetStore application:
<application>
<module>
<ejb>petstoreEjb.jar</ejb>
</module>
<module>
<web>
<web-uri>petstore.war</web-uri>
<context-root>petstore</context-root>
</web>
</module>
</application>
When the petstore.ear is deployed, the petStoreEjb.jar will be deployed before the petstore.war.
WebLogic Server provides a set of tools for deploying applications to WebLogic Servers and clusters. The following tools are provided:
The Administration Console
The
weblogic.DeployerutilityThe WebLogic Builder
The auto-deploy feature for WebLogic Server in development mode
This section discusses each of these tools and how they can be used to deploy applications in detail.
The Administration Console provides a browser-based GUI to configure, administer, and monitor the WebLogic Server domain. Administration Console is a Web-based application that’s deployed on the Administration Server. This subsection shows how you can use the Administration Console to configure and deploy applications to the WebLogic Server domain.
Follow these steps to configure a new J2EE application using the Administration Console:
Access the Administration Console through the browser using the following URL:
http://<adminServerListenAddress>:<adminServerListenPort>/consoleBecause the Administration Console is deployed on the Administration Server, the Administration Server must be running for you to access it. After you’ve launched the Administration Console in a browser, you must log in using the Administration Server’s system username and password.
The Administration Console has a navigation tree in the left frame that enables the user to navigate through the complete domain configuration. Start by selecting the domain that you want to work with.
Expand the Deployments node. The node expands to show the various J2EE components that can be deployed onto the server. This includes enterprise applications (EAR files), EJBs (JAR files), Web applications (WAR files), and connectors (RAR files). It also includes nodes for startup and shutdown classes and Web Service components.
Click on the Applications node. The right frame will display a list of applications that have already been configured. If you have not yet deployed any applications to the domain, the right pane displays only the Configure a new Application link, as shown in Figure 27.4.
To configure a new application in your WebLogic domain, click the Configure a new Application link.
This action opens the Locate Application or Component to Configure screen to guide you through deploying a J2EE application/component, as shown in Figure 27.5.
The J2EE application/component files should be accessible or be present on the Administration Server’s local file system for them to be configured through the Administration Console. If the application files are not present on the local file system, you can upload them to the Administration Server using the upload it through your browser link on the screen.
From this screen, you can either select an archived application file (EAR, WAR, JAR, or RAR file) or an application in the exploded directory format for configuration. If you select an application in an exploded directory format, the server deploys all the components in that selected directory.
Select the archive file you want to configure by clicking the [select] link to the left of the archive file or the exploded directory.
After you’ve selected the application you want to deploy, the Configure Application or Component screen will be displayed. From this screen, select the WebLogic Server or cluster to which you would like to deploy your application. You also have to enter a name that will be assigned to your application to identify it in the Administration Console.
Note
If you don’t select any servers or clusters, the application/component is only configured and is not deployed to any of the servers. You can, at a later time, make the appropriate target server selections and then choose to deploy the application.
For example, Figure 27.6 shows that an application named app1 is targeted to be deployed to the AdmminServer WebLogic Server.
To deploy your application to your target WebLogic Server(s), click the Configure and Deploy button. Upon clicking this link, you’re presented with the Deployment Panel indicating the status and activity of your initiated deployment process. An example of the Deployment Panel screen for the application named app1 is shown in Figure 27.7.
After your application is deployed, the Deployed column of the Deployment Status by Target table shows Deployed next to each of the deployed J2EE component(s). For example, Figure 27.8 shows the three components that were packaged in the app1 application have all been successfully deployed to their target server.
From the Deployment Panel, you can undeploy or redeploy an entire application or its individual components. By selecting one of the deployed application components in the Deployment Panel, you’re provided with a Deployed Component screen, similar to Figure 27.9, from which you can perform the actions in the list that follows the figure.
Use the Configuration tab to change the deployment order and staging mode for the application
Use the Targets tab to add or remove servers and clusters from the targeted list
Use the Deploy tab to deploy or undeploy to all targeted servers, or deploy, undeploy, or redeploy to a selected server at a time
Use the Monitoring tab to monitor the application at runtime
If you need to reconfigure a deployed application, such as adding or removing target server(s) or changing the staging mode or deployment order, you can perform these tasks directly from the Administration Console screens shown in Figures 27.8 and 27.9, respectively. To reach these screens after you’ve deployed your application, select the node of the application or component you want to reconfigure from the left pane of the Administration Console. Application components are listed as subnodes of their application name node, which you assigned during their deployment. For example, in Figure 27.8, app1 is the application name node in the Administration Console that contains the following deployed components:
WebApp1.war—. A Web applicationejb1.jar—. An EJBejb2.jar—. An EJB
In WebLogic Server, you can deploy a component that’s part of an enterprise application, or deploy an independent component that is not within an enterprise application. The Administration Console also enables you to undeploy components that have been deployed either way.
To undeploy a component with the Administration Console, follow these steps:
Select the component to be undeployed using the navigation tree in the left panel. The component can be a subnode of the Applications node or the EJB, WebApp, or another node, depending on how it was deployed.
Click the Deploy tab in the right panel.
In the deployment table, click the Undeploy button for the target you would like to undeploy.
This action undeploys the component from the target server. The console also refreshes to show the new deployment state and displays the status of the undeployment activity in the deployment activity table.
Note
Undeploying a component doesn’t remove or delete the component from the server. The application is only deactivated and unprepared on the server it was undeployed from. That means the application classes are unloaded from the server and left in a state from which they can be reloaded again, if needed. Neither are the class files removed from the staging directory of the server.
To delete applications from the WebLogic domain, follow these steps:
Deleting the application permanently deletes the application from the domain configuration. If the application is active on some servers in the domain, it’s first undeployed and then deleted.
To delete a component, go to the node of which the component is a type and follow the same procedure you would to delete an application.
To view a list of components and their deployment status through the Administration Console, follow these steps:
If you click on an application archive within the Application node, you’ll see the deployment status for each component within that application.
If you click on a component, you’ll see the deployment status for that particular component only.
The weblogic.Deployer tool is a utility that can be used to deploy applications to the WebLogic server and cluster from the command line. This utility has been developed primarily for administrators and developers who prefer to deploy applications from the command line, using shell scripts instead of using the GUI-based console.
To start the weblogic.Deployer tool, follow these steps:
Set up your local environment using the
setEnv.cmd(Windows) orsetEnv.sh(Unix) script depending on your operating system environment. This sets the appropriate environment variables including the JDK home and the systemCLASSPATH.These scripts can be found in the root of your domain directory.
You can invoke the deployer tool using the following syntax from the command line:
java weblogic.Deployer [options] [-activate|-deploy|-deactivate|-undeploy| -remove|-unprepare|-cancel|-list] [files]
The following commands provide more information on using the weblogic.Deployer utility:
Table 27.1 lists some of the main actions that can be performed with the weblogic.Deployer utility.
Table 27.1. Main Actions Passed on to weblogic.Deployer
This section and subsequent sections related to the weblogic.Deployer utility will describe how to use the weblogic.Deployer utility to deploy and redeploy a simple application named app1. The app1 application is packaged in an enterprise archive named app1.ear and contains the following archives:
Two EJBs packaged archives:
ejb1.jarandejb2.jarOne Web application packaged archive:
webApp1.war
In the examples, the weblogic.Deployer utility will be targeting a WebLogic Server domain with the following configuration:
Domain name: mydomain
Admin server: AdminServer listening on: EINSTEIN:7001
Managed server: MS1 listening on: EINSTEIN:7003
Managed server: MS2 listening on: EINSTEIN:7005
You can substitute your own application, WebLogic domain, and WebLogic Server names where appropriate to follow the weblogic.Deployer examples.
For example, to deploy the app1 application to the AdminServer (Administration Server), you can issue the following command:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -source app1.ear -name app1 -activate
This command deploys and activates the application named app1 (specified by -name and located in the current directory) to the Administration Server (specified by -adminurl).
The output from issuing this command is shown in Figure 27.10.
Figure 27.10. The output from deploying an application (app1) successfully to an Administration Server.
After the app1.ear application has been successfully deployed to the Administration Server, you can verify the deployment of the application and its components through the Administration Console.
If you need to target your deployment to specific managed servers in your domain, you must use the -targets option to specify those target deployment servers.
For example, the following command activates the application named app1.ear (specified by -name) on the managed servers MS1 and MS2 (specified by -targets):
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -source app1.ear -name app -targets MS1,MS2 -verbose –activate
Caution
The -targets option is a comma-separated list of the targeted WebLogic Server. If you place a space between the targeted servers, the application will be deployed to only the fist server in the list.
In the preceding command, the -verbose option was used to provide additional progress messages, which is helpful if you want to understand the tasks that are initiated by the Administration Server to deploy your application. The output from issuing this command is shown in Figure 27.11.
If you need to redeploy a new version of an existing deployed application, you must use the weblogic.Deployer command with the -source and the -targets options, which specify the location of the modified files and the target servers to redeploy the new application to, respectively. If you don’t provide the -source option or a list of updated files, the Administration Server assumes that nothing has been changed in the application and the deployment operation has no effect.
For example, the following command redeploys and activates a new version of the application named app1, located in a directory specified by the -source option, to the MS1 managed server specified by the -targets option:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -source app1.ear -name app -targets MS1 -verbose -activate
The output from issuing this command is shown in Figure 27.12.
You can add a new module to an existing application that’s already deployed on WebLogic Server without redeploying the entire application. To add a new module, you must first add the appropriate entry in the application’s application.xml deployment descriptor and then repackage the application.
For example, to add a new module webApp2.war without redeploying the existing modules within the application app1.ear in the MS1 managed server, use the following command:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -name app1 -source app1.ear -targets webApp2.war@MS1 -activate
To deactivate an application on a deployed WebLogic Server, you must use the weblogic.Deployer utility with the -deactivate option.
For example, the following command deactivates the application named app1 on the managed server MS2:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -name app1 -targets MS2 -deactivate
However, the application is not removed from the server MS2, but is left in a state from which it can be reactivated again quickly, if needed. After deactivating an application on a specific WebLogic Server, it isn’t accessible to clients on that server.
The output from issuing the deactivate command is shown in Figure 27.13.
If you need to deactivate an application from all the WebLogic Servers in a domain that the application has been deployed to, you can use the weblogic Deployer utility with the -deactivate option. This time, however, you do so without specifying the -targets option.
For example, the following command deactivates the app1 application on all the WebLogic Servers to which it has been deployed:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -name app1 -deactivate
To reactivate an application that has been deactivated on a WebLogic Server instance, you can use the weblogic.Deployer utility with the -activate and -targets option.
For example, the following command activates the application app1, which was deployed to the managed server MS2, but was deactivated:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -name app1 -targets MS2 -activate
The output from issuing this command is shown in Figure 27.14.
It’s important to understand that to activate a deactivated application, you don’t need to specify the -source option. Because the application was already configured on a WebLogic Server instance, the application files are staged there and the deactivation task doesn’t delete the application files.
The process of removing an application involves deactivating an application from its target WebLogic Server and removing any resources and files that were staged for that application. To remove an application using the weblogic.Deployer utility from a targeted WebLogic Server, you must use the -remove and -targets options.
For example, the following command deactivates the application app1 as well as removes all the files related to the application from the managed server MS2:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -name app1 -targets MS2 -remove
The output from issuing this command is shown in Figure 27.15.
To remove an application from all the WebLogic Servers it has been deployed to, you can use the weblogic.Deployer utility with the -remove option, but without specifying the -targets option. This removes the application files from the staging directory of all the WebLogic Servers to which it was deployed.
For example, the following command removes the app1 application from all of its deployed WebLogic Servers:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -name app1 -remove
If you’ve deployed an exploded Web application to WebLogic Server, you can also use the weblogic.Deployer utility to redeploy or refresh parts of the Web application.
For example, the following command refreshes the index.jsp file within a sample Web application deployed in an exploded directory on WebLogic Server:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -name exampleWebApp -activate .index.jsp
The path specified after the -activate option is relative to the root of the application from which it was originally deployed. In addition, you can also refresh static content in an exploded Web application.
You can summarize your deployment activity using the weblogic.Deployer utility by using the -list option as follows:
java weblogic.Deployer -adminurl http://einstein:7001 -list
A sample output from issuing this command is shown in Figure 27.16.
The output shows a list of deployment tasks that have been recently performed by the Administration Server.
If you ever need to cancel a deployment task that has been started incorrectly or is taking a long time to complete, you can issue a weblogic.Deployer command with the -cancel and -id options. Every time you issue a task for WebLogic Server to execute, that task is assigned a TaskID by the Administration Server. This TaskID is displayed in the output of issuing every weblogic.Deployer command.
For example, to cancel a weblogic.Deployer task with the TaskID 7, you can issue the following command:
java weblogic.Deployer -adminurl http://einstein:7001 -user wls -password einstein -cancel -id 7
The cancellation command has to be invoked from another command shell, different from the one that’s executing the weblogic.Deployer task you want to cancel.
WebLogic Builder is a new GUI-based deployment tool that’s provided with the WebLogic Server installation to assist you in deploying your developed J2EE applications to WebLogic Server. The primary deployment tasks you can perform with WebLogic Builder are as follows:
Generate deployment descriptors for a J2EE application or component
View and edit the deployment descriptors for a J2EE application or component
Validate the deployment descriptors
Connect and deploy an application/module to WebLogic Server
The following sections describe how you can use WebLogic Builder as an application build and deployment tool.
To start the weblogic.Deployer tool, follow these steps:
Set up your local environment using the
setEnv.cmd(Windows) orsetEnv.sh(Unix) script depending on your operating system environment. This sets the appropriate environment variables including the JDK home and the system CLASSPATH.These scripts can be found in the root of your domain directory.
To start WebLogic Builder, you can run the following scripts:
startWLBuilder.cmd(Windows)startWLBuilder.sh(Unix)
Alternatively, in a Windows environment, you can use the appropriate WebLogic Builder Start menu option from the taskbar.
You can open an archived module or an exploded application in WebLogic Builder by choosing File, Open from the main menu. WebLogic Builder pops up a frame that enables you to navigate through the file system to select the desired application archive, as shown in Figure 27.17.
To demonstrate WebLogic Builder, we’ll use an existing enterprise application archive named app1.ear, which has all the deployment descriptors already defined.
When you open an enterprise archive, WebLogic Builder examines the EAR file and creates a hierarchical tree of the modules and the deployment descriptors contained in the application in the left pane. You can navigate the tree and click on any node to see the corresponding deployment descriptor fields in the right pane. Figure 27.18 shows WebLogic Builder with app1.ear open.
The left pane shows the components within app1.ear, which are webApp1.war, ejb1.jar, and ejb2.jar. webApp1.war has one servlet called CookieCounter. If the CookieCounter node is selected, WebLogic Builder opens up the deployment parameters related to the servlet in the right pane. You can change these parameters and click File, Save in the main menu so that WebLogic Builder saves the changes to the appropriate deployment descriptor file. WebLogic Builder displays errors and messages in the bottom pane, which can be displayed by selecting the Errors and/or Messages options from the View menu.
You can also load an application or a component that does not have any deployment descriptors defined for it using WebLogic Builder. In such a scenario, WebLogic Builder examines the application archive or exploded directory, and intelligently creates the required deployment descriptors using a best-guess principle. For this reason, it’s always necessary to verify the integrity of auto-created deployment descriptors using WebLogic Builder.
WebLogic Builder provides a very intuitive way of adding elements to deployment descriptor files. In this section, you learn how you can add a new servlet with a URL mapping to the webApp1.war component of the app1.ear enterprise application archive.
To add a new servlet to a deployment descriptor file, follow these steps:
The right pane shows the servlets that exist in the deployment descriptors. Click the Add button at the bottom of the right pane. This opens an internal frame where you can enter all the information related to a new servlet.
Enter the servlet name and the servlet class or JSP you want to add. Add the URL mappings by which you want to access the servlet. In the same frame, you can add other parameters for the servlet such as init parameters, security roles, and display attributes. These are optional and can be added at a later point. An example of adding a new Servlet up to this point is shown in Figure 27.19.
Click OK. This adds the new servlet to the navigation tree in the left frame.
At this point, the addition of the new servlet hasn’t been saved to the deployment descriptor. You must do this explicitly by choosing File, Save. You can open the
web.xmlfile in theWEB-INFdirectory to verify the additions to the deployment descriptor have been made by WebLogic Builder. You can similarly use WebLogic Builder to add filters, listeners, security roles, security constraints, tag libraries, and so on for Web applications.
To generate the deployment descriptors automatically for an EJB20 CMP bean using WebLogic Builder, follow these steps:
Compile the EJB Java source files (remote interface, home interface, and the bean implementation) to a target directory (for example,
build). The target directory, which contains the EJB classes, will be used for generating the descriptor files for the CMP EJB using WebLogic Builder.Start WebLogic Builder and open the target directory where the EJB classes were compiled. In this case, that directory is
build.Because WebLogic Builder doesn’t find any deployment descriptors in the directory, it will offer to generate them. Click Yes at the prompt to auto-generate the deployment descriptors.
WebLogic Builder introspects the compiled classes and generates the necessary deployment descriptors. Choose File, Save to save the descriptors to their appropriate files. These XML files are saved to a
META-INFdirectory under the root directory; that is,build.
To add a new CMP field to the EJB20 CMP bean, follow these steps:
Click the CMP Fields node in the navigational tree in the left pane. The right pane shows the existing CMP fields for the bean.
Click the Add button on the bottom of the right pane. This opens an internal frame where you can select the field’s name, which corresponds to a getter/setter method in the bean’s implementation class.
Enter the table name that corresponds to the CMP bean or use the Browse button to select it. If you use the Browse button to get the table name, you should be connected to a WebLogic Server instance.
Enter the column name that corresponds to the CMP field. If you’re connected to a server, you can use the Browse button to browse the table and select the column name.
Enter the column type. Figure 27.20 shows WebLogic Builder after the new field has been added to the CMP bean.
Click OK to add the CMP field to the deployment descriptors. The new CMP field will appear in the navigation tree in the left pane under the CMP fields node.
At this point, the addition of the new CMP field has not been saved to the deployment descriptor. You must do so explicitly by choosing File, Save from the WebLogic Builder menu. This adds the new CMP field to the deployment descriptors
ejb-jar.xmlandweblogic-cmp-rdbms-jar.xml.
You can similarly use WebLogic Builder to add finders as well as relations.
WebLogic Builder can validate a component, connect to a running WebLogic Server instance, and deploy a module to a server. The Builder tool can also be used to view the deployment descriptor files. This section looks at each of these actions.
To deploy an application or module to WebLogic Server, WebLogic Builder must be connected to the target WebLogic Server. To connect to a WebLogic Server instance from WebLogic Builder, follow these steps:
Choose Tools, Connect to Server from the Builder menu. This opens an internal frame.
Enter the information about the WebLogic Server you want to connect to from the WebLogic Builder. This includes the server name, the listen address and port, and the protocol to be used for connecting as well as the administrator username and password. An example of this connection information is shown in Figure 27.21.
Click Connect.
This connects WebLogic Builder to the specified WebLogic Server instance.
To validate a component (for example ejb1.jar of the enterprise application archive named app1.ear), use the following procedures:
WebLogic Builder begins validating the component and produces the appropriate messages in the bottom pane. During validation, the tool checks for the J2EE compliance of the bean and runs ejbc on the bean. As shown in Figure 27.22, WebLogic Builder generates messages in the bottom pane that indicate the various actions WebLogic Builder performs during the validation process and the result (if the validation is successful).
WebLogic Builder also enables you to view the XML source of the deployment descriptor files. To do so, follow these steps:
This opens a frame, as shown in Figure 27.23, which shows the source of all the deployment descriptors present for that component.
To deploy an application using WebLogic Builder, follow these steps:
Connect to the server instance by choosing Tools, Connect to Server from the WebLogic Builder menu.
Open the application or component you want to deploy in WebLogic Builder.
Choose Tools, Deploy Module from the Builder menu. Enter the name of the application in the frame that opens and click the Deploy Module button, as shown in Figure 27.24.
The application will be deployed to the WebLogic Server instance to which the WebLogic Builder is connected.
You can also undeploy an application from a WebLogic Server instance by using WebLogic Builder as follows:
Connect to the server instance by choosing Tools, Connect to Server from the Builder menu.
Open any application or component in WebLogic Builder.
In the left pane, click the application you want to undeploy. For example, Figure 27.25 shows the app application selected for undeployment.
In the right pane, click the Undeploy button. Doing so undeploys the application from the WebLogic Server instance.
Auto-deployment is a deployment strategy that enables developers to quickly deploy or redeploy an application to the Administration Server and test it. This feature improves the efficiency of the typical develop-deploy-test harness that’s common during the development phase of any J2EE application.
Auto-deployment is a development time convenience feature, and is not recommended for use on production servers. In addition, this feature is meant for a single-server environment and therefore it isn’t recommended for the deployment of components on managed or clustered servers.
The Administration Server in any WebLogic domain can be started in one of two modes: development mode or production mode.
This mode enables the auto-deployment feature. By default, a WebLogic Server instance runs in development mode. However, you can explicitly set a WebLogic Server into development mode as follows:
By setting the
-Dweblogic.ProductionModeEnabledproperty to false when you start the WebLogic Server directly from the command line. For example:java <arguments> -Dweblogic.ProductionModeEnabled=false weblogic.Server
The
-Dweblogic.ProductionModeEnabledproperty controls the start mode of WebLogic Server.If you start WebLogic Server using the startup script (
startWebLogic.cmd) provided with the WebLogic Server installation, you can set the mode in which the server starts by setting theSTARTMODEvariable in the script. To start WebLogic Server in development mode, you would set this variable to false in the script, as follows:set STARTMODE=false
In this mode, the Administration Server starts an application poller that continuously polls the domainNameapplications directory to detect whether any new applications have been deployed or any existing application has been modified or undeployed. On detecting a change, it takes the necessary deployment actions.
This mode disables the auto-deployment feature. The server does not poll the domainNameapplications directory and therefore any changes in that directory are not detected. Because the auto-deployment feature is disabled in this mode, you must use the weblogic.Deployer tool, WebLogic Builder, or the Administration Console to perform any deployment tasks. Applications should be deployed to WebLogic Server in this mode after you have developed and tested them.
To start WebLogic Server in production mode, you can either set the -Dweblogic.ProductionModeEnabled property to true while starting the server, or you can set the STARTMODE variable in the startup script to true.
To deploy an application when the server is started in development mode, just copy the application to the applications directory of the Administration Server. This directory is present inside the domain directory; for example, mydomainapplications. You can copy either a bundled archive or an exploded application to the applications directory. In the case of exploded applications, all components within the application also should be exploded.
As soon as the Administration Server detects that a new application has been copied to the applications directory, it deploys the application automatically. If the Administration Server isn’t running when an application is copied to the applications directory, the application will be deployed the next time the Administration Server is started.
When the application has been detected and deployed by the Administration Server, the configuration of the application is also persisted to the config.xml file.
Because the Administration Server continuously polls the applications directory, undeploying an application using the Administration Console or weblogic.Deployer utility will not truly undeploy the application. As far as the Administration Server is concerned, there is still an application in the applications directory. For this reason, to undeploy an application from WebLogic Server in development mode, the best technique is just to delete the application archive or the exploded directory from the applications directory. The Administration Server will detect this change and automatically undeploy the application.
If an archived application (EAR, JAR, or WAR) is already deployed to the server through the applications directory, you can dynamically redeploy it just by copying the new version of the archive to the applications directory. The server updates the application automatically.
During the development cycle, a developer can perform this copying as the last step in his build process. When the new version of the archive is copied to the applications directory, it’s automatically updated and the developer can immediately test it—without restarting the server.
When an application or component has been deployed through the applications directory in an exploded format, the Administration Server periodically checks the timestamp on a file named REDEPLOY in the exploded application. If the timestamp on the file has changed since the previous check, the Administration Server redeploys the application.
To redeploy or update an exploded application, follow these steps:
Create an empty file named
REDEPLOYin the exploded application. The location for creating this file depends on the type of the exploded application:If the exploded application is an enterprise application (exploded EAR), the
REDEPLOYfile should be created in the top-levelMETA-INFdirectory; that is, in the same directory as theapplication.xmlfile. If the exploded application is an EJB, theREDEPLOYfile should be created in the top-levelMETA-INFdirectory; that is, in the same directory that contains theejb-jar.xml.If the exploded application is a Web application, the
REDEPLOYfile should be created in the top-levelWEB-INFdirectory; that is, the directory that contains theweb.xmlfile.If the exploded application is a connector, the
REDEPLOYfile should be created in the top-levelMETA-INFdirectory; that is, the directory that contains thera.xmlfile.
To update the application, copy the new files over the existing files in that exploded application directory. For example, in the case of an exploded Web application, you should copy the new set of JSPs over the existing set and copy the new servlet classes to the
WEB-INFclassesdirectory.Modify the timestamp of the
REDEPLOYfile. This can be done by using thetouchcommand on the command prompt; that is, by enteringtouch REDEPLOYor just by opening the file and saving it.
The application poller in the Administration Server detects the change in timestamp of the REDEPLOY file and updates or redeploys the contents of the exploded application.
Ant is an open source Java-based build tool developed by the Apache Foundation and is similar to GNU’s make utility. Ant consists of several built-in tasks for compiling and executing Java applications, building archives, as well as performing file and directory manipulations. These tasks make Ant a very useful tool for building J2EE applications. In this section, you learn some Ant basics, look at some built-in Ant tasks, and then examine how to write Ant scripts to build J2EE applications.
For complete documentation on Ant, the following site is a very useful reference:
WebLogic Server 7.0 bundles Ant version 1.4. The script that invokes Ant is located in the %BEA_HOME%weblogic700serverin directory. This script executes the Java class org.apache.tools.ant.Main. To invoke the Ant utility, this directory must be in your path.
The syntax for using the Ant utility is as follows:
ant [options] [target [target2 [target3] ...]]
The various options that can be passed to the Ant utility are
quiet:Be extra quiet. This is opposite ofverboseand, when used, the utility prints whether or not the build was successful.verbose:By default, the Ant utility prints out some information. With this option, it prints out extra information.listener <classname>:Adds an instance of class as a project listener.find <file>:Searches for build file toward the root of the file system and uses it.
Ant searches for a build file to determine what tasks need to be performed. By default, Ant looks for a file named build.xml in the current directory. If you need to use a build file with a different name, you can specify its name explicitly using the -buildfile argument. For example:
ant -buildfile ejbBuildFile.xml
The Ant build file is an XML document that describes the tasks to be performed by the Ant utility. You may use a simple text editor with XML highlighting or an XML editor to create and edit the build file. The Ant installation contains a JAXP-compliant parser that’s used to parse the build file.
Let’s use the following simple build file to examine its different attributes and properties:
<?xml version="1.0"?>
<project name="example" default="compile" basedir=".">
<property name="srcDir" value="."/>
<property name="targetDir" value="build"/>
<target name="init">
<mkdir dir="${targetDir}"/>
</target>
<target name="compile" depends="init">
<javac srcdir="${srcDir}" destdir="${targetDir}"/>
</target>
</project>
Because Ant build files are XML documents, the first line declares the version of XML in use. The next line defines the root element of the build file; that is, the <project> element. The <project> element contains one or more <target> elements, and each <target> element can contain one or more Ant tasks. Ant tasks are simply Java classes that can be invoked from the build file to perform specific actions. These classes provide the task implementation and should be present in the Ant classpath. Several basic tasks, such as java, javac, and others, are prepackaged with the Ant utility. Some of the built-in tasks available with the utility are described in the next section, “Built-in Ant Tasks.”
In this way, the build file is arranged in a hierarchy. The <project> element has three attributes:
The next two lines specify two <property> elements. The <property> elements enable you to declare user-defined variables that can be used anywhere in the context of the project. A project can have a set of properties defined using the <property> element. The value of a property can be referenced using the notation ${property-name}. The build file defines properties with the names srcDir and targetDir. The values of these properties can be referenced as ${srcDir} and ${targetDir} in the build file. The <property> element can also be used to get access to environment variables by declaring the following property:
<property environment="env"/>
You can then access the values of the environment variables CLASSPATH and PATH as ${env.CLASSPATH} or ${env.PATH}.
The next line defines a <target> element named init. The <target> element contains a sequence of Ant tasks. It has a name attribute so that it can be called from elsewhere in the build file. The name attribute is the only required attribute of the <target> element. In this case, the target contains a file and directory manipulation Ant task called mkdir. This is a predefined Ant task, and here it’s used to create the build directory.
The next three lines define another target element named compile. This target element has a new attribute called depends. This attribute enables you to specify other targets that can be executed before executing the tasks in the body of this target. In this case, because of the depends attribute, the init target will be executed before the compile target. The compile target contains a predefined task called javac. The task has two attributes, srcdir and destdir, that get their values from the project properties defined on the third and fourth lines of the build file.
This build file causes javac to be executed on all the .java files in the directory specified by the srcDir project property. The resultant .class files are placed in the directory specified by the targetDir project property.
We can use Ant and the build file we just created to compile a Java file by following these steps:
Create a temp directory named
antTest.Write a simple
HelloWorld.javaprogram in theantTestdirectory.Copy the
build.xmlfile to theantTestdirectory.Set the required environment variables by running one of the following scripts:
domainsetWLSEnv.cmd (Windows)
domainsetWLSEnv.sh (Unix)
This correctly sets the
PATHandCLASSPATHvariables.Run the Ant script by typing
anton the command line.Ant will find the
build.xmlin the current directory, create a directory calledbuild, compile theHelloWorld.javafile, and place it in thebuilddirectory.
The basic Ant utility is packaged with many built-in Ant tasks. Some of the common core tasks are
Tasks for compiling and executing Java applications:
<javac>,<java>, and<javadoc>Archive creation tasks:
<jar>,<war>, and<ear>File and directory manipulation tasks:
<copy>,<delete>,<mkdir>,<move>,<touch>, and<tstamp>
Let’s look at the most common Ant tasks that will help you in creating build scripts for J2EE applications.
The javac Ant task compiles the javac source code; that is, the .javac files. This task is smart in the sense that the compilation happens only if the .javac file has a more recent timestamp than its corresponding .class file.
The following are two examples of using the javac task:
<javac srcdir="myProjectsource" destdir="myProjectclasses"> <javac srcdir="myProjectsource" destdir="myProjectclasses" excludes="myPackage/**" classpath="myClasses.jar">
The srcdir attribute specifies the location of the source java files. The destdir attribute specifies the location to which the source files will be compiled.
Some additional attributes of the javac task are
includes:A comma-delimited list of files that must be included; wildcards are allowedexcludes:A comma-delimited list of files that must be excluded; wildcards are allowedclasspath:The classpath passed on to the Java compiler to be used while compilingdeprecation:Used to print information about deprecated classes and methods while compiling
The java task executes a specified Java class. The class may execute within the same JVM as the Ant utility or a new JVM, depending on the value of the fork attribute.
The following are two examples of using the java task:
<java classname="mypackage.HelloWorld"/> <java classname="mypackage.HelloWorld" classpath="myClasses.jar" fork="yes"/>
In the second example, the fork attribute is set to yes, so the HelloWorld program will execute in a different JVM instance from the Ant utility. If the attribute were set to no, the program would be run in the same JVM instance. In this case, be careful that the class does not have a System.exit() because that will terminate the execution of Ant.
Some of the other attributes that can be passed to the java Ant task are
While running a Java program, in most cases, we pass arguments to the JVM as well as command-line arguments to the program. We also need to pass system properties required by the Java class. This also can be done in the Ant java task as follows:
<java classname="mypackage.HelloWorld" fork="yes">
<arg value="-help"/>
<jvmarg value="-Xms=16m"/>
<sysproperty key="worldName" value="earth"/>
</java>
The <arg> element supplies command-line arguments to the Java program. The <jvmarg> element provides command-line arguments to the JVM. The <sysproperty> element supplies the system properties to the Java class while executing.
The jar task archives a set of files and may update existing archives or replace them depending on the attributes passed to the task.
The following are some examples of creating a Java archive:
<jar jarfile="myProject.jar" basedir="myProject"> <jar jarfile="myProject.jar" basedir="myProject" update="yes"> <jar jarfile="myProject.jar" basedir="myProject" excludes="*.html" compress="true">
The Ant utility also provides built-in Ant tasks for carrying out operations on files and directories such as copying files, creating and deleting directories, and so forth.
The following are examples of a few such tasks:
<copy file="myweb.xml" tofile="${build}/WEB-INF/web.xml"/>
<copy file="weblogic.xml" todir="${build}/WEB-INF" overwrite="yes"/>
<mkdir dir="${build}/images"/>
<delete dir="${build}/>
In the preceding examples, build is defined as a project property. Therefore, its value is specified in the script as ${build}.
Besides these Ant tasks that can be used to build any Java project, Ant also bundles some tasks that are specific to building J2EE applications. The following section describes two such useful tasks: war and ear.
The war Ant task can be used to archive a set of files into the standard J2EE web application format. The war task contains attributes and elements specific to building a Web application archive. Some of these elements are
webxml:This attribute defines the file to be used as theweb.xmldeployment descriptor and copies it asweb.xmlinto theWEB-INFdir of the archive.manifest:This attribute defines the file to be used as the manifest file and copies it asMETA-INFMANIFEST.MFof the archive.<lib>:Specifies the files to be copied into theWEB-INFlibdirectory using this element.<classes>:Specifies the files to be copied into theWEB-INFclassesdirectory using this element.
The following is an example of creating a Web application archive:
<?xml version="1.0"?>
<project name="example" default="buildWar" basedir=".">
<target name="buildWar">
<war warfile="myWebApp.war" webxml="dd/myWeb.xml" manifest="manifest.txt">
<lib dir="./libraries"/>
<classes dir="./classes"/>
<fileset dir="." includes="*.html,*.jsp"/>
<zipfileset dir="." prefix="images" includes="*.gif,*.jpg"/>
<zipfileset dir="." prefix="WEB-INF" includes="weblogic.xml"/>
</war>
</target>
</project>
The <fileset> element defines a collection of resources relative to the base directory. Here, the <fileset> is used to include all the JSPs and HTML pages in the root directory of the Web application. The <zipfileset> element is an extension of the <fileset> element with extra attributes that are useful in the context of archiving tasks. The prefix attribute of the <zipfileset> element is prepended to each entry in the output archive. Here, the output archive will have GIF and JPG files prefixed with images and the weblogic.xml file prefixed with WEB-INF; that is, WEB-INFweblogic.xml.
The ear Ant task archives a set of files into the standard J2EE enterprise application format. The appxml attribute defines the file that is to be used as the application.xml deployment descriptor.
The following is an example of creating an enterprise archive:
<ear earfile="myEnterpriseApp.ear" basedir="myproject"
appxml="myApp.xml" includes="*.jar,*.war"/>
As explained earlier in the section on the auto-deployment WebLogic Server feature, WebLogic Server can be run in two distinct modes: development and production. The server should be started in development mode when you’re developing applications and need to test them frequently. This mode should be used only in a single-server environment. The production mode should be used when you’ve completed the development phase and tested the application, and now need to launch it.
In this section, we describe some best practices that can be followed for deploying applications. While in the development phase of your project, start the server in development mode. However, depending on your infrastructure needs, you may either have a single- or multiple-server environment.
If you’re using a single-server environment in development mode, here are some tips that can improve your efficiency while developing applications:
Keep applications in an exploded format.
Deploy your application directly from the source directory.
Consider using auto-deployment by maintaining the application in an exploded format in the
<domainName>/applicationsdirectory of the Administration Server.To change any JSP, HTML, or image files, change them directly in the
<domainName>applications<yourWebApp>directory. You’ll see the changes to these files immediately when you access them.To update existing servlets (which have an entry in
web.xml), directly compile them to<domainName>applications<yourWebApp>WEB-INFclassesdirectory.To add new servlets, update deployment descriptors, or load new tag libraries or other libraries into the
WEB-INFlibdirectory, make the changes to the Web application under<domainName>applicationsdirectory, and then touch (modify the timestamp of) theWEB-INFREDEPLOYfile to redeploy the complete application.To update changes to the deployment descriptors of EJBs or resource adapters, touch (modify the timestamp of) the
META-INFREDEPLOYfile.To update changes to an enterprise archive in an exploded format, touch (modify the timestamp of) the
META-INFREDEPLOYfile.
If you’re developing in a multiple-server environment or running your server in production mode:
To update any changes to the application source files or deployment descriptors, use the
weblogic.Deployertool or the Administration Console to redeploy the application.When only a part of the application has changed, consider doing incremental updates; that is, updating only a particular component instead of redeploying the whole application. The
weblogic.Deployertool allows this and is described earlier in this chapter.