com.ibm.datapower.wamt.clientAPI
Class ManagedSet

java.lang.Object
  extended by WorkArea
      extended by com.ibm.datapower.wamt.clientAPI.ManagedSet

public class ManagedSet
extends WorkArea

A ManagedSet is one of the core objects that callers of the clientAPI will use to manage DataPower devices. A ManangetSet is a heterogeneous collection of DataPower devices. The term heterogeneous refers to the hardware and licensing characteristics of the devices, as well as the domains configured in the managed set (e.g., it is not a requirement that all devices have identical domain configurations, see Device.createManagedDomain(String) for more information on a creating managed domain on a single device in a ManagedsSet/

Devices can be added to a ManagedSet which indicates that they are managed and identifies a particular management scope. When a Device is not a member of a ManagedSet, it is considered unmanaged.

A managed set can have zero or more Devices as members. A device is managed only if it is a member of a ManagedSet. When a device is managed, their managed domain(s) can be are synchronized with a specified domain configuration and deployment policy. See Domain.setSynchronizationMode(DomainSynchronizationMode)} for more information about Domain synchronization.


Field Summary
static java.lang.String COPYRIGHT_2009_2013
           
 
Constructor Summary
ManagedSet(java.lang.String name)
          Create a new ManagedSet that is empty and add it to the Manager.
 
Method Summary
 ProgressContainer addDevice(Device device)
          Adds a device to this managed set.
 java.util.Hashtable<Device,java.lang.Exception> createManagedDomain(java.lang.String domainName, URLSource domainSource, URLSource deploymentPolicySource, java.lang.String deploymentPolicyDomainName, java.lang.String deploymentPolicyObjectName)
          Creates a domain of the specified name on all devices in this managed set.
 MacroProgressContainer deploySourceConfigurationForDomain(java.lang.String domainName)
          Deploys the previously set domain configuration to all managed domains in this managed set with the specified domain name.
 MacroProgressContainer deploySourceFirmwareVersion()
          Schedules tasks to deploy the FirmwareVersion to all devices in this managed set.
static ManagedSet getByPrimaryKey(java.lang.String targetKey)
          Get the ManagedSet instance that has the specified primary key.
 Device[] getDeviceMembers()
          Get the devices which are members of this ManagedSet.
 java.lang.String getDisplayName()
          Get a human-readable name that represents this object.
 java.lang.String getName()
          Get the name of this ManagedSet.
 OperationStatus getOperationStatus()
          Get the OperationStatus of this ManagedSet.
 java.lang.String getPrimaryKey()
           
 boolean isAvailableForUpdate()
          Check if the ManagedSet is available for new update commands.
 ProgressContainer removeDevice(Device device)
          Remove the specified device from this managed set.
 ProgressContainer removeDeviceWithoutUnsubscribe(Device device)
          Remove the specified device from this managed set without trying to unsubscribe.
 java.util.Hashtable removeManagedDomain(java.lang.String domainName)
          Removes specified managed domain from all devices in this managed set.
 java.util.Hashtable setDeploymentPolicyForDomain(java.lang.String domainName, URLSource configurationSource, java.lang.String policyDomainName, java.lang.String policyName)
          Sets the deployment policy for the specified domain name if it is present on any devices in the managed set.
 java.util.Hashtable setQuiesceTimeoutForDomain(java.lang.String domainName, int timeout)
          Set the timeout value (in seconds) for checking the status of a domain quiesce or unquiesce operation for the specified domain on all devices members in this managed set
 java.util.Hashtable setSourceConfigurationForDomain(java.lang.String domainName, URLSource configurationSource)
          Set the configuration source for the specified domain name if it is is present on any of the devices in the managed set.
 java.util.Hashtable setSourceFirmwareLevel(java.lang.String level)
          Set the source firmware level for each Device in this ManagedSet.
 java.util.Hashtable setSynchronizationModeForDomain(java.lang.String domainName, DomainSynchronizationMode synchMode)
          The valid synchronization modes that can be set for a domain are DomainSynchronizationMode.MANUAL and DomainSynchronizationMode.AUTO.
 java.lang.String toString()
          Get a String representation of this object for the purpose of debugging or tracing.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COPYRIGHT_2009_2013

public static final java.lang.String COPYRIGHT_2009_2013
See Also:
Constant Field Values
Constructor Detail

ManagedSet

public ManagedSet(java.lang.String name)
           throws AlreadyExistsInRepositoryException,
                  DatastoreException,
                  DeletedException
Create a new ManagedSet that is empty and add it to the Manager. This new ManagedSet will not have any Device members or managed domains.

Parameters:
name - a human-consumable symbolic name for this object that will be for later display of this ManagedSet. This name must be unique across all ManagedSets in this Manager.
Method Detail

isAvailableForUpdate

public boolean isAvailableForUpdate()
Check if the ManagedSet is available for new update commands. If any update to the devices in this ManagedSet is currently running, the ManagedSet will not allow additional updates to be performed in either the foreground or the background.

Returns:
true if there is no write lock on the ManagedSet, false otherwise

getName

public java.lang.String getName()
                         throws DeletedException
Get the name of this ManagedSet. This name should be human-consumable and is the symbolic name used when the constructor was called. The name is the primary key of this object in the manager. The name is immutable, so there is no setName(String) method.

Returns:
the symbolic name of this ManagedSet.

getPrimaryKey

public java.lang.String getPrimaryKey()
                               throws DeletedException

getByPrimaryKey

public static ManagedSet getByPrimaryKey(java.lang.String targetKey)
Get the ManagedSet instance that has the specified primary key.

Parameters:
targetKey - the key of the target ManagedSet
Returns:
the ManagedSet instance that has the specified primary key. If no ManagedSet exists with this primary key, then it will return null.
See Also:
getPrimaryKey()

getDeviceMembers

public Device[] getDeviceMembers()
                          throws DeletedException
Get the devices which are members of this ManagedSet.

Returns:
the Devices which are members of this ManagedSet. If this ManagedSet has no members, then this array may have zero elements.
See Also:
addDevice(Device), removeDevice(Device), "useCases section 4.2"

addDevice

public ProgressContainer addDevice(Device device)
                            throws java.lang.Exception,
                                   LockBusyException,
                                   AlreadyExistsInRepositoryException,
                                   InUseException,
                                   InvalidParameterException,
                                   NotEmptyException,
                                   DeletedException,
                                   UndeployableVersionException,
                                   AMPException,
                                   DatastoreException,
                                   DeviceTypeIncompatibilityException,
                                   ModelTypeIncompatibilityException,
                                   FeaturesNotEqualException,
                                   MissingFeaturesInFirmwareException,
                                   UnlicensedFeaturesInFirmwareException
Adds a device to this managed set.

The following actions are performed: - this Manager subscribes to the new device - if synchronization mode is AUTO, this Manager synchronizes the configuration on the device - the managed set is persisted with the new device.

An exception is thrown if: - the device is already a member of another managed set

Parameters:
device -
Returns:
ProgressContainer that wraps the task of adding the device.

removeDevice

public ProgressContainer removeDevice(Device device)
                               throws NotExistException,
                                      InUseException,
                                      InvalidParameterException,
                                      NotEmptyException,
                                      DatastoreException,
                                      LockBusyException,
                                      DeletedException,
                                      FullException
Remove the specified device from this managed set. This means that the device is no longer managed. No domains or firmware are changed during the execution of this method, everything is left as-is on the device. The device remains defined in the Manager, so you can continue to use the Device object, especially if you want to later add it to another ManagedSet. It is not deleted from the repository.

Parameters:
device - the device to remove
See Also:
addDevice(Device), getDeviceMembers()

removeDeviceWithoutUnsubscribe

public ProgressContainer removeDeviceWithoutUnsubscribe(Device device)
                                                 throws LockBusyException,
                                                        NotExistException,
                                                        DeletedException,
                                                        DirtySaveException,
                                                        DatastoreException
Remove the specified device from this managed set without trying to unsubscribe. This method should be used when addDevice(Device) fails when trying to subscribe. The failure can be due to a connectivity problem or when the device is already subscribed to another manager.

Parameters:
device - the device to remove
See Also:
addDevice(Device), getDeviceMembers()

getOperationStatus

public OperationStatus getOperationStatus()
Get the OperationStatus of this ManagedSet. See the javadoc of the return type for an explanation of what OperationStatus is.

Returns:
the object that represents the operation status of the ManagedSet. This is a rollup of all operation status across each device in the ManagedSet. This is defined as a rollup of all managed devices which in turn includes all managed domains on each device.

toString

public java.lang.String toString()
Get a String representation of this object for the purpose of debugging or tracing.

Returns:
a String representation of this object for the purpose of debugging or tracing.

getDisplayName

public java.lang.String getDisplayName()
Get a human-readable name that represents this object. This name may be used in user interfaces.

Returns:
a human-readable name that represents this object.

setSourceFirmwareLevel

public java.util.Hashtable setSourceFirmwareLevel(java.lang.String level)
                                           throws DeletedException,
                                                  NotExistException
Set the source firmware level for each Device in this ManagedSet. This method calls the Device.setSourceFirmwareLevel(String) method for each device in this managed set. If a suitable firmware level has not been loaded into the Manager for a device in the set then the device will be added to the returned Hashtable with a NotExistException. Bear in mind that the devices in this managed set may be different Device Types, Model Types, or be licensed for different features, so the manager should be preloaded with all of the correct firmware images, at the level specified, for all of the devices in this set.

Parameters:
level - desiredFirmwareVersion
Returns:
Hashtable of failed Devices - with Device(key)/Exception(value)
See Also:
Device.setSourceFirmwareLevel(String), Manager.addFirmware(Blob, String), Firmware, FirmwareVersion

deploySourceFirmwareVersion

public MacroProgressContainer deploySourceFirmwareVersion()
                                                   throws DeletedException,
                                                          NotExistException
Schedules tasks to deploy the FirmwareVersion to all devices in this managed set. This function is available on a managed set with device members. See MacroProgressContainer to check for the results of deployment to each of the devices members

Returns:
MacroProgressConatiner is a collection of single tasks. It is a container for multiple ProgressContainers that represent each firmware deployment task to a managed device. The user interface can track progress of macro tasks and the sub tasks via the methods available MacroProgressContainer.

The MacroProgressContainer.getProgressContainers() returns a collection of ProgressContainers. You can get the correlator on each ProgressContainer with a call to ProgressContainer.getCorrelator(). The correlator returned is the Device object associated with ProgressContainer. It can be used to correlate a background task to other items that the caller cares about.

The MacroProgressContainer.getFailedTasks() returns a Hashtable. The key is the Device object(key) and the value is the ProgressContainer generated for that device (value)

The MacroProgressContainer.blockAndTrace(Level)is a convenience method for waiting for the tasks to complete and printing the progress of each step for each nested ProgressConatiner.

See Also:
MacroProgressContainer

deploySourceConfigurationForDomain

public MacroProgressContainer deploySourceConfigurationForDomain(java.lang.String domainName)
                                                          throws DeletedException,
                                                                 NotExistException

Deploys the previously set domain configuration to all managed domains in this managed set with the specified domain name.

The domain configuration is previously set by calling setSourceConfigurationForDomain(String, URLSource) and setDeploymentPolicyForDomain(String, URLSource, String, String)

Parameters:
domainName - Name of domain to be created
Returns:
MacroProgressConatiner is a collection of single tasks. It is a container for multiple ProgressContainers that represent each firmware deployment task to a managed device. The user interface can track progress of macro tasks and the sub tasks via the methods available MacroProgressContainer.

The MacroProgressContainer.getProgressContainers() returns a collection of ProgressContainers. You can get the correlator on each ProgressContainer with a call to ProgressContainer.getCorrelator(). The correlator returned is the Device object associated with ProgressContainer. It can be used to correlate a background task to other items that the caller cares about.

The MacroProgressContainer.getFailedTasks() returns a Hashtable. The key is the Device object(key) and the value is the ProgressContainer generated for that device (value)

The MacroProgressContainer.blockAndTrace(Level)is a convenience method for waiting for the tasks to complete and printing the progress of each step for each nested ProgressConatiner.

See Also:
setSourceConfigurationForDomain(String, URLSource)

createManagedDomain

public java.util.Hashtable<Device,java.lang.Exception> createManagedDomain(java.lang.String domainName,
                                                                           URLSource domainSource,
                                                                           URLSource deploymentPolicySource,
                                                                           java.lang.String deploymentPolicyDomainName,
                                                                           java.lang.String deploymentPolicyObjectName)
                                                                    throws DeletedException,
                                                                           NotExistException,
                                                                           LockBusyException
Creates a domain of the specified name on all devices in this managed set. The domain name must be specified, all other parameter are optional. If the optional parameters are not specified it will create new domain objects of the specified name on all the devices and add them to the manager. This will replace a domain of the same name if it already exists without any warnings. The minimum firmware level must be satisfied for the operation. See FirmwareVersion.meetsMinimumLevel(String)

Parameters:
domainName - Name of domain to be created
domainSource - Source configuration to be deployed on device for the domain. Optional, must pass in null if not to be used.
deploymentPolicySource - Policy Source to be used during deployment. Optional, must pass in null if not to be used.
deploymentPolicyDomainName - Domain name for the deployment policy source. Used to locate the domain within the policy source. Only used if deploymentPolicySource is non-null.
deploymentPolicyObjectName - Name for the deployment policy use to locate the policy within the policy source. Only used if deploymentPolicySource is non-null.
Returns:
Hashtable of devices on which creation of domain failed. The key is the Device object(key) and the value is the Exception generated for that device (value)
See Also:
Domain.deployConfiguration(), Domain.setDeploymentPolicy(URLSource, String, String), Domain.setSourceConfiguration(URLSource)

removeManagedDomain

public java.util.Hashtable removeManagedDomain(java.lang.String domainName)
                                        throws DeletedException,
                                               NotExistException,
                                               LockBusyException
Removes specified managed domain from all devices in this managed set. The managed domain and all child objects such as domain versions,deployment policy and deployment policy version will be deleted from the device. They will not be available from the repository.

Parameters:
domainName - Name of domain to be removed.
Returns:
Hashtable of devices on which removal of the specified managed domain failed. The key is the Device object(key) and the value is the Exception generated for that device (value)

setSourceConfigurationForDomain

public java.util.Hashtable setSourceConfigurationForDomain(java.lang.String domainName,
                                                           URLSource configurationSource)
                                                    throws DeletedException,
                                                           NotExistException,
                                                           LockBusyException
Set the configuration source for the specified domain name if it is is present on any of the devices in the managed set.

Parameters:
domainName - Name of domain for setting the configuration source
configurationSource - The configuration source to set
Returns:
Hashtable of devices on which setSourceConfiguration() failed. The key is the Device object(key) and the value is the Exception generated for that device (value) on which setSourceConfiguration() failed
See Also:
Domain.setSourceConfiguration(URLSource), URLSource, deploySourceConfigurationForDomain(String)

setDeploymentPolicyForDomain

public java.util.Hashtable setDeploymentPolicyForDomain(java.lang.String domainName,
                                                        URLSource configurationSource,
                                                        java.lang.String policyDomainName,
                                                        java.lang.String policyName)
                                                 throws DeletedException,
                                                        NotExistException,
                                                        LockBusyException
Sets the deployment policy for the specified domain name if it is present on any devices in the managed set.

Parameters:
domainName - Name of managed domain for which policy export options will be set
configurationSource - The configuration source
policyDomainName - name of theDomain that is used as an index into blob that will be deployed on the device
policyName - name of Deployment Policy which will be used as an index into the blob that will be deployed on a device
Returns:
Hashtable of devices on which setDeplymentPolicy failed. The key is the Device object(key) and the value is the Exception generated for that device (value) on which setDeploymentPolicy failed
See Also:
Domain.setSourceConfiguration(URLSource), URLSource

setSynchronizationModeForDomain

public java.util.Hashtable setSynchronizationModeForDomain(java.lang.String domainName,
                                                           DomainSynchronizationMode synchMode)
                                                    throws DeletedException,
                                                           NotExistException,
                                                           LockBusyException

The valid synchronization modes that can be set for a domain are DomainSynchronizationMode.MANUAL and DomainSynchronizationMode.AUTO.

By default the synchronization mode is set to DomainSynchronizationMode.MANUAL. Configuration deployment must be scheduled and done manually by an administrator.

When synchronization mode is set to DomainSynchronizationMode.AUTO, domain configuration deployment is synchronized automatically. An automatic domain deployment can occur when the following conditions are detected:

  • The persisted domain configuration differs from the domain on the device
  • The timestamp of the persisted source files (domain source or deployment policy source) changes since the last deployment
  • A method call changes the domain source or the effective deployment policy
  • A prior synchronized deploy operation has failed
  • Set the synchronization mode on all managed domains with the specified domain name

    Parameters:
    domainName - name of domain
    synchMode - - The synchronization mode to set for the specified domains in this managed set. synchMode defaults to DomainSynchronizationMode.MANUAL. Valid synchronization modes are DomainSynchronizationMode.MANUAL and DomainSynchronizationMode.AUTO
    Returns:
    Hashtable of failed Domains - with Domain(key)/Exception(value)
    See Also:
    Domain.setSynchronizationMode(DomainSynchronizationMode), Manager.setDomainSynchronizationDaemonSleepMS(long)

    setQuiesceTimeoutForDomain

    public java.util.Hashtable setQuiesceTimeoutForDomain(java.lang.String domainName,
                                                          int timeout)
                                                   throws DeletedException,
                                                          NotExistException,
                                                          LockBusyException,
                                                          InvalidParameterException
    Set the timeout value (in seconds) for checking the status of a domain quiesce or unquiesce operation for the specified domain on all devices members in this managed set

    Parameters:
    domainName - Name of domains on which to set the timeout value
    timeout - timeout value for checking the status of a quiesce operation
    Returns:
    Hashtable of failed Devices - with Device(key)/Exception(value)
    See Also:
    Domain.setQuiesceTimeout(int), Manager.OPTION_DEBUG_DOMAIN_QUIESCE_TIMEOUT


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