Update an asset using programming

Update an asset using programming

We can update an asset by adding, deleting, or updating a single file or Java EE module, or by merging multiple files or Java EE modules into an asset. We can also update an asset by replacing the entire asset.

This task assumes a basic familiarity with command framework programming. Read about command framework programming in the API documentation.
Before we can update an asset, you must have imported the asset.
We can update an asset using programming, the console, or wsadmin.sh.

Specify the assetID parameter of the asset that you are updating. In addition, specify the operation parameter. Wether or not specify the contents and contenturi parameters depends on the operation specified.
You modify one or more files or module files of an asset with this task. You also update the asset binary file, but do not update the composition units that the system deploys with this asset as a backing object.
Perform the following tasks to update an asset 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.

Create and set up the command that updates an asset.

Set the parameter for the asset that you are updating.

Set the operation parameter.

Set the contents parameter unless the operation is set to delete.

Set the contenturi parameter if the operation is set to add, update, or addupdate.

Call the processCommandParameters method in the asynchronous command client to process the command parameters.
The command framework asynchronous command model requires this call.

Call the asynchronous command client to run the command to update an asset.
You could 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 asset is updated.

Example

The following example shows how to update 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 EditBLA {

    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 following lines to get soapClient soap client if
            // you are going to use the local command manager. 
            // Comment out the lines to and including             // CommandMgr cmdMgr = 
            // CommandMgr.getClientCommandMgr(soapClient);

            String host = "localhost"; // Change to the host if it is not 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 an 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.
            // This example creates a new session. We can replace the           // following code to use an existing session that has been 
            // created.
            String id = Long.toHexString(System.currentTimeMillis());
            String user = "content" + id;
            Session session = new Session(user, true);

            // If we do not use the command handler, 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 updates the asset.
            String cmdName = "updateAsset";
            AdminCommand cmd = cmdMgr.createCommand(cmdName);
            cmd.setConfigSession(session); // Update an asset
                                           // using the session                                            // created.
            System.out.println("\nCreated " + cmdName);

            // Set the required assetID parameter.
            // Examples of valid formats for the assetID parameter:
            // - aName 
            // - assetname=aName
            // - WebSphere:assetname=aName
            // This parameter accepts an incomplete ID as long as the 
            // incomplete ID can resolve to a unique asset within the 
            // business-level application.
            String assetID = "asset1.zip";   // Replace asset1.zip with the 
                                             // value of the assetID parameter.
            cmd.setParameter("assetID", assetID);

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

            // Set the required operation parameter.
            // Possible operation values are add, addupdate, delete, merge, // replace, and update.
            // Use the add value to add a new file or Java EE module to the asset.
            // Use the addupdate value to add a new file or Java EE module to the asset, or 
            // update an existing file or Java EE module.
            // Use the delete value to delete an existing file or Java EE module in the asset.
            // Use the merge value to provide a partial update with multiple 
            // additions, updates, or deletions.
            // Use the replace value for a full update to replace all the contents.
            // Use the update value to update an existing file or Java EE module in the asset.
            String op = "add"; // Replace the add value with the operation value.
            cmd.setParameter("operation", op);

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

            // Set the contents parameter.
            // Required unless the operation is set to 
            // delete.
String contents = "c:\assets\abc.txt";
(zos)(iseries)
String contents = "/assets/abc.txt"
            
            cmd.setParameter("contents", contents);

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

            // Set the contenturi parameter.
            // Required for the           //   add, addupdate, update, or delete operations.
            String contenturi = "abc.txt";  // URI within the asset to                                             // place the new file. Replace
                                            // with the value.
            cmd.setParameter("contenturi", contenturi);

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

            // 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("Throwing an exception from " +       
                   "asyncCmdClientHelper.processCommandParameters(cmd).");
                th.printStackTrace();
                System.exit(-1);
            }

            // Run the command.
            asyncCmdClientHelper.execute(cmd);
            System.out.println("\nCompleted command execution");

            CommandResult result = cmd.getCommandResult();
            if (result != null) {
                if (result.isSuccessful()) {
                    System.out.println("\nCommand executed successfully "
                           + "with result\n" + result.getResult());
                }
                else {
                    System.out.println("\nCommand executed 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

We can do other tasks associated with assets in business-level applications, such as adding or deleting other assets, listing assets, exporting assets, and so on.

Related concepts

Additional APIs

Related tasks

Deploy and administering business-level applications
Administer business-level applications using programming
Import an asset using programming
Export an asset using programming
Listing assets using programming
Edit an asset using programming
View an asset using programming
Delete an asset using programming
Manage assets

BLAManagement (AdminTask)