Add a composition unit using programming

We can add an asset to a business-level application by creating a composition unit for the asset. A composition unit is typically created from a business-level application or an asset and contains configuration information that makes the asset runnable.

Before we can add a composition unit to a business-level application, you must have created an empty business-level application and imported an asset.

We can add a composition unit to a business-level application using programming, the console, or wsadmin.sh.

When we add a composition to a business-level application, the composition unit is configured for the specified business-level application. The composition unit cannot be shared with other business-level applications.

Perform the following steps to add a composition unit to 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 that 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 adds a composition unit.
The command name is addCompUnit. The blaID and cuSourceID parameters are required parameters that you use to specify composition unit source to be added to the business-level application. Examples of composition unit source are an asset or a business-level application. We can optionally provide deployable units for the composition unit through the deplUnit parameter. If the cuSourceID parameter is a Java EE asset, we can optionally use the cuConfigStrategyFile parameter or the defaultBindingOptions parameter to specify the default bindings. The defaultBindingOptions parameter must match the binding options available for this Java EE asset. To view a list of binding options available for this Java EE asset, look at the AssetOptions step in the viewAsset command. Specify each binding option in an option_name=option_value pair, with multiple pairs separated by a # character.
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 set up composition unit information through various 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 the composition unit is to be deployed. The RelationshipOptions step contains shared library composition units on which this composition unit has dependencies. The ActivationPlanOptions step allows us to specify runtime components for each deployable unit. The CreateAuxCUOptions step contains assets on which this composition unit has dependencies. We can set up parameters in these steps.
Call the asynchronous command client to run the command that adds a composition unit to a business-level application.
We 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.
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 is added to the business-level application.

Example

The following example shows how to import an asset 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 AddCompUnit {

    public static void main(String [] args) {

        try {

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

            String host = "localhost";
            String port = "8880"; // Change to the 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 the asynchronous 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 following listener with             // null for the AsyncCommandClient object.
            AsyncCommandClient asyncCmdClientHelper = new             AsyncCommandClient(session, listener);
            System.out.println("\nCreated async command client");

            // Create the command to add a composition unit to a business-level application.
            String cmdName = "addCompUnit";
            AdminCommand cmd = cmdMgr.createCommand(cmdName);
            cmd.setConfigSession(session); // Add the composition unit using                                           // the session created.
            System.out.println("\nCreated " + cmdName);

            // Set the blaID command 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 cuSourceID command parameter.
            // Examples of valid formats for the cuSourceID parameter:
            // If the source is an asset, examples are:
            // - aName
            // - assetname=aName
            // - WebSphere:assetname=aName
            // If the source is another business-level application, // examples are:
            // - bName
            // - blaname=bName
            // - WebSphere:blaname=bName
            // The cuSourceID command parameter 
            // accepts an incomplete ID as long as the incomplete 
            // ID can resolve to a unique asset or business-level application.
            String cuSourceID = "assetname=asset1.zip";
            cmd.setParameter("cuSourceID", cuSourceID);

            System.out.println("\nSet cuSourceID parameter to "
                               + cmd.getParameter("cuSourceID"));

            // Set the deplUnits command parameter.
            // If the deployable units of an asset are, for example, a.jar and   
            // b.jar, then when you run the addCompUnit command we can 
            // specify deplUnits as a.jar+b.jar. We can specify the whole
            // list, a subset of that list, or "default" to create this composition
            // unit as a shared library. If the deplUnits parameter is not specified, // the deployable units are set the same as that of their asset.
            String deplUnits = "default";
            cmd.setParameter("deplUnits", deplUnits);

            System.out.println("\nSet deplUnits parameter to "
                             + cmd.getParameter("deplUnits"));

            // Call the asynchronous client helper to process 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: 
            // description - description for the composition unit 
            // startingWeight - starting weight for the composition 
            // unit within the business-level application. The default is 1. 
            // startedOnDistributed - to start composition unit upon distribution
            // to target nodes. The default is false. 
            // restartBehaviorOnUpdate - restart behavior for a composition unit when 
            // updating the composition unit.
            // The default is DEFAULT. Valid values are DEFAULT, ALL, and NONE. 
            String stepName = "CUOptions";
            CommandStep step = ((TaskCommand) cmd).gotoStep(stepName);

            // Composition unit name:
            String name = "cu1";

            // Composition unit description:
            String description = "cu1 description";

            for(int i = 0; i < step.getNumberOfRows(); i++) {
               // The following lines change the composition unit name and 
               // description step parameters of the CUOptions step. Change
               // the set of step parameters as required for the 
               // scenario.

               // Set the name.
               step.setParameter("name", name, i);
               System.out.println("\nSet name parameter to " +
                                 step.getParameter("name", i));

               // 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);

            // Specify the targets to deploy the composition unit.
            // The default is server1. Use the + character to  
            // specify multiple targets.
            String server = "server1";

            for(int i = 0; i < step.getNumberOfRows(); i++) {
                // The following lines change the composition unit and 
                // server step parameters of the 
                // MapTargets step. Change the set of step parameters 
                // as required for the scenario.

                // Set the server.
                step.setParameter("server", server, i);
                System.out.println("\nSet server parameter to " +
                                           step.getParameter("server", i));
            }

            // The addCompUnit command might contain the 
            // CreateAuxCUOptions, RelationshipOptions and ActivationPlanOptions
            // steps, depending on the asset content of the assets imported.
            // The CreateAuxCUOptions step is available if the cuSourceID value             // is an asset. The asset includes an asset relationship to an 
            // asset that does not have a matching composition unit in the 
            // business-level application.
            //
            // If the CreateAuxCUOptions 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 no matching composition units
            // in the business-level application. A "secondary" composition unit will be created for each             // of those asset dependencies.
            //
            // Each CreateAuxCUOptions row corresponds to one dependency
            // relationship declaration.  Each row consists of parameter values
            // for the dependency relationship.  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.) 
            //  inputAsset - The asset ID for the source asset of the primary             //               composition unit. (Read-only.) 
            //  cuID - The name of the secondary composition unit to create.
            //  matchTarget - Whether the server target for the secondary
            //                composition unit is 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.
            //
            // 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 that 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.
            // The addCompUnit command contains the 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 to add the composition unit.
            asyncCmdClientHelper.execute(cmd);
            System.out.println("\nCompleted running of 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);
    }
}

What to do next

Start the business-level application to which we added the composition unit. Complete administrative tasks such as viewing or deleting the composition unit.

Related concepts

Additional APIs

Administer business-level applications using programming

Delete a composition unit using programming

Listing composition units using programming

View a composition unit using programming

Edit a composition unit using programming

Manage composition units