Introduction

The application management feature in WebSphere© Application Server V5 provides a Java^TM programmatic interface for installation and management of J2EE applications. WebSphere Application Server V5 is a J2EE 1.3 specification compliant application server and, as such, it supports deployment of J2EE applications that are compliant with J2EE 1.3, as well as with the J2EE 1.2 specification. The application management functionality offered by WebSphere Application Server is exposed through its administrative programs: the wsadmin scripting interface, and the Web-based administrative console. This article will focus primarily on the programmatic interfaces for managing J2EE applications.

While this article is self-contained, you should familiarize yourself with Part 1 and Part 2 of this series to become familiar with WebSphere Application Server administration basics, and with Part 5 to learn more about programmatic configuration of WebSphere Application Server artifacts other than J2EE applications. The WebSphere Application Server Javadoc is also a helpful document for this topic, with information on the com.ibm.websphere.management.application package which contains all the application management APIs.

Back to top

Application preparation

J2EE applications and modules include an XML-based deployment descriptor that specifies various J2EE artifacts (such as EJB definitions, security role definitions, ejb-refs, resource-refs, etc.) pertaining to the application or the modules. These artifacts define various unresolved references that are used by the application logic. J2EE specification requires that these artifacts be mapped to J2EE platform-specific (e.g. WebSphere-specific) information during deployment of J2EE applications on such platforms.

The Application Assembly Tool, installed as a part of the WebSphere Application Server product, as well as the application management support provided by WebSphere systems management, facilitate collection of such WebSphere-specific information that is used to resolve references defined in various deployment descriptors in a J2EE application. This information is stored in the application EAR file and is co-located with the deployment descriptors. Figure1 shows the structure of an EAR file that is populated with WebSphere-specific deployment information.

WebSphere application management architecture provides a set of classes that allows deployers to collect WebSphere-specific deployment information (hereafter called binding information) and store it in the application EAR file. Such an EAR file can then be installed into a WebSphere configuration, using application management interfaces described later in the Installing applications section. The rest of this section explains, using a programming example, how an EAR file can be populated with binding information.

The major steps in the application preparation process are:

1. Create AppDeploymentController instance
2. Obtain AppDeploymentTask instances
3. Manipulate task data as necessary
4. Save task data back into EAR file and obtain install options.

1. Create AppDeploymentController

The AppDeploymentController takes an EAR file as an argument and creates a sequence of steps, represented by AppDeploymentTask objects (hereafter called tasks). The tasks are typically presented to the deployer to collect binding information, or are manipulated programmatically. The following code excerpt shows how to create an AppDeploymentController instance:

// create preferences to pass in the locale information 

Hashtable prefs = new Hashtable(); 
prefs.put(AppConstants.APPDEPL_LOCALE, Locale.getDefault()); 
           
// create a controller instance for EAR file 
// specified by a fully-qualified path in earName 
AppDeploymentController flowController =
AppManagementFactory.readArchive (earName, prefs); 

2. Obtain AppDeploymentTask instances

After creating AppDeploymentController, you can iterate over the task objects that it creates. Each task collects a specific kind of binding information for various modules in the application or for the application itself. A task has the following attributes (and corresponding getters/setters as applicable):

The table below lists various task names that are typically created by AppDeploymentController for a J2EE 1.3 (and J2EE 1.2) application. You may notice more tasks if the application contains WebSphere enterprise extensions.

The URI column in various tasks uniquely identifies a module in the application using the format <moduleURI,ddURI> as its value, where moduleURI is the module file name defined in the application's deployment descriptor, and ddURI is the URI of the deployment descriptor within the module (for standard deployment descriptor) or the URI of the alternate deployment descriptor for the module, as defined in the application's deployment descriptor. For example, if an application has a Web module in MyWeb.war and the module uses a standard deployment descriptor, then the value of the URI column in various tasks for this module is MyWeb.war,WEB-INF/web.xml. Thus the URI column value always guarantees a unique identification of a module.

The following code excerpt shows how to obtain tasks from AppDeploymentController:

AppDeploymentTask task =flowController.getFirstTask();
 while (task != null) 
{
    // manipulate task data as necessary
    task = flowController.getNextTask();
} 

3. Manipulate task data

Using task name, task column names, and the J2EE artifact for which binding information is to be supplied, the task data can be modified if the corresponding column is marked as mutable. The following sample code shows how binding information can be supplied for a specific task. In this example, we are specifying users for a security role: consider that the application has a security role named Role1, and that you need to assign users User1 and User2 to that role:

if (task.getName().equals ("MapRolesToUsers") && !task. isTaskDisabled()) 
{ 
       // find out column index for role and user column 
       // refer to the table above to find the column names
       int roleColumn = -1;
       int userColumn = -1;
       String[] colNames = task.getColumnNames();
       for (int i=0; i < colNames.length; i++)
       { 
            if (colNames[i].equals ("role"))
            	roleColumn = i;
            else if (colNames[i].equals ("role.user"))
               userColumn = i; 
       } 
            
       // iterate over task data starting at row 1 as row0 is
       // column names
       String[][]data = task.getTaskData();
       for (int i=1; i < data.length; i++)
       {
            if (data[i][roleColumn].equals ("Role1")) 
            {
            	data[i][userColumn]="User1|User2";
               break;
            }
       } 
       
       // now that the task data is changed, save it back
       task.setTaskData (data);
} 

Similar logic can be used to specify all other types of binding information, such as JNDI names for EJBs, virtual host names for Web modules, etc., in various tasks. (The task information and the sample code above do not allow you to collect binding information for application client modules. You need to use the Client Configuration tool shipped with WebSphere Application Server to configure application clients.)

4. Save EAR file and obtain install options

After all the necessary binding information has been supplied in various tasks, the task data should be saved back into the EAR file so that the populated EAR file can be installed into the WebSphere configuration. In addition to the binding information that is stored in the EAR file, there are several other deployment options that are collected by tasks, such as AppDeploymentOptions, EJBDeployOptions, and MapModulesToServers. These options are not saved in the EAR file but should be passed when the application is installed into the WebSphere configuration. After the task data is manipulated as necessary and the EAR file is saved, these options can be obtained from AppDeploymentController as a hash table. Alternately, these options can be passed directly during application installation, as explained in the Installing applications section below, and in the javadoc for installApplication API of com.ibm.websphere.management.application.AppManagement interface.

The following code shows how to save the task data into the EAR file and get generated installation options:

// the following line of code saves the task data
// in the EAR file specified as earName in step 1
flowController.saveAndClose();
 
// get the installation options
Hashtable options = flowController.getAppDeploymentSavedResults();

Back to top

Managing applications

The application management support in WebSphere Application Server provides functions such as installing and uninstalling applications, editing of binding information for installed applications, updating the entire application, exporting the application, etc. This functionality is provided through the com.ibm.websphere.management.application.AppManagement interface, which is exposed as a JMX-based AppManagement MBean in WebSphere Application Server, and can be accessed by code running on the server or in a standalone administrative client program. When using WebSphere Application Server Network Deployment (explained in Part 1 of this article series), the AppManagement MBean is only present in the deployment manager that facilitates centralized configuration and administration. Similar to config service (explained in Part 5), the AppManagement functions can also be accessed in the absence of WebSphere Application Server. This mode, known as Local Mode, is particularly useful for installing J2EE applications as a part of product installation.

AppManagementProxy

The com.ibm.websphere.management.application.AppManagementProxy class provides uniform access to application management functionality, regardless of whether it is accessed from the server process, administrative client process, or a standalone Java program in the absence of WebSphere Application Server. The following code excerpts demonstrate how to obtain an AppManagementProxy instance in a variety of cases:

1. To access AppManagement function from the code that is running in WebSphere Application Server (e.g. as a custom service), use:

   AppManagement appMgmt = AppManagementProxy. getJMXProxyForServer();

   
   You can then use the AppManagement interface to perform operations such as installation of applications.
2. To access application management functionality from outside WebSphere Application Server via a JMX-based AppManagement MBean, you need to first create an AdminClient to establish connection to the WebSphere server. Part 2 of this article series on Writing Your Own Administration Programs explains how you can obtain an AdminClient object:

   AdminClient adminClient = .... // create AppManagement proxy object AppManagement appMgmt = AppManagementProxy. getJMXProxyForClient (adminClient);

   
   Figure2 shows the request flow when using AppManagementProxy object to communicate with AppManagement MBean.
   Figure 2. Using AppManagementProxy from remote client
   
   
3. To access application management functions when WebSphere Application Server is not running (local mode), you can create AppManagementProxy using the following code:

   AppManagement appMgmt = AppManagementProxy. getLocalProxy ();

   
   
   • When running in Local Mode you must set the system property com.ibm.ws.management.standalone to true. If you want to modify configuration documents in a non-default location, you also need to set the location of the config directory through the system property was.repository.root.
   • Although application management functions can be used with or without WebSphere Application Server running, do not access application management functions in local mode and via AppManagement MBean concurrently, as it is possible that updates made using these modes can collide and break the integrity of the WebSphere Application Server configuration.

After obtaining AppManagementProxy, you can perform various management functions such as installation, uninstallation, editing, etc. However, before diving into the details of various application management functions, it is necessary to understand how the session concept from config service (explained in Part 5 of this article series) works with application management functions.

Session sharing

Config service allows you to create a session, which is a temporary staging area where all the configuration modifications can be saved. Saving the session saves all the updates from the session into the WebSphere configuration repository. The application management logic supports session sharing with config service. Thus, it is possible to make all the application-specific changes in the same session as the one created by config service. Saving such a session saves all the updates, including the ones that are application-specific. All the methods on the AppManagement interface take the last parameter as (String workspaceID). Here is a sample API:

public void installApplication (String localEarPath,
            String appName, Hashtable properties, String workspaceID)
            throws AdminException; 

(The exceptions are setApplicationInfo and setModuleInfo APIs, which do take (String workspaceID) as a parameter, but not as the last parameter.)

Passing a null value for this parameter indicates that there is no session sharing, and thus configuration changes made as a result of this operation are always saved in the configuration repository if the operation succeeds. The following steps demonstrate session sharing with config service:

1. Obtain config service (refer to Part 5: Obtain config service):

   configService = ...

   
   
2. Create a session (refer to Part 5: Create a session):

   Session session = ...

   
   
3. Pass in the session information to AppManagement:

   appMgmt = ... appMgmt.installApplication (earPath, appName, properties, session.toString());

   
   
4. Save the session after all necessary changes are made:

   configService.save(session, false);

   
   

Installing applications

An EAR file that is populated with WebSphere-specific binding information can be installed into a WebSphere configuration using installApplication API (installApplicationLocal API, if application management logic is running in local mode) on the AppManagement interface.

The javadoc for installApplication API on com.ibm.websphere.management.application.AppManagement interface explains various options that can be passed during application installation, and also shows a code sample. These options can also be collected during the Application Preparation phase.

Configuration repository document structure

When the session in which the application deployment takes place is saved, the application EAR file, as well as the application metadata (which includes deployment descriptor and WebSphere-specific bindings and deployment descriptor extensions), are stored in the configuration repository. Additionally, a deployment.xml file is also created per deployed application. It contains information about various deployment attributes and module-to-target (server/cluster) mappings. These files are stored in the configuration in the following directory structure:

$WAS_HOME/config/cells/cellName/applications/appName.ear/appName.ear

$WAS_HOME/config/cells/cellName/applications/appName.ear/deployments/
appName/<<all metadata files>> 
$WAS_HOME/config/cells/cellName/applications/appName.ear/deployments/
appName/deployment.xml

EAR extraction in install destination

After the deployment-specific files are created in the WebSphere configuration repository (and in the case of WebSphere Application Server Network Deployment configuration, as the master repository configuration is synchronized with each node that the application modules are expected to run on), the application EAR file is extracted in the install destination location of the target node. This location is specified during application installation using option AppConstants.APPDEPL_INSTALL_DIR. The WebSphere Application Server run time reads the application business logic (e.g. EJB classes, servlets, JSPs) from the install destination location, while serving application client requests. However, the application metadata (e.g. deployment descriptor, WebSphere-specific bindings) is read by the server run time only during application startup. The metadata is read either from the configuration repository or from the install destination, depending upon the APPDEPL_USE_BINARY_CONFIG option specified during application installation. This option is saved in deployment.xml as the useMetadataFromBinaries attribute. The default behavior is to read the metadata from the configuration repository.

The default install destination is ${APP_INSTALL_ROOT}/cellName/appName.ear, which is typically $WAS_HOME/installedApps/cellName/appName.ear. If an application is deployed on heterogeneous nodes, then the install destination (AppConstants.APPDEPL_INSTALL_DIR option specified during installation) should be defined as a variable with platform-specific values for individual nodes.

Uninstalling applications

An uninstall operation removes the application from the WebSphere configuration, thus removing it from all the servers and clusters that it runs on. Use uninstallApplication API (uninstallApplicationLocal, if application management logic is running in local mode) to uninstall applications.

To remove an application from a specific server or a cluster, or all the servers on a specific node, you can edit the application information, as explained in the Editing applications section below.

After the application is uninstalled from the WebSphere configuration repository (and in the case of WebSphere Application Server Network Deployment configuration, as the master repository configuration is synchronized with each node that the application modules are deployed on), the EAR file extracted into the install destination of the target node during application installation is deleted. The application is stopped, if running, before the extracted EAR file is deleted from the target node.

Editing applications

Most of the application binding information and application options that are specified during installation can be modified post install by editing an existing application. Certain options, such as EJB deployment, JSP precompilation, etc. are only available at installation time. The edit operation involves following steps:

1. Get information about an installed application

Use the getApplicationInfo method on AppManagement interface to get a list of AppDeploymentTask instances.

// Get information for an application with name appName 
// Pass Locale information as the preference 
Hashtable prefs = new Hashtable();
 prefs.put(AppConstants.APPDEPL_LOCALE, Locale.getDefault()); 
Vector allTasks =  appMgmt.getApplicationInfo (appName, prefs, null); 

2. Manipulate task data as necessary

The Vector returned in the above step contains various AppDeploymentTask instances that are same as the ones explained in the AppDeploymentTask table above. These tasks can be manipulated as explained in the Manipulate task data section.

3. Save changes back into the installed application

Use the setApplicationInfo method on the AppManagement interface to save the changes back to the configuration repository or to the session.

// Set information for an application with name appName 
// Pass Locale information as the preference 
Hashtable prefs = new Hashtable();
prefs.put(AppConstants.APPDEPL_LOCALE, Locale.getDefault());
appMgmt.setApplicationInfo (appName, prefs, null, allTasks); 

After the edited application is saved in the WebSphere configuration repository (and in the case of WebSphere Application Server Network Deployment configuration, as the master repository configuration is synchronized with each node that the application modules are deployed on), the following actions are taken on each target node:

1. If the application is running on the target node, then it is stopped and restarted for the new binding information and deployment options to take effect.
2. If the application is completely removed from the target node by editing the MapModulesToServers task, then the EAR file extracted in the install destination of the target node as a result of application installation is deleted. Conversely, if the application is newly deployed on the application servers of the target node, then the EAR file is extracted in the install destination.

Redeploying (Updating) configurations

It is quite common for application developers to continue to develop and/or fix applications in their development environment even after the application is deployed on a production system. In order to replace a deployed J2EE application with its new revision, the AppManagement interface provides a redeployApplication API (redeployApplicationLocal for local mode). This function uninstalls the deployed application and installs the new revision with the same application name.

If the application is updated in the WebSphere configuration repository while it is running, then the running application is first stopped, the old EAR file is deleted from the install destination, the new EAR file is extracted in the install destination, and the application is restarted.

Starting and stopping applications

WebSphere Application Server provides an ApplicationManager MBean in each application server that allows you to start or stop application on that server. Refer to Part 2 of this article series to learn how to access MBean operations.

Since WebSphere Application Server Version 5.0.1, the AppManagement interface also provides startApplication and stopApplication APIs. These functions start and stop applications on all the targets (servers and clusters) that the application is deployed on.

Back to top

Using ConfigService for AppDeployment options

There are additional attributes related to a deployed application that are not exposed during or after application installation using AppDeploymentTask objects. These attributes are saved in the deployment.xml file that is created in the configuration repository per deployed application. Refer to the sample code in the download section (AppManagementSample1.java) to see how you can use config service to manipulate these attributes. These attributes include:

• startingWeight: specifies the order in which applications are started when the server starts up; applications are started in the ascending order of their starting weight.
• classloaderMode: specifies the order in which classes are searched by the application class loader; default is PARENT_FIRST, which means classes are looked for in the following places in order: process, application, module. The other option is PARENT_LAST.

Refer to javadoc on appdeployment classes to learn about various attributes defined per application deployment.

Back to top

Conclusion

Application management functionality in WebSphere Application Server has been greatly enhanced in Version 5.0. The code samples presented in this article and in the download section demonstrate how to manage J2EE applications programmatically. Check out the URLs in the next section for more information.

Back to top

Download

Name	Size	Download method
AppManagementSample.zip	100KB	FTP|HTTP

Information about download methods

Resources

• WebSphere Application Server Javadoc
  
  
• JMX Javadoc (from Tivoli's tmx4j JMX implementation)
  
  
• Java Management Extensions home page
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Application preparation
• Managing applications
• Using ConfigService for AppDeployment options
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers