com.ibm.datapower.wamt.clientAPI
Class Domain

java.lang.Object
  extended by com.ibm.datapower.wamt.clientAPI.Domain
All Implemented Interfaces:
Taggable, Versionable

public class Domain
extends java.lang.Object
implements Versionable, Taggable

A Domain object corresponds to a domain configuration on a DataPower device. A domain is a configuration partition on a DataPower device, and is the most granular configuration object that the manager uses. The constructor for Domain should not be used directly. Use the createManagedDomain method on ManagedSet or Device instead. A DataPower device can contain multiple domains.

A domain is Versionable - upon successful deployment the domain configuration is read back off of the device to create a DomainVersion object.

The manager has the ability to maintain domain synchronization on Managed Domains. For more information refer to setSynchronizationMode(DomainSynchronizationMode). Domain synchronization is disabled by default, to enable it refer to setSynchronizationMode(DomainSynchronizationMode)

Domain quiesce happens automatically for devices with firmware 3.8.1 or later. To change the domain quiesce timeout change the Configuration.KEY_DOMAIN_QUIESCE_TIMEOUT value in WAMT.properties, or call setQuiesceTimeout(int)

The default domain contains some configuration that is unique to a specific DataPower device. Ethernet interface configuration is an example. When managing the default domain for devices with firmware 3.8.1 or later, a deployment policy should be used to filter out configuration that is unique to a specific device. The following two filtered configuration rules should always be used in the deployment policy for the default domain:

Additonal rules can be specified to filter out other configuration if needed. For devices with firmwares prior to 3.8.1, device specific configuration is always excluded from the default domain configuration.

See Also:
DomainVersion

Field Summary
static java.lang.String COPYRIGHT_2009_2013
           
 
Fields inherited from interface com.ibm.datapower.wamt.clientAPI.Versionable
COPYRIGHT_2009_2010
 
Method Summary
 void addTag(java.lang.String name, java.lang.String value)
           Add a new tag.
 ServiceDeployment createServiceDeployment(ServiceConfiguration svcConfig, boolean importAllFiles)
          Create the ServiceDeployment object with service configuration only, no deployment policy for deployment.
 ServiceDeployment createServiceDeployment(ServiceConfiguration svcConfig, URLSource policyURL, java.lang.String policyDomain, java.lang.String policyObjName, boolean importAllFiles)
          Create the ServiceDeployment object with service configuration and deployment policy to be deployed in this domain.
 DeleteObjectResult[] deleteService(RuntimeService service, ConfigObject[] excludeObjects, boolean deleteReferencedFiles)
          Delete a RuntimeService, and return the result of each objects in a RuntimeService.
 ProgressContainer deployConfiguration()
          Push a configuration onto the device that was previously set by calling setSourceConfiguration(URLSource) and setDeploymentPolicy(URLSource, String, String)
 java.lang.String getAbsoluteDisplayName()
          Get a human-readable name that represents this object.
 AdminStatus getAdminStatus()
          Get AdminStatus of this domain, enabled (AdminState.ENABLED) or disabled (AdminState.DISABLED).
 java.util.Map<java.lang.String,java.util.List<Status>> getAllStatus()
          Get all status
static Domain getByPrimaryKey(java.lang.String targetKey)
          Retrieve a reference to the Domain that has the specified primary key.
 DeploymentPolicy getDeploymentPolicy()
          Get the deployment policy owned by this Domain.
 Device getDevice()
          Get the device that owns this Domain.
 int getHighestVersionNumber()
          Get the highest version number of all the DomainVersions in this Domain.
 java.lang.String getName()
          Get the name of this Domain.
 OpStatus getOpStatus()
          Get OpStatus of this domain, up (OpState.UP) or down (OpState.DOWN).
 java.lang.String getPrimaryKey()
           
 QuiesceStatus getQuiesceStatus()
          Get Quiesce Status of this domain.
 int getQuiesceTimeout()
          Get the persisted timeout value when Domain is quiesced.
 java.lang.String getRelativeDisplayName()
          Get a human-readable name that represents this object.
 RuntimeService[] getServices()
          Get all services in this domain.
 URLSource getSourceConfiguration()
          This method can be used to retrieve the URLSource specified by setSourceConfiguration(URLSource)
 java.util.List<Status> getStatus(java.lang.String name)
          Get a status
 DomainSynchronizationMode getSynchronizationMode()
          This method can be used to determine the current synchronization mode for this Domain
 java.util.Set<java.lang.String> getTagNames()
           Get all of the tag names on the resource.
 java.util.Set<java.lang.String> getTagValues(java.lang.String name)
           Get the values for a given tag name.
 Version getVersion(int targetVersionNumber)
          Get the specified Version of this Versionable object.
 Version[] getVersions()
          Get all the versions that exist of this Versionable object.
 void quiesce()
          Quiesce a domain The quiece operation is used on firmware versions 3.8.1 or higher to stop a domain before updating it.
 void refresh()
          Update the latest status of domain and all services in this domain.
 void remove(Version version)
          Trim the specified DomainVersion from the repository.
 void removeTag(java.lang.String name)
           Remove all tags with the provided name.
 void removeTag(java.lang.String name, java.lang.String value)
           Remove the exactly matching tag.
 void removeTags()
           Remove all the tags from the resource.
 void restart()
          To restart this domain
 void setDeploymentPolicy(URLSource url, java.lang.String policyDomain, java.lang.String policyObjName)
          Use this method to specify the deployment policy to apply to this domain during deployment.
 void setDeploymentPolicyXML(URLSource url)
          Use this method to specify the deployment policy in XML format.
 void setQuiesceTimeout(int timeout)
          Set the timeout value (in seconds) for checking the status of a domain quiesce or unquiesce operation.
 void setSourceConfiguration(URLSource sourceConfiguration)
          Use this method to specify the domain configuration URLSource that should be deployed for this Domain.
 void setSynchronizationMode(DomainSynchronizationMode synchMode)
          Set configuration synchronization mode on the Domain.
 java.lang.String toString()
          Get a String representation of this object for the purpose of debugging or tracing.
 void unquiesce()
          Unquiesce a domain The quiece operation is used on firmware versions 3.8.1 or higher to stop a domain before updating it.
 void uploadFile(java.lang.String fileName, URLSource urlSource)
          Upload file to device of this domain
 
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
Method Detail

setSourceConfiguration

public void setSourceConfiguration(URLSource sourceConfiguration)
                            throws DatastoreException,
                                   DeletedException,
                                   java.net.URISyntaxException,
                                   NotExistException,
                                   InvalidParameterException,
                                   FullException,
                                   NotManagedException
Use this method to specify the domain configuration URLSource that should be deployed for this Domain.

NOTE: If domain synchronization is enabled, and a deployment policy is to be deployed along with this source then the synchronization mode should be set to DomainSynchronizationMode.MANUAL prior to calling this method and set back to DomainSynchronizationMode.AUTO after calling setDeploymentPolicy(URLSource, String, String). The domain will be synchronized automatically after the synchronization mode is set to DomainSynchronizationMode.AUTO

Parameters:
sourceConfiguration - is a URLSource that points to the configuration that should be deployed to the Device for this domain. The domain configuration is not persisted in the repository as a DomainVersion until the configuration is successfully deployed
See Also:
setSynchronizationMode(DomainSynchronizationMode), setDeploymentPolicy(URLSource, String, String)

deployConfiguration

public ProgressContainer deployConfiguration()
                                      throws DeletedException,
                                             FullException,
                                             NotManagedException
Push a configuration onto the device that was previously set by calling setSourceConfiguration(URLSource) and setDeploymentPolicy(URLSource, String, String)

This method returns a long-running task that is wrapped in a ProgressContainer. The ProgressContainer must be used to trigger the actual execution of this task.

This operation will fail if the domain does not belong to a managed device.

Note: To use EXPORT configuration files for DataPower devices on a firmware prior to 4.0.1, the domain on the device must be created first via the DataPower WebGUI or CLI. A domain does not need to be created first on the device if using a entire domain BACKUP configuration file.

Returns:
the ProgressContainer object for this long running task
See Also:
setSourceConfiguration(URLSource sourceConfiguration)

quiesce

public void quiesce()
             throws DeletedException,
                    UnsuccessfulOperationException,
                    AMPException,
                    NotExistException
Quiesce a domain The quiece operation is used on firmware versions 3.8.1 or higher to stop a domain before updating it.


unquiesce

public void unquiesce()
               throws UnsuccessfulOperationException,
                      DeletedException,
                      AMPException,
                      NotExistException
Unquiesce a domain The quiece operation is used on firmware versions 3.8.1 or higher to stop a domain before updating it.


getName

public java.lang.String getName()
                         throws DeletedException
Get the name of this Domain. This name should be human-consumable. The name combined with the ManagedSet name is the primary key of this object in the manager. The name is immutable, so there is no setName(String) method.

Returns:
the name of this domain

getDevice

public Device getDevice()
                 throws DeletedException
Get the device that owns this Domain. The relationship between a Domain and a Device is immutable, so there is no setDevice(Device) method.


getDeploymentPolicy

public DeploymentPolicy getDeploymentPolicy()
                                     throws DeletedException
Get the deployment policy owned by this Domain.

A DeploymentPolicy object is created as a member of the Domain when the Domain is created. The DeploymentPolicy value may be changed by calling setDeploymentPolicy(URLSource, String, String) - there is no setDeploymentPolicy(DeploymentPolicy) method.


setDeploymentPolicy

public void setDeploymentPolicy(URLSource url,
                                java.lang.String policyDomain,
                                java.lang.String policyObjName)
                         throws DeletedException,
                                DirtySaveException,
                                DatastoreException,
                                InvalidParameterException,
                                FullException,
                                MissingFeaturesInFirmwareException,
                                NotManagedException
Use this method to specify the deployment policy to apply to this domain during deployment. This deployment policy will NOT be available on the device after a successful deployment. If the domain source is set to a DomainVersion, the deployment policy is not required to be set. NOTE: If domain synchronization is enabled, and a domain configuration is to be deployed along with this policy then the synchronization mode should be set to DomainSynchronizationMode.MANUAL prior to calling this method and set back to DomainSynchronizationMode.AUTO after calling setDeploymentPolicy(URLSource, String, String). The domain will be synchronized automatically after the synchronization mode is set to DomainSynchronizationMode.AUTO

Parameters:
url - - is a URLSource that points to a configuration source containing the policy to be used during deployment. The deployment policy information is not persisted in the repository until the policy is successfully deployed. This parameter is required.
policyDomain - - this is the first piece of information used to find the deployment policy within the configuration source specified by the URLSource. This parameter is only required if the source is a backup, since a backup may contain multiple domains.
policyObjName - - this is the second piece of information used to find the deployment policy within the configuration source specified by the URLSource. This parameter is required.
See Also:
setSynchronizationMode(DomainSynchronizationMode), setSourceConfiguration(URLSource)

setDeploymentPolicyXML

public void setDeploymentPolicyXML(URLSource url)
                            throws DeletedException,
                                   DirtySaveException,
                                   DatastoreException,
                                   InvalidParameterException,
                                   FullException,
                                   MissingFeaturesInFirmwareException,
                                   NotManagedException
Use this method to specify the deployment policy in XML format. Refer to setDeploymentPolicy(URLSource, String, String) for synchronization behavior as related to deployment policy.

Parameters:
url - - is a URLSource that points to a configuration source containing the policy to be used during deployment. The deployment policy information is not persisted in the repository until the policy is successfully deployed. This parameter is required.
See Also:
setDeploymentPolicy(URLSource, String, String)

setSynchronizationMode

public void setSynchronizationMode(DomainSynchronizationMode synchMode)
                            throws DeletedException,
                                   DirtySaveException,
                                   DatastoreException,
                                   FullException,
                                   NotManagedException
Set configuration synchronization mode on the Domain.
The synchronization mode defaults to DomainSynchronizationMode.MANUAL. Valid synchronization modes are DomainSynchronizationMode.MANUAL and DomainSynchronizationMode.AUTO.
If the domain synchronization mode for a domain is set to DomainSynchronizationMode.AUTO The manager checks periodically to see if the domain configuration is out of synch with the domain on a DataPower device device.

The manager is designed to make the following checks:

Conditions that cause the manager to invoke the synchronization logic:

  1. Manager Start: When the manager is started it assumes that some managed domains may have been altered on managed devices while it was down. It calls synch(true) for each domain in order to do a diff on that domain (and redeploy if necessary).
  2. Notification: The device has the capability to notify the manager if a domain configuration is saved. A notification is specific to a particular device/domain (or the default domain, in the event a domain was removed) so the notification will eventually call synch(true) to verify the domain has changed, which will cause redeploy, which causes another notification that causes the manager to validate the domains are now identical.
  3. Timer event: The timer fires periodically as specified by ConfigurationDEFAULT_DOMAIN_SYNCHRONIZATION_INTERVAL unless overridden in WAMT.properties with the value of DomainSynchronizationInterval The timer event calls synch(false) because it does not want to always compare deployed domains to the source configuration, because the manager should be notified of such changes.
  4. "Set" method changes: If the synchronization mode is DomainSynchronizationMode.AUTO then a synch(false) task will be kicked off when setSourceConfuguration(url) or setDeploymentPolicy(url, domain, policy) are called with changes to the Domain configuration. If they are called with identical parameters then the synch() method will not be called
  5. Enabling synch: If the synchronization mode is set from DomainSynchronizationMode.MANUAL to DomainSynchronizationMode.AUTO then a synch(true) task will be called for the domain.

Parameters:
synchMode - the synchronization mode this device should adhere to
See Also:
DomainSynchronizationMode

remove

public void remove(Version version)
            throws InvalidParameterException,
                   NotExistException,
                   DeletedException,
                   LockBusyException,
                   DatastoreException
Trim the specified DomainVersion from the repository. The associated DeploymentPolicyVersion is also deleted. This could be user-initiated or invoked by an agent. It will remove the specified DomainVersion, but will not delete the Domain object.

Parameters:
version - the version to remove from the repository

getPrimaryKey

public java.lang.String getPrimaryKey()
                               throws DeletedException

getByPrimaryKey

public static Domain getByPrimaryKey(java.lang.String targetKey)
Retrieve a reference to the Domain that has the specified primary key.

Parameters:
targetKey - the primary key to search for
Returns:
the Domain that has the specified primary key. May return null if no Domain with the specified primary key was found.
See Also:
getPrimaryKey()

getVersions

public Version[] getVersions()
                      throws DeletedException
Description copied from interface: Versionable
Get all the versions that exist of this Versionable object.

This object should implement the Versionable interface, and versions of this object should implement the Version interface.

Specified by:
getVersions in interface Versionable
Returns:
an array of objects which describe all the versions of this object.
See Also:
Versionable.getVersion(int)

getVersion

public Version getVersion(int targetVersionNumber)
                   throws DeletedException
Description copied from interface: Versionable
Get the specified Version of this Versionable object. Versions are specified by a version number, which is a monotomically increasing integer that should be unique across this Versionable object.

Specified by:
getVersion in interface Versionable
Parameters:
targetVersionNumber - the specified version to get of this object.
Returns:
the specified version of this object. May return null if no version of the specified number exists.
See Also:
Versionable.getVersions()

getHighestVersionNumber

public int getHighestVersionNumber()
                            throws DeletedException
Get the highest version number of all the DomainVersions in this Domain.

Returns:
the highest version number of all the DomainVersions.

toString

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

Overrides:
toString in class java.lang.Object
Returns:
a String representation of this object for the purpose of debugging or tracing.

getRelativeDisplayName

public java.lang.String getRelativeDisplayName()
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. For example, "domain1".

getAbsoluteDisplayName

public java.lang.String getAbsoluteDisplayName()
Get a human-readable name that represents this object. This name may be used in user interfaces. This name is absolute to the context of the system.

Returns:
a human-readable name that represents this object. For example "Domain:testDomain1 on Device:dp12.dp.rtp.raleigh.ibm.com/9.42.102.72 in Managed Set:set1".

getSourceConfiguration

public URLSource getSourceConfiguration()
                                 throws DeletedException
This method can be used to retrieve the URLSource specified by setSourceConfiguration(URLSource)

Returns:
URLSource

getSynchronizationMode

public DomainSynchronizationMode getSynchronizationMode()
                                                 throws DeletedException
This method can be used to determine the current synchronization mode for this Domain

Returns:
the domain synchronization mode for this Domain object

getQuiesceTimeout

public int getQuiesceTimeout()
Get the persisted timeout value when Domain is quiesced.

Returns:
timeout value in seconds

setQuiesceTimeout

public void setQuiesceTimeout(int timeout)
                       throws DeletedException,
                              AlreadyExistsInRepositoryException,
                              DatastoreException,
                              InvalidParameterException
Set the timeout value (in seconds) for checking the status of a domain quiesce or unquiesce operation.

Quiesce only pertains to Firmware levels 3.8.1.0 or later. Earlier levels of firmware do not support quiesce so calling this method has no effect. Note: An exception will not be thrown if you call this method for a domain on a device that has a firmware level below 3.8.1.0 - so this value will be available if firmware is ever upgraded.

If a value of zero is set then the quiesce operation will be initiated on supported firmware, but the quiesce or unquiesce status will not be checked. If a nonzero value less than 60 is set, then the value will automatically be set to a minimum of 60 seconds. Values higher than 60 are OK.

Parameters:
timeout - value in seconds

getServices

public RuntimeService[] getServices()
                             throws DeletedException,
                                    UnsuccessfulOperationException
Get all services in this domain. This operation is used on firmware versions 5.0.0 or higher.

Returns:
the service array contains all service in this domain

deleteService

public DeleteObjectResult[] deleteService(RuntimeService service,
                                          ConfigObject[] excludeObjects,
                                          boolean deleteReferencedFiles)
                                   throws AMPException,
                                          DeletedException,
                                          UnsuccessfulOperationException
Delete a RuntimeService, and return the result of each objects in a RuntimeService.

Parameters:
service - The service which is returned from getServices() to be deleted
excludeObjects - The ConfigObject array for ConfigObjects of Service to be excluded (not to be deleted)
deleteReferencedFiles - true is to delete referenced files of service
Returns:

refresh

public void refresh()
             throws DeletedException
Update the latest status of domain and all services in this domain.


createServiceDeployment

public ServiceDeployment createServiceDeployment(ServiceConfiguration svcConfig,
                                                 URLSource policyURL,
                                                 java.lang.String policyDomain,
                                                 java.lang.String policyObjName,
                                                 boolean importAllFiles)
                                          throws DeletedException,
                                                 UnsuccessfulOperationException,
                                                 NotExistException,
                                                 InUseException,
                                                 InvalidParameterException,
                                                 AMPException,
                                                 java.io.IOException,
                                                 DirtySaveException,
                                                 DatastoreException,
                                                 FullException,
                                                 MissingFeaturesInFirmwareException,
                                                 NotManagedException
Create the ServiceDeployment object with service configuration and deployment policy to be deployed in this domain. Parameter policyURL must be valid to point to the deployment policy. Use createServiceDeployment(ServiceConfiguration, boolean) instead if no deployment policy is for deployment.

Note: If ServiceConfiguration.setServicesForDeployment(ConfigService[]) is not invoked, then assume all services and files in the source configuration will be deployed, the importAllFiles will be treated as true, meaning all files in the source configuration will be deployed to the target domain no matter what the importAllFiles is set.

Parameters:
svcConfig - The ServiceConfiguration object
policyURL - is a URLSource that points to a configuration source containing the policy to be used during deployment. The deployment policy information is not persisted in the repository until the policy is successfully deployed. This parameter is required.
policyDomain - this is the first piece of information used to find the deployment policy within the configuration source specified by the URLSource. This parameter is only required if the source is a backup, since a backup may contain multiple domains.
policyObjName - this is the second piece of information used to find the deployment policy within the configuration source specified by the URLSource. This parameter is required.
importAllFiles - true to import all files in a configuration source
Returns:
The ServiceDeployment object
See Also:
createServiceDeployment(ServiceConfiguration, boolean)

createServiceDeployment

public ServiceDeployment createServiceDeployment(ServiceConfiguration svcConfig,
                                                 boolean importAllFiles)
                                          throws DeletedException,
                                                 UnsuccessfulOperationException,
                                                 NotExistException,
                                                 java.io.IOException,
                                                 InUseException,
                                                 InvalidParameterException,
                                                 AMPException
Create the ServiceDeployment object with service configuration only, no deployment policy for deployment.

Parameters:
svcConfig - The ServiceConfiguration object
importAllFiles - true to import all files in a configuration source
Returns:
The ServiceDeployment object
See Also:
createServiceDeployment(ServiceConfiguration, URLSource, String, String, boolean)

getAdminStatus

public AdminStatus getAdminStatus()
                           throws InvalidParameterException,
                                  DeletedException
Get AdminStatus of this domain, enabled (AdminState.ENABLED) or disabled (AdminState.DISABLED).

Returns:
AdminStatus

getOpStatus

public OpStatus getOpStatus()
                     throws InvalidParameterException,
                            DeletedException
Get OpStatus of this domain, up (OpState.UP) or down (OpState.DOWN).

Returns:
OpStatus

getQuiesceStatus

public QuiesceStatus getQuiesceStatus()
                               throws InvalidParameterException,
                                      DeletedException
Get Quiesce Status of this domain.

Returns:
QuiesceStatus

addTag

public void addTag(java.lang.String name,
                   java.lang.String value)
            throws DeletedException,
                   AlreadyExistsInRepositoryException,
                   DatastoreException,
                   InvalidParameterException
Description copied from interface: Taggable

Add a new tag.

Specified by:
addTag in interface Taggable
Parameters:
name - the tag name
value - the tag value

removeTag

public void removeTag(java.lang.String name,
                      java.lang.String value)
               throws DeletedException,
                      DirtySaveException,
                      DatastoreException,
                      InvalidParameterException
Description copied from interface: Taggable

Remove the exactly matching tag. no error if you try to remove a tag that isn't there

Specified by:
removeTag in interface Taggable
Parameters:
name - the tag name
value - the tag value

removeTag

public void removeTag(java.lang.String name)
               throws DeletedException,
                      DirtySaveException,
                      DatastoreException,
                      InvalidParameterException
Description copied from interface: Taggable

Remove all tags with the provided name. no error if you try to remove a tag that isn't there

Specified by:
removeTag in interface Taggable
Parameters:
name - the tag name

removeTags

public void removeTags()
                throws DeletedException,
                       DirtySaveException,
                       DatastoreException
Description copied from interface: Taggable

Remove all the tags from the resource. No error if none exist

Specified by:
removeTags in interface Taggable

getTagNames

public java.util.Set<java.lang.String> getTagNames()
                                            throws DeletedException
Description copied from interface: Taggable

Get all of the tag names on the resource. return an empty set if no tags have been added

Specified by:
getTagNames in interface Taggable
Returns:
the set of tag name

getTagValues

public java.util.Set<java.lang.String> getTagValues(java.lang.String name)
                                             throws DeletedException,
                                                    InvalidParameterException
Description copied from interface: Taggable

Get the values for a given tag name. return an empty set if the resource hasn't been tagged with the requested tag name

Specified by:
getTagValues in interface Taggable
Parameters:
name - the tag name
Returns:
the set of tag name

uploadFile

public void uploadFile(java.lang.String fileName,
                       URLSource urlSource)
                throws DeletedException,
                       AMPException,
                       java.io.IOException,
                       java.net.URISyntaxException,
                       NotExistException,
                       UnsuccessfulOperationException
Upload file to device of this domain

Parameters:
fileName - the name of the file in the format used by the device, i.e., store:///myfile. The folder must exist in the device, otherwise, the exception is thrown
urlSource - an URLSource that points to the file that is copied to the Device, the schemes of url only support "file:///", "http://", "https://". URISyntaxException exception is thrown if the urlSource is not valid.

restart

public void restart()
             throws DeletedException,
                    AMPException,
                    LockBusyException,
                    UnsuccessfulOperationException,
                    NotExistException
To restart this domain


getAllStatus

public java.util.Map<java.lang.String,java.util.List<Status>> getAllStatus()
                                                                    throws DeletedException,
                                                                           SOMAException,
                                                                           SOMAIOException
Get all status

Returns:
all status

getStatus

public java.util.List<Status> getStatus(java.lang.String name)
                                 throws DeletedException,
                                        SOMAException,
                                        SOMAIOException
Get a status

Parameters:
name - The name of operation to get status
Returns:
the status list


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