Importing an asset using programming

We can import an asset to register the asset with WAS ND and optionally store the asset in WAS repository so that we can later use that asset in a business-level application. An asset represents at least one binary file that implements business logic.

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

We can import an asset using programming, the admin console, or wsadmin.

When you import an asset, you register the asset with WAS ND and optionally store the asset in WAS repository.

You must provide a file path to the source that we are importing. Specify an absolute path name to the source, as the behavior for a relative path is unpredictable.

You can specify a destination location from where the appserver reads the asset file while starting a composition unit created from the asset. The asset is copied to this location when the configuration changes are synchronized with the node. The default asset destination is $WP_PROFILE/installedAssets/asset_name.

You can optionally specify a storage type of FULL, METADATA, or NONE. The default value is FULL, which means that the asset and associated meta data are stored in WAS asset repository. If we specify a storage type of METADATA, the asset is not copied to WAS repository, but associated meta data is stored in WAS repository. If we specify a storage type of NONE, neither the asset nor the asset meta data is stored in WAS asset repository.

For storage types of METADATA and NONE, the asset is expected to reside at the destination file path. Storage types of METADATA and NONE are typically used by development tools which enable iterative development on the copy of the asset in the directory structure of the tool.

Perform the following steps to import an asset using programming.

 

1. Connect to the appserver.

   The command framework allows the admin command to be created and run with or without being connected to the appserver. This step is optional if the application server is not running.

2. Create the command manager.

   The command manager provides the functionality to create a new admin command or query existing administrative commands.

3. 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.

4. 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.

5. Use the command manager createdd in a previous step to set up the command that imports an asset.

   The command name is importAsset. The source parameter is a required parameter that you use to specify the path to the asset. We can optionally provide the storageType parameter to specify how to save the asset in the configuration repository.

6. Call the processCommandParameters method in the asynchronous command client to process the command parameters.

   The command framework asynchronous command model requires this call.

7. Set up the command step parameters.

   We can set parameters in the AssetOptions step that contains data about the asset such as its description, file permission, and relationship with other assets.

8. Call the asynchronous command client to run the command that imports an asset.

   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.

9. 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 imported.

 

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.CommandMgr;
 import com.ibm.websphere.management.cmdframework.AdminCommand;
 import com.ibm.websphere.management.cmdframework.TaskCommand;
 import com.ibm.websphere.management.cmdframework.CommandStep;
 import com.ibm.websphere.management.cmdframework.CommandResult;
 import com.ibm.websphere.management.cmdframework.UploadFile;
 import com.ibm.websphere.management.exception.AdminException;
 import com.ibm.websphere.management.async.client.AsyncCommandClient;
 public class ImportAsset {

    public static void main (String [] args) {

        try {
             
            
// Connect to the appserver.         
            
// 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 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 we 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.

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

            String cmdName = "importAsset";
            UploadFile assetSource = new   

(Windows)

UploadFile("c:\sources\test5.zip"); //Change to the directory of the sources.

[Linux] [HP-UX] [Solaris]

[AIX]

UploadFile("/sources/test5.zip"); //Change to the directory of the sources.

    
            
// Create the command to import an asset.
            AdminCommand cmd = cmdMgr.createCommand(cmdName);
            cmd.setConfigSession(session); 
//import the asset using 
                                           
//the session created
            System.out.println("\nCreated " + cmdName);

            
// Set the source command parameter.
            cmd.setParameter("source", assetSource);
            System.out.println("\nSet source parameter to " +
                               cmd.getParameter("source"));

            
// Uncomment the following line to set the storage type to
            
// a value of STORAGETYPE_META or STORAGETYPE_NONE instead of
            
// the default of STORAGETYE_FULL:
            
//
            
//cmd.setParameter(“storageType,             
            
//                  CommandConstants.STORAGETYPE_NONE);
          
            
// 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 AssetOptions step.
            String stepName = "AssetOptions";
            CommandStep step = ((TaskCommand) cmd).gotoStep(stepName);

            
// The new asset name must contain the             
            
// same extension as the original .zip file name.
            String assetNewName = "asset1.zip";

            
// If we override the default destination, include the 
            
// entire path with the file name for the new destination.

(Windows)

String destName = "c:\websphere\asset\installDir\asset1.zip";

[Linux] [HP-UX] [Solaris]

[AIX]

String destName = "/websphere/asset/installDir/asset1.zip";

            for (int i = 0; i < step.getNumberOfRows(); i++) {
                
// 
The following lines change the name and destination
                
// step parameters. Other step parameters that we can
                
// use follow, but are commented out. 
                
// Change the set 
                
// of step parameters as required by the scenario.

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

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

                
// Set the description.
                
//String desc = "description for asset1.zip";
                
//step.setParameter("description", desc, i);
                
//System.out.println("\nSet description parameter to " +
                
//      step.getParameter("description", i));
                
                
// Set the validation.
                
//String validate = "Yes";
                
//step.setParameter("validate", validate, i);
                
//System.out.println("\nSet validate parameter to " +
                
//              step.getParameter("validate", i));
                
                
// Set the file permission.
                
//String filePermission = ".*\\.dll=755";
                
//step.setParameter("filePermission", filePermission, i);
                
//System.out.println("\nSet filePermission parameter to " + 
                
//              step.getParameter("filePermission", i));
                
                
// Set the type aspect parameter value.
                
// Format for a typeAspect: WebSphere:spec=xxx,version=n.n+
                
// Websphere:spec=xxx,version=n.n.
                
//String typeAspect = "";
                
//step.setParameter("typeAspect", typeAspect, i);
                
//System.out.println("\nGet typeAspect: " +
                
//      step.getParameter("typeAspect", i));

                
// Set the relationship parameter.
                
// The relationship parameter declares dependency
                
// relationships on other assets.  The parameter value
                
// is a list which contains the ID of each asset declared
                
// as a dependency.  Each ID in the list is separated by
                
// a "plus" sign ("+").
                
// 
                
// Only assets which are Java archives can be referenced in
                
// dependency relationships.  An asset is a Java archive if
                
// it has a type aspect identifying it as such.
                
//
                
// If an asset declared as a dependency does not exist or
                
// does not have a Java archive type aspect, it is ignored
                
// and no dependency on the asset is registered in the                 
                
// asset's configuration.
                
//
                
//String relationship = 
                
//       "assetname=shared.zip+assetname=shared2.zip";
                
//step.setParameter("relationship", relationship, i);
                
//System.out.println("\nGet relationship: " +
                
//      step.getParameter("relationship", i));

            }

            
// Call the asynchronous command client that imports the asset.
            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);
    }
}

 

Next steps

Add a composition unit to a business-level application using the asset that you imported. An asset included in a business-level application is represented by a composition unit.

Additional Application Programming Interfaces (APIs)

 

Related tasks

Deploy business-level applications
Administer business-level applications using programming
Add a composition unit using programming
Delete an asset using programming
Exporting an asset using programming
Listing assets using programming
Edit an asset using programming
View an asset using programming
Manage assets with scripting

 

Related

BLAManagement