Edit a composition unit using programming

WAS v8.5 > Administer applications and their environment > Administer business-level applications using programming

Edit a composition unit using programming

We can edit the configuration information in a composition unit of a business-level application if, for example, to change certain modules in the composition unit configured to run in specific targets. A composition unit is typically created from a business-level application or an asset and contains configuration information that makes the asset runnable.

This task assumes a basic familiarity with command framework programming. Read about command framework programming in the application programming interfaces documentation.

Before we can edit a composition unit of a business-level application, you must have created an empty business-level application, imported an asset, and added a composition unit to the business-level application. We can edit a composition unit of a business-level application using programming, the dmgr console, or wsadmin. This topic describes how to edit a composition unit of a business-level application using programming.

Provide the blaID and cuID parameters to specify the composition unit of the business-level application that you are editing.

Perform the following tasks to edit a composition unit of a business-level application using programming.

Connect to the application server.
The command framework allows the administrative command to be created and run with or without being connected to the application server. This step is optional if the application server is not running.
Create the command manager.
The command manager provides the functionality to create a new administrative command or query existing administrative commands.
Optionally create the asynchronous command handler for listening to command notifications.
Business-level application commands are implemented as asynchronous commands. To monitor the progress of the running command, we have to create an asynchronous command handler to receive notifications the command generates.
Create the asynchronous command client.
An asynchronous command client provides a higher level interface to work with an asynchronous command. If we created an asynchronous command handler in the previous step, the handler is passed to the asynchronous command client. The asynchronous command client forwards the command notification to the handler and helps to control running of the command.
Use the command manager created in a previous step to create and set up the command that edits a composition unit of a business-level application.
The command name is editCompUnit. Use the required blaID and cuID parameters to specify the composition unit of the business-level application that you are editing.
Call the processCommandParameters method in the asynchronous command client to process the command parameters.
The command framework asynchronous command model requires this call.
Set up the command step parameters.
We can edit various composition unit information through steps. The CUOptions step contains data about the composition unit such as its description, starting weight, and start and restart behavior. The MapTargets step contains target information about where to deploy the composition unit. The RelationshipOptions step contains shared library composition units on which this composition unit has a dependency. The ActivationPlanOptions step allows you to change runtime components for each deployable unit. We can edit parameters in these steps.
Call the asynchronous command client to run the command that edits a composition unit of a business-level application.
You might have created an asynchronous command handler to implement the AsyncCommandHandlerIF interface class in a previous step. If we did, the asynchronous command client listens to command notifications and forwards the notifications to the handler. The handler performs any necessary actions while waiting for the command to complete.
If we are editing a composition unit to update a shared library, first manually stop all Java EE applications that depend on that shared library. After updating the shared library, manually restart the Java EE applications. Java EE applications do not automatically restart when a shared library is updated.
Check the command result when the command completes.
When the command finishes running, control is returned to the caller. We can then check the result by calling the command.getCommandResult method.

Results

After you successfully run the code, the composition unit of a business-level application is edited.

Example

The following example shows how to edit a composition unit of a business-level application based on the previous steps. Some statements are split on multiple lines for printing purposes.

package com.ibm.ws.management.application.task;

import java.util.Properties;

import com.ibm.websphere.management.AdminClient;
import com.ibm.websphere.management.AdminClientFactory;
import com.ibm.websphere.management.Session;
import com.ibm.websphere.management.cmdframework.AdminCommand;
import com.ibm.websphere.management.cmdframework.CommandMgr;
import com.ibm.websphere.management.cmdframework.CommandResult;
import com.ibm.websphere.management.cmdframework.CommandStep;
import com.ibm.websphere.management.cmdframework.TaskCommand;
import com.ibm.websphere.management.async.client.AsyncCommandClient;

public class EditCompUnit {

    public static void main(String [] args) {

        try {

            // Connect to the application server.       
            // This step is optional if we use the local       
            // command manager. Comment out the lines to and including             // CommandMgr cmdMgr = CommandMgr.getClientCommandMgr(
            // soapClient);
            // to get the soapClient soap client if we use the local             // command manager. 

            String host = "localhost";
            String port = "8880"; // Change to your port number if it is 
                                  // not 8880.
  
            Properties config = new Properties();
            config.put(AdminClient.CONNECTOR_HOST, host);
            config.put(AdminClient.CONNECTOR_PORT, port);
            config.put(AdminClient.CONNECTOR_TYPE,           
                       AdminClient.CONNECTOR_TYPE_SOAP);
            System.out.println("Config: " + config);
            AdminClient soapClient =                                    
                              AdminClientFactory.createAdminClient(config);
  
            // Create the command manager.
            CommandMgr cmdMgr = CommandMgr.getClientCommandMgr(soapClient);
  
           // Comment out the previous lines to create a client command 
           // manager if you are using a local command manager.     
           // Uncomment the following line to create a local command    
           // manager:
           // CommandMgr cmdMgr = CommandMgr.getCommandMgr();
           System.out.println("\nCreated command manager");
  
           // Optionally create an asynchronoous command handler.
           // Comment out the following line if no further handling            // of command notification is required:
           AsyncCmdTaskHandler listener = new AsyncCmdTaskHandler();
  
           // Create an asynchronous command client.
  
           // Set up the session.
           String id = Long.toHexString(System.currentTimeMillis());
           String user = "content" + id;
           Session session = new Session(user, true);
        
           // If no command handler is used, replace the listener with            // null for the following AsyncCommandClient object:
           AsyncCommandClient asyncCmdClientHelper = new                     
           AsyncCommandClient(session, listener);
           System.out.println("\nCreated async command client");
  
           // Create the command that edits the composition unit.
           String cmdName = "editCompUnit";
           AdminCommand cmd = cmdMgr.createCommand(cmdName);
           cmd.setConfigSession(session); // Edit a certain composition 
                  // unit of a business-level using the session created.
             System.out.println("\nCreated " + cmdName);
        
           // Set the blaID parameter.
           // Examples of valid formats for the blaID parameter are:    
           // - bName   
           // - blaname=bName  
           // - WebSphere:blaname=bName
           // This parameter accepts an incomplete ID as long as the            // incomplete ID can resolve to a unique business-level application.
           String blaID = "bla1";
           cmd.setParameter("blaID", blaID);
        
           System.out.println("\nSet blaID parameter to "
                               + cmd.getParameter("blaID"));
        
           // Set the cuID parameter.
           // Examples of valid formats for the cuID parameter are:     
           // - name  
           // - cuname=name  
           // - WebSphere:cuname=name
           // This parameter accepts an incomplete ID as long as the    
           // incomplete ID can resolve to a unique composition unit  
           // within the business-level application.
           String cuID = "cu1";
           cmd.setParameter("cuID", cuID);
        
           System.out.println("\nSet cuID parameter to "
                               + cmd.getParameter("cuID"));
        
           // Call the asynchronous client helper to process the command parameters.
           try {               
               asyncCmdClientHelper.processCommandParameters(cmd);
               System.out.println("\nCompleted process command " + 
                                    "parameters");
           } catch (Throwable th) {
               System.out.println("Failed from " + 
                   "asyncCmdClientHelper.processCommandParameters(cmd).");
               th.printStackTrace();
               System.exit(-1);
           }
        
           // Set up the step parameters for the CUOptions step.
           // The CUOptions step contains the following arguments that can be edited:
           // description - description for the composition unit 
           // startingWeight - starting weight for the composition unit 
           //                  within the business-level application. 
           // startedOnDistributed - to start composition unit upon distribution 
           //                        to target nodes. 
           // Valid values are true, false. 
           // restartBehaviorOnUpdate - restart behavior for the composition 
           //                 unit when the compostion unit is updated.
           // Valid values are DEFAULT, ALL, NONE 
           String stepName = "CUOptions";
           CommandStep step = ((TaskCommand) cmd).gotoStep(stepName);
        
           // Composition Unit description:
           String description = "cu1 description changed in editCompUnit";
        
           for(int i = 0; i < step.getNumberOfRows(); i++) {
                // Use the following code to change the composition unit step parameters 
                // of the CUOptions step. Change your set of step parameters 
                // as required by your scenario.
                
                // For example, set the description.
                step.setParameter("description", description, i);
                System.out.println("\nSet description parameter to " +
                                   step.getParameter("description", i));
           }
        
           // Set up the step parameters for the MapTargets step
           stepName = "MapTargets";
           step = ((TaskCommand) cmd).gotoStep(stepName);
        
           // In this step the server parameter is required.
           // server - target(s) to deploy the composition unit. The default is server1. 
           //          To add an additional target to the existing 
           //          target, add a prefix to the target with a “+”. To 
           //          delete an existing target, add a prefix to the 
           //          target with a “#“. To replace the existing 
           //          target, use the regular syntax as in the addCompUnit example.
           // Example: server = "#server1+server2";
                     String server = "server1";
        
           for(int i = 0; i < step.getNumberOfRows(); i++) {
                // Use the following code to set the server parameter of the MapTargets step.
                 // Change your set of step parameters as required by your 
                 // scenario.
                
                // For example, set the server.
                step.setParameter("server", server, i);
                System.out.println("\nSet server parameter to " +
                                   step.getParameter("server", i));
           }
    
           // If the RelationshipOptions step is available, the selected            // deployable units of the source asset of the "primary" composition            // unit (that is, the composition unit being added) have dependencies
           // on other assets for which there are matching "secondary" composition            // units in the business-level application.  The RelationshipOptions step is much like            // CreateAuxCUOptions except the required secondary composition            // units already exist.  Also, each RelationshipOptions row maps one            // deployable unit to one or more secondary composition units, whereas,
           // each CreateAuxCUOptions row maps one deployable unit to one            // asset dependency.
           //
           // Each RelationshipOptions row corresponds to one deployable unit
           // with one or more dependency relationships and consists of            // parameter values for the dependency relationships.  Some parameters            // are read-only and some of them are editable.  To edit parameter            // values, use the same approach as that used to edit parameter values            // in the CUOptions step. 
           //
           // The parameters for this step include:
           //
           //  deplUnit – The name of the deployable unit which has the            //             dependency. (Read-only.) 
           //  relationship – Composition unit dependencies in the form of a            //                 list of composition unit IDs.  Composition unit
           //                 IDs are separated by a "plus" sign ("+").  Each ID
           //                 can be fully or partially formed as shown with the            //                 following examples:
           //                     WebSphere:cuname=SharedLib1.jar
           //                     WebSphere:cuname=SharedLib.jar
           //                     SharedLib.jar
           //  matchTarget - Whether the server target for the secondary
           //                composition units are to match the server target for 
           //                the primary composition unit.  The default value            //                is "true".  If the value is set to "false", the            //                secondary composition unit will be created with no            //                target.  The target on the secondary composition unit
           //                can be set at a later time with the editCompUnit
           //                command.
           // for(int i = 0; i < step.getNumberOfRows(); i++) {
                // Use the following if statement to set the relationship and matchTarget parameters                 // of the RelationshipOptions step. Change your set of 
                // step parameters as required by your scenario.
                
                // Uncomment the following code to match the deplUnit and then set 
                // the relationship differently.
                //String deplUnit = (String) step.getParameter(“deplUnit”, 
                //                                                      i);

                //if (deplUnit.equals(“a1.jar”) {
                    // For example, change the relationship for the a1.jar file.
                    //step.setParameter("relationship", relationship, i);
                    //System.out.println("\nSet relationship parameter " +
                    //       "to " + step.getParameter("relationship", i));
                
                    // For example, change matchTarget.
                    //step.setParameter("matchTarget", matchTarget, i);
                    //System.out.println("\nSet matchTarget parameter to "+
                    //             step.getParameter("matchTarget", i));
                //}
           //}
           
           // The addCompUnit command contains thr ActivationPlanOptions step. 
           // The user can set the ActivationPlanOptions step parameters similar to            // the step parameters for the CUOptions step in the previous examples. 
           // The arguments for this step include: 
           // deplUnit – deployable unit URI (read only parameter) 
           // activationPlan - specifies a list of runtime components in the 
           // format of specname=xxxx        

           // Run the command command to edit the composition unit.
           asyncCmdClientHelper.execute(cmd);
           System.out.println("\nCompleted running of the command");
  
           // Check the command result.
           CommandResult result = cmd.getCommandResult();
           if (result != null) {
               if (result.isSuccessful()) {
                   System.out.println("\nCommand ran successfully "
                                  + "with result\n" + result.getResult());
               } 
                else {
                   System.out.println("\nCommand ran with " + 
                                              "Exception");
                   result.getException().printStackTrace();
                   }
           }
       } catch (Exception e) {
           e.printStackTrace();
       }
    }}


package com.ibm.ws.management.application.task;

import com.ibm.websphere.management.cmdframework.provider.CommandNotification;
import com.ibm.websphere.management.async.client.AsyncCommandHandlerIF;

public class AsyncCmdTaskHandler implements AsyncCommandHandlerIF {

    public void handleNotification(CommandNotification notification) {
        // Add our own code here to handle the received notification
        System.out.println("\nEXAMPLE: notification received: " +   
                            notification);
    }}

After you edit the composition unit, we can run the updated business-level application.

Related concepts:

Additional Application Programming Interfaces (APIs)

Deploy business-level applications
Administer business-level applications using programming
Delete a composition unit using programming
View a composition unit using programming
Add a composition unit using programming
List composition units using programming
Manage composition units using wsadmin.sh