Application deployment distributes the information created in Chapter 3, "Configuring Applications for Deployment" to the Administration Server for server-side processing and application startup. Your deployment tool must be able to successfully complete the following deployment operations:
Your deployment tool must instantiate and register the DeploymentFactory objects it uses. You can implement your own mechanism for managing DeploymentFactory objects. WebLogic Server DeploymentFactory objects are advertised in a manifest file stored in the wldeploy.jar file. The manifest contains entries of the fully qualified class names of the factories, separated by whitespace. For example, if you assume that the DeploymentFactory- objects reside in a fixed location and are included in the deployment tool classpath, the deployment tool registers any DeploymentFactory objects it recognizes at startup. See Example 4-1.
Example 4-1 Registered Deployment Factory in the Manifest File
MANIFEST.MF:
Manifest-version: 1.0
Implementation-Vendor: BEA Systems
Implementation-Title: WebLogic Server 9.0 Mon May 29 08:16:47 PST 2006 221755
Implementation-Version: 9.0.0.0
J2EE-DeploymentFactory-Implementation-Class:
weblogic.deploy.spi.factories.DeploymentFactoryImpl
.
.
.
The standard DeploymentFactory interface is extended by weblogic.deploy.api.WebLogicDeploymentFactory. The additional methods provided in the extension are:
String[] getUris(): Returns an array of URI's that are recognized by getDeploymentManager. The first URI in the array is guaranteed to be the default DeploymentManager URI, deployer:WebLogic. Only published URI's are returned in this array.
String createUri(String protocol, String host, String port): Returns a usable URI based on the arguments.
Your deployment tool must allocate a DeploymentManager from a DeploymentFactory, which is registered with the DeploymentFactoryManager class, in order to perform deployment operations. In addition to configuring an application for deployment, the DeploymentManager is responsible for establishing a connection to a J2EE server. The DeploymentManager implementation is accessed using a DeploymentFactory.
The following sections provide information on how a DeploymentManager connects to a server instance:
Use the DeploymentFactory.getDeploymentManager method to get a DeploymentManager object. This method takes a URI, user ID and password as arguments. The URI has the following patterns:
deployer:WebLogic<:host:port>
deployer:WebLogic.remote<:host:port>
deployer:WebLogic.authenticated<:host:port>
When connecting to an Administration Server, the URI must also include the host and port, such as deployer:WebLogic:localhost:7001. See Understanding DeploymentManager URI Implementations.
The following provides additional information on DeploymentManager arguments:
When obtaining a disconnected DeploymentManager, you do not need to include the host:port because there is no connection to an Administration Server. For example, the URI can be deployer:WebLogic.
The user ID and password arguments are ignored if the deployment tool uses a pre-authenticated DeploymentManager.
You can access the URI of any DeploymentManager implementation using the DeploymentFactory.getUris() method. getUris is an extension of DeploymenFactory.
Depending on the URI specified during allocation, the DeploymentManager object will have one of the following characteristics:
deployer:WebLogic: The DeploymentManager is running locally on an Administration Server and any files referenced during the deployment session are treated as if they are local to the Administration Server.
deployer:WebLogic.remote: The DeploymentManager is running remotely to the WebLogic Server Administration Server and any files referenced during the deployment session are treated as being remote to the Administration Server and may require uploading. For example, a distribute operation includes uploading the application files to the Administration Server.
deployer:WebLogic.authenticated: This is an internal, unpublished URI, usable by applications such as a console servlet that is already authenticated and has access to the domain management information. The DeploymentManager is running locally on a WebLogic Administration Server and any files referenced during the deployment session are treated as if they are local to the Administration Server.
You can explicitly force the uploading of application files by using the WebLogicDeploymentManager method enableFileUploads() method.
DeploymentManagers are either connected or disconnected. Connected DeploymentManagers imply a connection to a WebLogic Server Administration Server. This connection is maintained until it is explicitly disconnected or the connection is lost. If the connection is lost, the DeploymentManager reverts to a disconnected state.
Explicitly disconnecting a DeploymentManager is accomplished using the DeploymentManager.release method. There is no corresponding method for reconnecting the DeploymentManager. Instead the deployment tool must allocate a new DeploymentManager.
Note:
Allocating a newDeploymentManager does not affect any configuration information being maintained within the tool through a DeploymentConfiguration object.Most of the functional components of a DeploymentManager are defined in the J2EE Deployment API specification. However, Oracle has extended the DeploymentManager interface with the capabilities required by existing WebLogic Server-based deployment tools. Oracle WebLogic Server deployment extensions are documented at weblogic.deploy.api.spi.WebLogicDeploymentManager.
The JSR-88 programming model revolves around employing TargetModuleID objects (TargetModuleIDs) and ProgressObject objects. In general, target modules are specified by a list of TargetModuleIDs which are roughly equivalent to deployable root modules and sub-module level MBeans. The DeploymentManager applies the TargetModuleIDs to deployment operations and tracks their progress. A deployment tool needs to query progress using a ProgressObject returned for each operation. When the ProgressObject indicates the operation is completed or failed, the operation is done.
The following sections provide an overview of WebLogic DeploymentManager features:
WebLogic Server allows for a DeploymentOptions argument (weblogic.deploy.api.spi.DeploymentOptions) which supports the overriding of certain deployment behaviors. The argument may be null, which provides standard behavior. Some of the options supported in this release are:
admin (test) mode
Retirement Policy
Staging
See DeploymentOptions Javadoc.
Distribution of new applications results in:
the application archive and plan is staged on all targets.
the application being configured into the domain.
Note:
Redistribution honors the staging mode already configured for an application.The standard distribute operations does not support version naming. WebLogic Server provides WebLogicDeploymentManager to extend the standard with a distribute operation that allows you to associate a version name with an application.
The ProgressObject returned from a distribute provides a list of TargetModuleIDs representing the application as it exists on the target servers. The targets used in the distribute are any of the supported targets. The TargetModuleID represents the application's module availability on each target.
For new applications, TargetModuleIDs represent the top level AppDeploymentMBean objects. TargetModuleIDs do not have child TargetModuleIDs based on the modules and sub-modules in the application since the underlying MBeans would only represent the root module. For pre-existing applications, the TargetModuleIDs are based on DeployableMBeans and any AppDeploymentMBean and SubAppDeploymentMBean in the configuration.
If you use the distribute(Target[],InputStream,InputStream) method to distribute an application, the archive and plan represented by the input streams are copied from the streams into a temporary area prior to deployment which impacts performance.
The standard start operation only supports root modules; implying only entire applications can be started. Consider the following configuration.
<AppDeployment Name="myapp"> <SubDeployment Name="webapp1", Targets="serverx"/> <SubDeployment Name="webapp2", Targets="serverx"/> </AppDeployment>
The TargetModuleID returned from getAvailableModules(ModuleType.EAR) looks like:
myapp on serverx (implied) webapp1 on serverx webapp2 on serverx
and start(tmid) would start webapp1 and webapp2 on serverx.
To start webapp1, module level control is required. Configure module level control by manually creating a TargetModuleID hierarchy.
WebLogicTargetModuleID root = dm.createTargetModuleID("myapp",ModuleType.EAR,getTarget(serverx)); WebLogicTargetModuleID web = dm.createTargetModuleID(root,"webapp1",ModuleType.WAR); dm.start(new TargetModuleID[]{web});
This approach uses the TargetModuleID creation extension to manually create an explicit TargetModuleID hierarchy. In this case the created TargetModuleID would look like
myapp on serverx (implied) webapp1 on serverx
The start operation does not modify the application configuration. Version support is built into the TargetModuleIDs, allowing the user to start a specific version of an application. Applications may be started in normal or administration (test) mode.
The deploy operation combines a distribute and start operation. Web applications may be deployed in normal or administration (test) mode. You can specify application staging using the DeploymentOptions argument. deploy operations use TargetModuleIDs instead of Targets for targeting, allowing for module level configuration.
The deploy operation may change the application configuration based on the TargetModuleIDs provided.
The standard stop operation only supports root modules; implying only entire applications can be stopped. See the Application Start.
Oracle provides versioning support, allowing you to stop a specific version of an application. The stop operation does not modify the application configuration. See Version Support.
The standard undeploy operation removes an application from the configuration, as specified by the TargetModuleIDs. Individual modules can be undeployed. The result is that the application remains on the target, but certain modules are not actually configured to run on it. See the Application Start section for more detail on module level control.
The WebLogicDeploymentManager extends undeploy in support of removing files from a distribution. This is a form of in-place redeployment that is only supported in Web applications, and is intended to allow you to remove static pages. See Version Support.
Standard redeployment support only applies to entire applications and employs side-by-side versioning to ensure uninterrupted session management. The WebLogicDeploymentManager extends the redeploy() method and provides the following additional support:
The in-place redeployment strategy works by immediately replacing a running application's deployment files with updated deployment files, such as:
Partial redeployment which involves adding or replacing specific files in an existing deployment.
Updating a configuration using a redeployment of a deployment plan
A DeploymentManager implements the JSR-88 specification and restricts operations to root modules. Module level control is provided by manually constructing a module specific TargetModuleID hierarchy using WebLogicDeploymentManager.createTargetModuleID
When a new version of an application is redeployed, the old version should eventually be retired and undeployed. There are 2 policies for retiring old versions of applications:
(Default) The old version is retired when new version is active and old version finishes its in-flight operations.
The old version is retired when new version is active, retiring the old after some specified time limit of the new version being active.
Note:
The old version is not retired if the new version is in administration (test) mode.Side-by-side versioning is used to provide retirement extensions, as suggested in the JSR-88 redeployment specification. This ensures that an application can be redeployed without interruption in service to its current clients. Details on deploying side-by-side versions can be found in "Redeploying Applications in a Production Environment" in Deploying Applications to Oracle WebLogic Server.
A Web application may be started in normal or administration (test) mode. Normal mode indicates the Web application is fully accessible to clients. Administration (test) mode indicates the application only listens for requests using the admin channel. Administration (test) mode is specified by the DeploymentOptions argument on the WebLogic Server extensions for start, deploy and redeploy. See DeploymentOptions Javadoc.
Use ProgressObjects to determine deployment state of your applications. These objects are associated with DeploymentTaskRuntimeMBeans.ProgressObjects support the cancel operation but not the stop operation.
ProgessObjects are associated with one or more TargetModuleIDs, each of which represents an application and its association with a particular target. For any ProgressObject, its associated TargetModuleIDs represent the application that is being monitored.
The ProgressObject maintains a connection with the deployment framework, allowing it to provide a deployment tool with up-to-date deployment status. The deployment state transitions from running to completed or failed only after all TargetModuleIDs involved have completed their individual deployments. The resulting state is completed only if all TargetModuleIDs are successfully deployed.
The released state means that the DeploymentManager was disconnected during the deployment. This may be due to a manual release, a network outage, or similar communication failures.
Example 4-2 shows how a ProgressObject can be used to wait for a deployment to complete:
Example 4-2 Example Code to Wait for Completion of a Deployment
package weblogic.deployer.tools;
import javax.enterprise.deploy.shared.*;
import javax.enterprise.deploy.spi.*;
import javax.enterprise.deploy.spi.status.*;
/**
* Example of class that waits for the completion of a deployment
* using ProgressEvent's.
*/
public class ProgressExample implements ProgressListener {
private boolean failed = false;
private DeploymentManager dm;
private TargetModuleID[] tmids;
public void main(String[] args) {
// set up DeploymentManager, TargetModuleIDs, etc
try {
wait(dm.start(tmids));
} catch (IllegalStateException ise) {
//... dm not connected
}
if (failed) System.out.println("oh no!");
}
void wait(ProgressObject po) {
ProgressHandler ph = new ProgressHandler();
if (!po.getDeploymentStatus().isRunning()) {
failed = po.getDeploymentStatus().isFailed();
return;
}
po.addProgressListener(ph);
ph.start();
while (ph.getCompletionState() == null) {
try {
ph.join();
} catch (InterruptedException ie) {
if (!ph.isAlive()) break;
}
}
StateType s = ph.getCompletionState();
failed = (s == null ||
s.getValue() == StateType.FAILED.getValue());
po.removeProgressListener(ph);
}
class ProgressHandler extends Thread implements ProgressListener {
boolean progressDone = false;
StateType finalState = null;
public void run(){
while(!progressDone){
Thread.currentThread().yield();
}
}
public void handleProgressEvent(ProgressEvent event){
DeploymentStatus ds = event.getDeploymentStatus();
if (ds.getState().getValue() != StateType.RUNNING.getValue()) {
progressDone = true;
finalState = ds.getState();
}
}
public StateType getCompletionState(){
return finalState;
}
}
}
The following sections provide information on how to target objects:
The standard modules types are defined by javax.enterprise.deploy.shared.ModuleType. This is extended to support WebLogic Server-specific module types: JMS, JDBC, INTERCEPT and CONFIG.
JSR-88 defines a secondary descriptor as additional descriptors that a module can refer to or make use of. These descriptors are linked to the root DConfigBean of a module such that they are visible to a Java Beans based tool as they are child properties of a DConfigBeanRoot object. Secondary descriptors are automatically included in the configuration process for a module.
An EJB or Web application may include a webservers.xml descriptor. If present, the module is automatically configured with the WebLogic Server equivalent descriptor for configuring Web services as secondary descriptors. The deployment plan includes these descriptors as part of the module, not as a separate module.
CMP support in EJBs is configured using RDBMS descriptors that are identified for CMP beans in the weblogic-ejb-jar.xml descriptor. The RDBMS descriptors support CMP11 and CMP20. Any number of RDBMS descriptors may be included with an EJB module. Provide these descriptors in the application archive or configuration area (approot/plan). Although they are not created by the configuration process, they may be modified like any other descriptor. RDBMS descriptors are treated as secondary descriptors in the deployment plan.
JDBC modules are described by a single deployment descriptor with no archive. If the module is part of an EAR, the JDBC descriptors are specified in weblogic-application.xml as configurable properties. You can deploy JDBC modules to WebLogic servers and clusters. Configuration changes to JDBC descriptors are handled as overrides to the descriptor.
If a JDBC module is part of an EAR, its configuration overrides are incorporated in the deployment plan as part of the EAR, not as separate modules.
JMS modules are described by a single deployment descriptor with no archive. If the module is part of an EAR, the JMS descriptors are specified in weblogic-application.xml as configurable properties. JMS modules are deployed to JMS servers. Configuration changes to JMS descriptors are handled as overrides to the descriptor. JMS descriptors may identify "targetable groups". These groups are treated as sub-modules during deployment.
If the JMS module is part of an EAR, its configuration overrides are incorporated in the deployment plan as part of the EAR, not as separate modules.
Intercept modules are described by a single deployment descriptor with no archive. If the module is part of an EAR, the Intercept descriptors are specified in weblogic-application.xml as configurable properties. Intercept modules are deployed to WebLogic Server servers and clusters. Configuration changes to Intercept descriptors are handled as overrides to the descriptor.
If the Intercept module is part of an EAR, its configuration overrides are incorporated in the deployment plan as part of the EAR, not as separate modules.
The J2EE Deployment API specification's definition of a target does not include any notion of its type. WebLogic Server supports standard modules and Oracle-specific module types as valid deployment targets. Target support is provided by the weblogic.deploy.api.spi.WebLogicTarget and weblogic.deploy.api.spi.WebLogicTargetType classes. See Module Types.
The TargetModuleID objects uniquely identify a module and a target it is associated with. TargetModuleIDs are the objects that specify where modules are to be started and stopped. The object name used to identify the TargetModuleID is of the form:
Application=parent-name,Name=configured-name,Target=target-name,TWebLogicTargetType=target-type
where
parent-name is the name of the ear this module is part of.
configured-name is the name used in the WebLogic Server configuration for this application or module
target-name is the server, cluster or virtual host where there module is targeted
target-type is the description of the target derived from Target.getDescription.
TargetModuleID.toString() will return this object name.
TargetModuleID is extended by weblogic.deploy.api.spi.WebLogicTargetModuleID. This class provides the following additional functionality:
getServers—servers associated with the TargetModuleID's target
isOnCluster—whether target is a cluster
isOnServer—whether target is a server
isOnHost—whether target is a virtual host
isOnJMSServer—whether target is a JMS server
getVersion—the version name
createTargetModuleID—factory for creating module specific targeting
WebLogicTargetModuleID is defined in more detail in the Javadocs.
The WebLogicDeploymentManager is also extended with convenience methods that simplify working with TargetModuleIDs. They are:
filter—returns a list of TargetModuleIDs that match on application, module, and version
getModules—creates TargetModuleIDs based on an AppDeploymentMBean
TargetModuleIDs have a hierarchical relationship based on the application upon which they are based. The root TargetModuleID of an application represents an EAR module or a stand-alone module. Child TargetModuleIDs are modules that are defined by the root module's descriptor. For EARs, these are the modules identified in the application.xml descriptor for the EAR. JMS modules may have child TargetModuleIDs (sub-modules) as dictated by the JMS deployment descriptor. These may be children of an embedded module or the root module. Therefore, JMS modules can have three levels of TargetModuleIDs for an application.
Typically, you get TargetModuleIDs in a deployment operation or one of the DeploymentManager.get*Modules() methods. These operations provide TargetModuleIDs based on the existing configuration. In certain scenarios where more specific targeting is desired than is currently defined in the configuration, you may use the createTargetModuleID method. This method creates a root TargetModuleID that is specific to a module or sub-module within the application. This TargetModuleID can then be used in any deployment operation. For operations that include the application archive, such as deploy(), using one of these TargetModuleIDs may result in the application being reconfigured. For example:
<AppDeployment Name="myapp", Targets="s1,s2"/>
The application is currently configured for all modules to run on s1 and s2. To provide more specific targeting, a deployment tool can do the following:
Target s1 = find("s1",dm.getTargets()); // find() is not part of this api WebLogicTargetModuleID root = dm.createTargetModuleID("myapp",ModuleType.EAR,s1); WebLogicTargetModuleID web = dm.createTargetModuleID(root,"webapp1",ModuleType.WAR); dm.deploy(new TargetModuleID[]{web},myapp,myplan,null);
myapp is reconfigured and webapp is specifically targeted to only run on s1. The new configuration is:
<AppDeployment Name="myapp", Targets="s1,s2"> <SubDeployment Name="webapp", Targets="s1"/> </AppDeployment>
Consider the deployment of a stand-alone JMS module, one that employs sub-modules. The module is defined by the file, simple-jms.xml, which defines sub-modules, sub1 and sub2. The descriptor is fully configured for the environment hence no deployment plan is required, although the scenario described here would be the same if there was a deployment plan.
The tool to deploy this module performs the following steps:
// init the jsr88 session. This uses a WLS specific helper class, // which does not employ any WLS extensions DeploymentManager dm = SessionHelper.getDeploymentManager(host,port,user,pword); // get list of all configured targets // The filter method is a location where you could ask the user // to select from the list of all configured targets Target[] targets = filter(dm.getTargets()); // the module is distributed to the selected targets ProgressObject po = dm.distribute(targets,new File("jms.xml"),plan); // when the wait comes back the task is done waitForCompletion(po); // It is assumed here that it worked (there is no exception handling) // the TargetModuleIDs (tmids) returned from the PO correspond to all the // configured app/module mbeans for each target the app was distributed to. // This should include 3 tmids per target: the root module tmid and the // submodules' tmids. TargetModuleID[] tmids = po.getResultTargetModuleIDs(); // then to deploy the whole thing everywhere you would do this po = dm.start(tmids); // the result is that all sub-modules would be deployed on all the selected // targets, since they are implicitly targeted wherever the their parent is // targeted // To get sub-module level deployment you need to use WebLogic Server // extensions to create TargetModuleIDs that support module level targeting. // The following deploys the topic "xyz" on a JMS server WebLogicTargetModuleID root = dm.createTargetModuleID(tmids[i].getModuleID(),tmids[i],jmsServer); WebLogicTargetModuleID topic = dm.createTargetModuleID(root,"xyz",WebLogicModuleType.JMS); // now we can take the original list of tmids and let the user select // specific tmids to deploy po = dm.start(topic);