Package com.ibm.datapower.wamt.clientAPI

The clientAPI package encapsulates the logic for managing DataPower appliances, providing the API that should be used by a user interface to interact with one or more appliances.

See:
          Description

Interface Summary
Taggable  
Version A version of an object that is Versionable.
Versionable An object which can have multiple Versions.
 

Class Summary
Blob A simple representation of a Binary Large OBject (BLOB).
ConfigService The ConfigService is to represent the information of service returned from the ServiceConfiguration.getAvailableServices(Device).
Configuration This class loads all of the configuration data for the manager.
DeploymentPolicy This class represents the deployment policy that is to be applied to a Domain during deployment.
DeploymentPolicyVersion A class to track the versions of a DeploymentPolicy.
Device A Java object representation of an DataPower device (appliance).
Domain A Domain object corresponds to a domain configuration on a DataPower device.
DomainVersion Internal use only

A class to track the versions of a Domain.

Firmware A container for firmware images.
FirmwareVersion A single instance of a firmware image.
Lock An implementation of a re-entrant lock that can be either blocking (like synchronized) or non-blocking (fail-fast).
MacroProgressContainer A MacroProgressContainer is a container for multiple ProgressContainers.
ManagedSet A ManagedSet is one of the core objects that callers of the clientAPI will use to manage DataPower devices.
ManagementStatus Capture the management status (i.e., synced, in progress, etc.) for a managed element (firmware) on a device.
ManagementStatus.Enumerated The possible values for ManagementStatus.
Manager A singleton that is the root management object that starts and stops all other management objects/daemons.
ManagerStatus Capture the status of the Manager.
ManagerStatus.Enumerated The possible values for ManagerStatus.
ProgressContainer A ProgressContainer is the vehicle that the manager uses to inform the caller (likely a user presentation) of the progress on a long-running method.
RuntimeService The RuntimeService is to represent the service which is created on runtime, such as the return from Domain.getServices() or ServiceDeployment.getInterDependentServices().
ServiceConfiguration The ServiceConfiguration is created for the services in the source configuration to be deployed.
ServiceDeployment The ServiceDeployment is used to check the inter-dependent service before the deployment, and is used to deploy the service source configuration to device.
Signaler Send a signal to some third party that informs them we are about to do an update of a device.
URLSource A URLSource is a convenience class to access blob objects from various schemes e.g.
 

Enum Summary
DeploymentPolicyType DeploymentPolicyType is an enum used to determine the type of deployment policy to be used during a configuration deploy.
DomainSynchronizationMode DomainSynchronizationMode is an enumeration used to determine the synchronization policy that will used for managed domains.
 

Exception Summary
AlreadyExistsException The specified operation would create a duplicate, and duplicates are not allowed.
ClientAPIException The ClientAPIException is the parent class for all other exceptions defined in the clientAPI.
DeletedException The Java object you are trying to access has been deleted from the persisted datastore.
DeviceTypeIncompatibilityException An operation was attempted on two objects and the two objects did not have a compatible device type.
FeaturesNotEqualException An operation was attempted on two Device objects, and the two Devices did not have the same licensed features.
FullException The container you are trying to add an item to is already at its maximum capacity.
IncompatibilityException An operation was attempted on two objects, and the objects were incompatible with each other.
InUseException The referenced item is in use and cannot be removed/deleted/destroyed while it is in use.
InvalidCredentialException The credential supplied does not pass the authentication and/or the authorization tests.
InvalidParameterException A runtime problem was detected with the parameter that you are attempting to use.
LockBusyException The requested item is locked by another thread and is unavailable for the requested operation.
MissingFeaturesInFirmwareException An operation was attempted between a Firmware and a Device, but the Device is licensed for features that the Firmware does not provide libraries for.
ModelTypeIncompatibilityException An operation was attempted on two objects, and the ModelType for the two objects was incompatible.
NotEmptyException You are trying to delete a container which is not empty, or trying to delete an object which other objects are dependent upon.
NotExistException The requested object does not exist.
NotManagedException The operation requested cannot be done because the relevant object is not managed.
ShutdownException An operation was prematurely terminated because the Manager is being shut down.
SubscriptionToAnotherManagerException The device you are trying to subscribe to already has been subscribed to using the same subscription id by another subscriber (manager).
UndeployableVersionException The specified DomainVersion is not deployable because it does not match the specified DeploymentPolicyVersion.
UnlicensedFeaturesInFirmwareException An operation was attempted with a Firmware and a Device, and the Firmware has libraries for strict features that the Device is unlicensed for.
UnsuccessfulOperationException A runtime problem was detected while attempting to perform the indicated operation.
UnsupportedVersionException The version you are trying to create, deploy or operate on is not supported and is not allowed.
 

Package com.ibm.datapower.wamt.clientAPI Description

The clientAPI package encapsulates the logic for managing DataPower appliances, providing the API that should be used by a user interface to interact with one or more appliances.

From a user interface perspective the clientAPI is the top-level API of the manager. The first classes you should become familiar with are:

There are several factors to consider when using clientAPI

Firmware related considerations

Consider the following factors when deploying firmware to a DataPower device.

Overview of using the clientAPI

Code Sample

The best way to describe how to use the manager is to provide a code sample. The following section is provided to be a sample for using the clientAPI. For more information refer to specific clientAPI JavaDoc for the clientAPI class you are interested in.

Comments in this sample describe not only the associated code, but occasionally describes alternate usage of the clientAPI, so read closely!

import java.io.File;
import java.util.HashMap;
import java.util.Map;
import java.util.logging.Level;

import com.ibm.datapower.wamt.Credential;
import com.ibm.datapower.wamt.DMgrException;
import com.ibm.datapower.wamt.clientAPI.Device;
import com.ibm.datapower.wamt.clientAPI.Domain;
import com.ibm.datapower.wamt.clientAPI.ManagedSet;
import com.ibm.datapower.wamt.clientAPI.Manager;
import com.ibm.datapower.wamt.clientAPI.ProgressContainer;
import com.ibm.datapower.wamt.clientAPI.URLSource;

public class Sample {
    
    public static void main(String[] args) throws Exception  {

        //Create the first instance of the manager. 
        Map options = new HashMap();
        Credential credential = new Credential();
        //Specify the RepositoryEncryptionPassword property for additional security.
        //  credential.setProperty("RepositoryEncryptionPassword", "ExamplePW");
        //Specify the RepositoryDirectory property for location where repository files will be stored.        
        //  credential.setProperty("RepositoryDirectory", "c:/WAMTRepository");        
        
        options.put(Manager.OPTION_CREDENTIAL, credential);
        Manager manager = Manager.getInstance(options);

        
        //Go ahead and declare the progressContainer var, it will be used a few times.
        ProgressContainer progressContainer = null;
        
        // Create device object
        System.out.println("Create Device: device1");                   
        progressContainer = null;
        progressContainer = Device.createDevice("dp10", "dp10.dp.rtp.raleigh.ibm.com", "admin", "may0510m", 5550);
        progressContainer.blockAndTrace(Level.FINER);
        if (progressContainer.hasError()) {
            System.out.println("An error occurred creating device object");
            return;
        }
        Device device1 = (Device) progressContainer.getResult();
        
        // NOTE: At this point you can perform operations on the device like 
        //       backup/restore, delete a domain, and update firmware. In this 
        //       example, the device will be added to a managed set.

        // Create managed set object and add device1
        System.out.println("Create Managed Set: set1");                 
        ManagedSet set1 = new ManagedSet("set1");
        progressContainer = set1.addDevice(device1);
        progressContainer.blockAndTrace(Level.FINER);
        
        
        //Create a managed domain in the Device object
        System.out.println("Create domain on device1");                 
        Domain domain1 = device1.createManagedDomain("myDomain");
        
        //Reference a domain config source via file, and policy config source via http
        URLSource domainSource = new URLSource("file:///C:/DataPowerData/domain-export.zip");
        URLSource policySource = new URLSource("http://my-http-server:8080/mypolicies/deployment-policy-export.zip");

        //Set the domain and policy, and then deploy
        //
        //  At this point the domain synch could be enabled by calling 
        //     domain1.setSynchronizationMode(DomainSynchronizationMode.AUTO);
        //  but we won't, since we are about to set a domain AND a policy source, which would cause 
        //  the domain to be deployed twice in rapid succession with the next two lines of code.
        //  To disable auto synch call:
        //     domain1.setSynchronizationMode(DomainSynchronizationMode.MANUAL);
        //
        domain1.setSourceConfiguration(domainSource);
        domain1.setDeploymentPolicy(policySource, "someDomain", "somePolicyInTheDomain");

        //Note that the "deployConfiguration" is not needed if synch is auto 
        progressContainer = domain1.deployConfiguration();
        System.out.println("OPTIONAL: PC Total steps=" + progressContainer.getTotalSteps());
        progressContainer.blockAndTrace(Level.FINER);
        if (progressContainer.getError()==null){
           System.out.println("  OK deploy:");          
        }
        else {
           System.out.println("  Failed deploy:"+progressContainer.getError().getMessage());
        }

        // Create firmware versions in manager
        System.out.println("Load firmware");                    
        File firmwareFile = new File("C:/DataPowerData/xi-firmware-3.8.1.1.scrypt2");
        Blob blob = new Blob(firmwareFile);
        progressContainer = manager.addFirmware(blob, "New XI firmware");
        progressContainer.blockAndTrace(Level.FINER);
        if (progressContainer.hasError()) {
            System.out.println("An error occurred loading firmware");
            return;
        }
        
        //Set the firmware level for all devices in the managed set...
        //hmm, seems like I recall we only have one.
        System.out.println("Set firmware level and deploy it");                 
        Hashtable failedDevices = set1.setSourceFirmwareLevel("3.8.1.1");
        if (!failedDevices.isEmpty()) {
            System.out.println("Hmm, a device failed. Maybe we dont have 3.8.1.1 for it?");                     
        }
        MacroProgressContainer mpc = set1.deploySourceFirmwareVersion();
        mpc.blockAndTrace(Level.FINER);
        if (mpc.hasError()) {
            //Note that if a device in the set had a problem with the 
            //seSourceFirmwareLevel, it will probably fail here too
            System.out.println("An error occurred deploying firmware");
            return;
        }
        //* This can also be done on the device directly
        //device1.setSourceFirmwareLevel("3.8.1.1");
        //progressContainer = device1.deploySourceFirmwareVersion();
        //progressContainer.blockAndTrace(Level.FINER);

        //////////////////////////////////////////////
        // OPTIONAL REMOVAL - begin
        // The code between the "OPTIONAL" comments 
        // removes the newly created device & managed set 
        // from the manager. If you skip these then they  
        // will remain persisted and be available the next 
        // time the manager is started. Thus creating them 
        // again will cause an error. 
        //
        // remove device from the managed set
        System.out.println("Remove device1");                   
        progressContainer = set1.removeDevice(device1);
        progressContainer.blockAndTrace(Level.FINER);
        //    
        // remove managed set from manager 
        System.out.println("Remove managed set1");                      
        manager.remove(set1);
        //
        // remove device from manager
        System.out.println("Remove device1 from manager");                      
        manager.remove(device1);
        //
        // OPTIONAL REMOVAL - end
        //////////////////////////////////////////////
        
        // shutdown manager
        manager.shutdown();
        System.out.println("Sample COMPLETED.  Exiting.");
    }
}



© Copyright IBM Corp. 2006, 2010 All Rights Reserved.