Deploying WebLogic Server Applications
The following sections describe more advanced deployment topics that might not be used in every WebLogic Server installation:
WebLogic Server uses a two-phase deployment protocol when deploying applications and standalone modules in a domain. The protocol ensures the consistency of deployments to multiple WebLogic Servers in a domain, and also supports advanced deployment features such as application ordering and improved monitoring.
Each deployment in a WebLogic Server domain takes place in two phases: prepare and activate.
The prepare phase ensures that the application and its modules are in a state in which they can be reliably deployed. During the prepare phase, WebLogic Server instances in the domain complete the following tasks:
In the activate phase, target servers make the application available for clients to use. The activate phase constitutes the actual deployment of the application or module.
The activation phase only takes place after the prepare phase successfully completes.
The primary goal of the two-phase deployment model is to ensure that a deployment to multiple targets (for example, deployments to a cluster of WebLogic Server instances) succeeds or fails as a logical unit on the available target servers. In a cluster, you can ensure that a deployment does not activate if even one of the available servers fails to verify the deployment files or detects an error in the deployment files.
Note: The WebLogic Server 6.x deployment protocol, which is deprecated in WebLogic Server 8.1, does not ensure consistent deployment to clusters. See WebLogic Server 6.x Deployment Protocol (Deprecated) for more information.
The two-phase deployment protocol also enables the following new features for deployed applications:
By default, the two-phase deployment protocol is used to deploy new applications by all available deployment tools. The Administration Server also uses the deprecated WebLogic Server 6.x deployment protocol when:
application.xml
descriptor.The 6.x deployment protocol is now deprecated. If you have applications that use the 6.x protocol, follow these instructions to use two-phase deployment:
java weblogic.Deployer -adminurl http://admin:7001 -username weblogic
-name app -undeploy
application.xml
file, create one in the application's META-INF
subdirectory.java weblogic.Deployer -adminurl http://admin:7001 -username weblogic
-deploy -name ArchivedEarJar -source C:/MyApps/JarEar.ear
-target server1,server2
When you deploy to a WebLogic Server cluster, the default two-phase deployment behavior ensures that the deployment succeeds only on clustered server instances that are reachable by the Administration Server. If servers are unreachable at the time of deployment (for example, because of a network failure between the Administration Server and a Managed Server) those servers will not receive the deployment request until the network connection is restored. This can lead to a situation where some servers in the cluster use a new version of a deployment unit, while other, unreachable servers use an older version.
The ClusterConstraintsEnabled
option enforces a strict two-phase deployment policy for all servers in a domain. ClusterConstraintsEnabled
ensures that a deployment to a cluster succeeds only if all members of the cluster are reachable and can deploy the specified files.
You can set the ClusterConstraintsEnabled
for the domain when you start the Administration Server by supplying a startup argument:
-DClusterConstraintsEnabled=true
enforces strict cluster deployment for servers in a domain.-DClusterConstraintsEnabled=false
uses the default two-phase deployment behavior for servers in a domain; deployment is ensured only for clustered servers that are reachable by the Administration Server.You can also set the ClusterConstraintsEnabled
option using the Administration Console:
The deployment staging mode determines whether or not the Administration Server copies deployment files to target servers during the activate phase of a deployment. WebLogic Server provides three different options for staging archive files: stage mode, nostage mode, and external_stage mode, as described in Staging Modes.
A server's staging directory is the directory in which the Administration Server copies deployment files for stage mode deployments. It is also the directory in which deployment files must reside before deploying an application using external_stage mode.
In stage mode, the Administration Server copies the deployment files from their original location on the Administration Server machine to the staging directories of each target server. For example, if you deploy a J2EE Application to three servers in a cluster using stage mode, the Administration Server copies the deployment files to directories on each of the three server machines. Each server then deploys the J2EE Application using its local copy of the archive files.
Warning: After you have deployed your application, do not change or remove the original source files for the application. The WebLogic Server deployment framework uses the files to manage deployed applications. Changing or removing the original source files may result in unexpected application behavior.
When copying files to the staging directory, the Administration Server creates a subdirectory with the same name as the deployment name. So if you deployed using the command:
java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic -name mytestear -stage -targets mycluster
-deploy c:\bea\weblogic81\samples\server\medrecd\dist\physicianEar
a new directory, mytestear
, would be created in the staging directory of each server in mycluster
. If you do not specify a deployment name, a default deployment name (and staging subdirectory) is used:
physicianEar
in the example above).physicianEar.ear
, the deployment name and staging subdirectory are physicianEar
.The Administration Console uses stage mode as the default mode when deploying to more than one WebLogic Server instance. weblogic.Deployer
uses the target server's staging mode as the default, and managed servers use stage mode by default.
Stage mode ensures that each server has a local copy of the deployment files on hand, even if a network outage makes the Administration Server unreachable. However, if you are deploying very large applications to multiple servers or to a cluster, the time required to copy files to target servers can be considerable. You may consider nostage mode to avoid the overhead of copying large files to multiple servers.
In nostage mode, the Administration Server does not copy the archive files from their source location. Instead, each target server must access the archive files from a single source directory for deployment. The staging directory of target servers is ignored for nostage deployments.
For example, if you deploy a J2EE Application to three servers in a cluster, each server must be able to access the same application archive files (from a shared or network-mounted directory) to deploy the application.
Note: The source for the deployment files in nostage mode is the path provided by the user at deployment time (as opposed to stage mode, where the source is the path in each server's staging directory). However, even in nostage mode, WebLogic Server copies out parts of the deployment to temporary directories. This enables users to update entire archived deployments or parts of archived deployments.
In nostage mode, the Web Application container automatically detects changes to JSPs and servlets. Nostage also allows you to later update only parts of an application by updating those parts in one file system location and then redeploying.
The Administration Console uses nostage mode as the default when deploying only to the Administration Server (for example, in a single-server domain). weblogic.Deployer
uses the target server's staging mode, and Administration Servers use stage mode by default. You can also select nostage mode if you run a cluster of server instances on the same machine, or if you are deploying very large applications to multiple machines that have access to a shared directory. Deploying very large applications in nostage mode saves time during deployment because no files are copied.
External_stage mode is similar to stage mode, in that target servers deploy using local copies of the deployment files. However, the Administration Server does not automatically copy the deployment files to targeted servers in external_stage mode; instead, you must copy the files to the staging directory of each target server before deployment. You can perform the copy manually or using automated scripts.
Within each target server's staging directory, deployment files must be stored in a subdirectory that reflects the deployment name. This can either be the name you type in for the deployment, or the default deployment name (the name of the exploded archive directory, or the name of the archive file without its file extension). See Deploying an Enterprise Application Using external_stage Mode for an example.
External_stage mode is the least common deployment staging mode. It is generally used only in environments that are managed by third-party tools that automate the required copying of files. You may also choose to use external_stage mode when you are deploying very large applications to multiple machines and you do not have a shared file system (and cannot use nostage mode). Using external stage in this scenario decreases the deployment time because files are not copied during deployment.
When you deploy an application or standalone module using the Administration Console, the staging mode is set at the application level. The application staging mode always overrides any deployment mode specified for the target server itself.
The server staging mode specifies the default deployment mode for a server if none is specified at deployment time. For example, the server staging mode is used if you deploy using weblogic.Deployer
and you do not specify a staging mode. The default value for the server staging mode is nostage for the Administration Server and stage mode for Managed Servers.
By default, WebLogic Server deploys server-level resources (JDBC followed by JMS) before deploying applications and standalone modules, followed by startup classes. (The order of startup class execution is configurable, as described in Ordering Startup Class Execution and Deployment.)
Note: WebLogic Server security services are always initialized before server resources, applications, and startup classes are deployed. For this reason, you cannot configure custom security providers using startup classes, nor can custom security provider implementations rely on deployed server resources such as JDBC.
The deployment order of deployment units relative to one another is determined by the Load Order attribute. By default, each deployment unit is configured with a Load Order value of 100. Deployments with a lower Load Order value are deployed before those with a higher value during startup. Deployments with the same Load Order value are deployed in alphabetical order using the deployment name. You can change the load order for a deployment unit by setting the Load Order attribute in the Administration Console or programmatically using the ApplicationMBean. See Changing the Order of Deployment for a Deployment Unit for instructions on changing the Load Order using the Administration Console.
If the application is an EAR, the individual modules are loaded in the order in which they are declared in the application.xml deployment descriptor. See Enterprise Application Deployment Descriptor Elements in Developing WebLogic Server Applications.
By default WebLogic Server startup classes are run after the server initializes JMS and JDBC services, and after applications and standalone modules have been deployed.
If you want to perform startup tasks after JMS and JDBC services are available, but before applications and modules have been activated, you can select the Run Before Application Deployments option in the Administration Console (or set the StartupClassMBean
's LoadBeforeAppActivation
attribute to "true").
If you want to perform startup tasks before JMS and JDBC services are available, you can select the Run Before Application Activations option in the Administration Console (or set the StartupClassMBean
's LoadBeforeAppDeployments
attribute to "true").
The following figure summarizes the time at which WebLogic Server executes startup classes.
Figure 4-1 Startup Class Execution
BEA provides the examples.jms.startup
API code example which demonstrates how to establish a JMS message consumer from a WebLogic startup class.See the Administration Console Online Help or the full Javadocs for StartupClassMBean
for more information.
Note: WebLogic Server 8.1optionally installs API code examples in WL_HOME\samples\server\examples\src\examples
, where WL_HOME is the top-level directory of your WebLogic Server installation. You can start the examples server, and obtain information about the samples and how to run them.
Once you deploy an application, you can redeploy the application itself or selected parts of the application. Redeploying an entire application involves unloading its classes and then deploying the application again with the changed deployment files. (For applications deployed using stage mode, redeployment also involves re-copying deployment files to target servers.)
Note: An application becomes unavailable to clients during redeployment. WebLogic Server doesn't guarantee the operation of the application and deployment task if there is an access from the client at this time. For this reason, redeployment is not recommended for use in a production environment.
Redeploying a part of an application, such as a Web Application or EJB module in an Enterprise Application, involves unloading only the classes in a particular classloader and reloading those classes using the updated class files. See WebLogic Server Application Classloading in Developing WebLogic Server Applications for more information on classloading behavior. Individual files in a Web Application (for instance, a servlet, JSP, or static HTML page) can also be redeployed independently of the rest of the application, without affecting the application classloaders.
See Redeploying or Stopping a Deployment Unit and Redeploying Static Files in a Web Application for example instructions on redeploying applications and modules.
When redeploying applications and modules, consider the following limitations:
save-sessions-enabled
to "true" in the container-descriptor
stanza of the weblogic.xml
deployment descriptor file.weblogic.Deployer
displays the message:Exception:weblogic.management.ApplicationException: [J2EE:160076] You
must include all of [module_list] in your files list to modify [module
]
Partial redeployment refers to changing or adding a part of a deployed Web Application, and using the redeploy action to have the change take place. WebLogic Server supports partial redeployment only for Web Applications that are deployed as exploded WAR files. The following kinds of partial redeployment are supported:
WEB-INF/classes
directory can be redeployed independently of the rest of the Web Application. You can also deploy only the updated classes (rather than the entire WEB-INF/classes
directory) by setting the Reload Period for the Web Application. (See Deploying Web Applications in Developing Web Applications for WebLogic Server for more information about Reload Period.)WEB-INF/lib
cannot be redeployed independently of the rest of the Web Application. The container automatically redeploys the entire application, but maintains the state, when redeploying JAR files in WEB-INF/lib
.
WebLogic Server enables you to change the run-time deployment configuration of an Enterprise Application without having to modify and repackage the contents of the archive itself. You accomplish this by specifying an alternate deployment descriptor file to use when deploying the Enterprise Application.
An alternate deployment descriptor file can reside anywhere outside a packaged EAR file or exploded EAR directory. (You cannot store alternate Deployment Descriptor files within the archive or directory.) You identify the external EAR descriptor file at deployment time, and WebLogic Server uses the alternate file in place of the deployment's existing (packaged) deployment descriptor. If the files are deployed using stage mode, alternate deployment descriptor files are copied with the deployment files to the top level of the deployment's subdirectory in each target server's staging directory (for example, domain_directory/
servername/stage/myapp
). With other staging modes, no copying is performed.
You can specify an alternate deployment descriptor file to use in place of either the standard J2EE deployment descriptor (application.xml
) or the WebLogic Server deployment descriptor (weblogic-application.xml
).
Alternate deployment descriptors are generally used with archived Enterprise Applications (EAR files), because they enable you to change deployment parameters without repackaging the application itself. However, you can also specify alternate descriptors to use with exploded EAR directories.
Common uses for alternate deployment descriptors include:
If you deploy an Enterprise Application using an alternate descriptor, you cannot change the alternate descriptor file's location when you redeploy the application. For example, you cannot use the weblogic.Deployer -redeploy
command and specify a different filename or path to the alternate deployment descriptor file. Note, however, that changes to the original descriptor file are implemented during redeployment.
If you have deployed an application with a standard deployment descriptor, you cannot use an alternate descriptor with the deployed application using the -redeploy
or -deploy
commands. Instead, you must first undeploy the application, then deploy it with an alternate descriptor file
To use an alternate deployment descriptor, you simply use one or both of the following options to weblogic.Deployer
:
-altappdd
—specifies the name of an alternate J2EE deployment descriptor (application.xml
).-altwlsappdd
—specifies the name of an alternate WebLogic Server deployment descriptor (weblogic-application.xml
).See Deploying an Enterprise Application with an Alternate (External) Application Descriptor for an example of using alternate descriptor files.
This section contains topics for J2EE application developers who are developing and deploying applications to WebLogic Server:
Notes: Auto-deployment is a method for quickly deploying an application to a standalone server (Administration Server) for evaluation or testing. It is recommended that this method be used only in a single-server development environment. Use of auto-deployment in a production environment or for deployment on Managed Servers is not recommended.
BEA recommends that you use the WebLogic Server split development directory and wldeploy
ant task, rather than auto-deployment, when developing an application. See Introducing the Split Development Directory Structure in Developing WebLogic Server Applications.
If auto-deployment is enabled, when an application is copied into the \applications
directory of the Administration Server, the Administration Server detects the presence of the new application and deploys it automatically (if the Administration Server is running). If WebLogic Server is not running when you copy the application to the \applications
directory, the application is deployed the next time the WebLogic Server Administration Server is started. Auto-deployment deploys only to the Administration Server.
Notes: Due to the file locking limitations of Windows NT, if an application is exploded, all the modules within the application must also be exploded. In other words, you cannot use auto-deployment with an exploded application or module that contains a JAR file.
Auto-deployment is intended for use with a single server target in a development environment. If you use other tools, such as the Administration Console, to add targets to an auto-deployed, exploded application, redeploying the application does not propagate changes to the new target servers.
You can run a WebLogic Server domain in two different modes: development and production.
Development mode enables a WebLogic Server instance to automatically deploy and update applications that are in the domain_name/applications
directory (where domain_name
is the name of a WebLogic Server domain). In other words, development mode lets you use auto-deploy. Production mode disables the auto-deployment feature.
By default, a WebLogic Server domain runs in development mode. To specify the mode for a domain, see Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.
To auto-deploy an archived application, copy its archive file to the /applications
directory. WebLogic Server automatically sets the application's deployment mode to stage mode.
A deployment unit that was auto-deployed can be dynamically redeployed while the server is running. To dynamically redeploy, copy the new version of the archive file over the existing file in the /applications
directory.
To undeploy an archived deployment unit that was auto-deployed, delete the application from the /applications
directory. WebLogic Server stops the application and removes it from the configuration.
To auto-deploy an application in exploded archive format, copy the entire exploded archive directory to the /applications
directory. WebLogic Server automatically deploys exploded archive applications using the nostage deployment mode. If you deploy an exploded EAR directory that contains archived modules (JAR files), the JAR files are locked during the deployment.
When an application has been auto-deployed in exploded archive format, the Administration Server periodically looks for a file named REDEPLOY
in the exploded application directory. If the timestamp on this file changes, the Administration Server redeploys the exploded directory.
To redeploy files in an exploded application directory:
REDEPLOY
, and place it in the WEB-INF or META-INF
directory, depending on the application type you are deploying:An exploded enterprise application has a META-INF
top-level directory; this contains the application.xml file.
An exploded Web application has a WEB-INF
top-level directory; this contains the web.xml file.
An exploded EJB application has a META-INF
top-level directory; this contains the ejb-jar.xml file.
An exploded connector has a META-INF
top-level directory; this contains the ra.xml file.
Note: The REDEPLOY
file works only for an entire deployed application or standalone module. If you have deployed an exploded Enterprise Application, the REDEPLOY
file controls redeployment for the entire application—not for individual modules (for example, a Web Application) within the Enterprise Application. If you deploy a Web Application by itself as an exploded archive directory, the REDEPLOY
file controls redeployment for the entire Web Application.
When the Administration Server detects the changed timestamp, it redeploys the contents of the exploded directory.
Note: You must touch the REDEPLOY
file (alter its timestamp) any time you wish to trigger redeployment of an auto-deployed application. Even if you modify an application while a server is shut down, you must touch REDEPLOY
to ensure that changes are applied when the server next starts up.
To undeploy an application that was auto-deployed in exploded format, use the weblogic.Deployer
-undeploy
command, or use the Administration Console to remove the deployment configuration. Then remove the application files from the /applications
directory.
Application lifecycle listener events provide handles on which developers can control behavior during deployment, undeployment, and redeployment. This section discusses how you can use the application lifecycle listener events.
Four application lifecycle events are provided with WebLogic Server, which can be used to extend listener, shutdown, and startup classes. These include:
public void preStart(ApplicationLifecycleEvent evt) {}
public void postStart(ApplicationLifecycleEvent evt) {}
public void preStop(ApplicationLifecycleEvent evt) {}
public void postStop(ApplicationLifecycleEvent evt) {}
Note: For Startup and Shutdown classes, you only implement a main{} method. If you implement any of the methods provided for Listeners, they are ignored.
Note: No remove{} method is provided in the ApplicationLifecycleListener, because the events are only fired at startup time during deployment (prestart and poststart) and shutdown during undeployment (prestop and poststop).
In order to use these events, you must register them in the weblogic-application.xml deployment descriptor. See Application Deployment Descriptor Elements. Define the following elements:
You create a listener by extending the abstract class (provided with WebLogic Server) weblogic.application.ApplicationLifecycleListener. The container then searches for your listener.
You override the following methods provided in the WebLogic Server ApplicationLifecycleListener abstract class to extend your application and add any required functionality:
Listing 4-1 illustrates how you override the ApplicationLifecycleListener. In this example, the public class MyListener extends ApplicationLifecycleListener.
import weblogic.application.ApplicationLifecycleListener;
import weblogic.application.ApplicationLifecycleEvent;
public class MyListener extends ApplicationLifecycleListener {
public void preStart(ApplicationLifecycleEvent evt) {
System.out.println
("MyListener(preStart) -- we should always see you..");
} // preStart
public void postStart(ApplicationLifecycleEvent evt) {
System.out.println
("MyListener(postStart) -- we should always see you..");
} // postStart
public void preStop(ApplicationLifecycleEvent evt) {
System.out.println
("MyListener(preStop) -- we should always see you..");
} // preStop
public void postStop(ApplicationLifecycleEvent evt) {
System.out.println
("MyListener(postStop) -- we should always see you..");
} // postStop
public static void main(String[] args) {
System.out.println
("MyListener(main): in main .. we should never see you..");
} // main
}
Listing 4-2 illustrates how you implement the shutdown class. The shutdown class is attachable to preStop and postStop events. In this example, the public class MyShutdown extends ApplicationLifecycleListener.
import weblogic.application.ApplicationLifecycleListener;
import weblogic.application.ApplicationLifecycleEvent;
public class MyShutdown extends ApplicationLifecycleListener {
public static void main(String[] args) {
System.out.println
("MyShutdown(main): in main .. should be for post-stop");
} // main
}
Listing 4-3 illustrates how you implement the startup class. The startup class is attachable to preStart and postStart events. In this example, the public class MyStartup extends ApplicationLifecycleListener.
import weblogic.application.ApplicationLifecycleListener;
import weblogic.application.ApplicationLifecycleEvent;
public class MyStartup extends ApplicationLifecycleListener {
public static void main(String[] args) {
System.out.println
("MyStartup(main): in main .. should be for pre-start");
} // main
}
The following examples illustrate how you configure application lifecycle events in the weblogic-application.xml deployment descriptor file. The URI parameter is not required. You can place classes anywhere in the application $CLASSPATH. However, you must ensure that the class locations are defined in the $CLASSPATH. You can place listeners in APP-INF/classes or APP-INF/lib, if these directories are present in the EAR. In this case, they are automatically included in the $CLASSPATH.
The following example illustrates how you configure application lifecycle events using the URI parameter. In this case, the archive foo.jar contains the classes and exists at the top level of the EAR file. For example: myEar/foo.jar
Listing 4-4 Configuring Application Lifecycle Events Using the URI Parameter
<listener>
<listener-class>MyListener</listener-class>
<listener-uri>foo.jar</listener-uri>
</listener>
<startup>
<startup-class>MyStartup</startup-class>
<startup-uri>foo.jar</startup-uri>
</startup>
<shutdown>
<shutdown-class>MyShutdown</shutdown-class>
<shutdown-uri>foo.jar</shutdown-uri>
</shutdown>
The following example illustrates how you configure application lifecycle events without using the URI parameter.
Listing 4-5 Configuring Application Lifecycle Events without Using the URI Parameter
<listener>
<listener-class>MyListener</listener-class>
</listener>
<startup>
<startup-class>MyStartup</startup-class>
</startup>
<shutdown>
<shutdown-class>MyShutdown</shutdown-class>
</shutdown>
Application lifecycle events are only triggered if a full re-deployment of the application occurs. During a full re-deployment of the application—provided the application lifecycle events have been registered—the application lifecycle first commences the shutdown sequence, next re-initializes its classes, and then performs the startup sequence.
For example, if your listener is registered for the full application lifecycle set of events (preStart, postStart, preStop, postStop), during a full re-deployment, you see the following sequence of events: