com.ibm.datapower.wamt.clientAPI
Class Device

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

public class Device
extends java.lang.Object
implements Taggable

A Java object representation of an DataPower device (appliance). Use the static method createDevice(String, String, String, String, int) to create a Device object. This method will instantiate the object, load metadata from the device, and persist the information via the dataAPI. Device is recreated by the Manager at startup. A device is removed from the manager by calling Manager.remove(Device).

Even though a device, upon creation, is known to the manager, it is unmanaged until it is added to a ManagedSet via ManagedSet.addDevice(Device). A device can belong to one and only one ManagedSet.

A device can have multiple (0..N) domains. But a domain is not managed unless it is created using the createManagedDomain method on the Device or ManagedSet object. Calling createManagedDomain on ManagedSet causes a domain object to be created on each device in the managed set. the manager will not perform any operations on an unmanaged domain.

Each managed domain has an operational status. The operational status reflects the op-state of the domain. A device has an operational status, which is the aggregation of all of the domains. Firmware does not have an operational status. Refer to the javadoc for OperationStatus for an explanation of how the aggregation occurs.

Firmware may be updated on a device regardless of its membership in a managed set.

The methods in this class that access data that originates from a device are really accessing cached values in the data members of a class instance. They are not invoking the device communication API (AMP) to get the value in real time. Separate threads in the manager will communicate with the device in a background manner to get the data from the device to populate this class instance.


Field Summary
static java.lang.String COPYRIGHT_2009_2013
           
 
Method Summary
 void acceptLicenseForFirmware()
          Assert license acceptance for subsequent firmware update.
 void addTag(java.lang.String name, java.lang.String value)
           Add a new tag.
 ProgressContainer backup(java.lang.String cryptoCertificateName, URLSource cryptoImage, java.net.URI backupDestination, boolean includeISCSI, boolean includeRaid)
          Takes a backup of a DataPower appliance which can be replicated to a compatible appliance.
static ProgressContainer createDevice(java.lang.String symbolicName, java.lang.String hostname, java.lang.String userid, java.lang.String password, int hlmPort)
          Create a background task to add a new device to the Manager.
 Domain createManagedDomain(java.lang.String domainName)
          Create a managed domain on this Device.
 void deleteDomain(java.lang.String domainName)
          Delete a domain on a device.
 ProgressContainer deploySourceFirmwareVersion()
          Schedules a task to deploy a FirmwareVersion.
 java.lang.String getActualFirmwareLevel()
          Get the firmware level that is currently deployed to this device.
 StringCollection getAllDomainNames()
          Get a list of all the domains on the specified device, including those that are not managed.
static Device getByPrimaryKey(java.lang.String targetKey)
          Retrieve a reference to the device that has the specified primary key.
 Commands getCommands()
          Get the commands implementation to use for this device.
 java.lang.String getCurrentAMPVersion()
          Returns the current AMP version supported by this device.
static java.lang.String getCurrentAMPVersionFromGetDeviceInfoResponse(java.lang.String ampVersion)
          Determine the current AMP version
 DeviceContext getDeviceContext()
          Returns the DeviceContext for this device, necessary for AMP calls.
 DeviceType getDeviceType()
          Get the device type.
 java.lang.String getDisplayName()
          Get a human-readable name that represents this object.
 StringCollection getFeatureLicenses()
          Get the list of Strings that represent the feature entitlements (licensed features) for this device.
 int getGUIPort()
          Get the device's port for the WebGUI.
static java.lang.String getHardwareOptionsFromDeviceID(java.lang.String deviceID)
          Determine the descriptive hardware options String from the String returned from Commands.getDeviceMetaInfo(DeviceContext).
 int getHLMPort()
          Get the device's port number for AMP (HLM) communication.
 java.lang.String getHostname()
          Get the hostname or IP address of this device.
 Domain getManagedDomain(java.lang.String targetDomainName)
          Get the managed Domain with the specified domain name on this device.
 Domain[] getManagedDomains()
          Get the managed Domains on this Device
 ManagedSet getManagedSet()
          Return this device's ManagedSet membership.
 ManagementStatus getManagementStatusOfDevice()
          Get the management status of the device.
 ManagementStatus getManagementStatusOfFirmware()
          Get the management status of the firmware.
 ModelType getModelType()
          Get the device's model type.
static ModelType getModelTypeFromDeviceID(java.lang.String deviceID)
          Determine the ModelType from the String returned from Commands.getDeviceMetaInfo(DeviceContext).
 OperationStatus getOperationStatusOfDomain(Domain domain)
          Get the operation status of a managed domain.
 java.lang.String getPrimaryKey()
          Returns the primary key of this device as a String
 int getQuiesceTimeout()
          Get the persisted timeout value when Domain is quiesced.
 OperationStatus getRollupOperationStatus()
          Rollup the operation status of all the domains on this device, and return that aggregated value.
 java.lang.String getSerialNumber()
          Get the unique ID of this device, which is its hardware serial number.
 SOMACommands getSOMACommands()
          Get the SOMA commands implementation to use for this device.
 FirmwareVersion getSourceFirmwareVersion()
          Returns the source FirmwareVersion that is set for this device.
 ManagementOperations[] getSupportedOperations()
          Get a list of operations that are supported on this device.
 java.lang.String getSymbolicName()
          Get the symbolic name of this Device.
 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.
 java.lang.String getUserId()
          Get the administrative userid of this device.
 ProgressContainer getWebGUIURL(Domain domain)
          Create a background task to get the URL of the device's WebGUI.
 boolean isDeviceReachable()
          Check if a device is reachable.
 boolean isPrimary()
          Check if the device is primary.
 boolean isSecureBackupSupported()
          Check if secure backup is enabled on the device.
 boolean meetsMinimumFirmwareLevel(java.lang.String minimumLevel)
          Compare a specific firmware level (represented as a string) to the the firmware level that is currently deployed to this device.
 void quiesce()
          Quiesce all the domains on a device (managed domains and unmanaged domains).
 ProgressContainer reboot()
          reboot this device.
 void removeManagedDomain(java.lang.String domainName)
          Stop managing a domain on the device.
 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.
 ProgressContainer restore(java.lang.String cryptoCredentialName, java.net.URI backupSource, boolean validate)
          Restores the configuration and secure data from a successful secure backup.
 void setGUIPort(int guiPort)
          Set the device's port for the WebGUI.
 void setHLMPort(int hlmPort)
          Set the device's port number to which the AMP (HLM) client will attempt to connect.
 void setHostname(java.lang.String hostname)
          Set the hostname or IP address of this device.
 void setPassword(java.lang.String password)
          Set the password for the administrative userid for this device.
 void setQuiesceTimeout(int timeout)
          Set the timeout value (in seconds) for checking the status of a domain quiesce or unquiesce operation.
 void setSourceFirmwareLevel(java.lang.String desiredLevel)
          An alternative to setSourceFirmwareVersion(FirmwareVersion), this method accepts a firmware "level" (e.g., "3.8.0.1") instead of a specific FirmwareVersion object.
 ProgressContainer setSourceFirmwareVersion(FirmwareVersion desiredFirmwareVersion)
          Schedules a task to set the FirmwareVersion for this device.
 void setSymbolicName(java.lang.String name)
          Set the symbolic name of this Device.
 java.util.Hashtable setSynchronizationModeForManagedDomains(DomainSynchronizationMode synchMode)
          Set the Synchronization Mode for the all domains on device.
 void setUserId(java.lang.String userid)
          Set the administrative userid for this device.
 java.lang.String toString()
          Get a String representation of this object for the purpose of debugging or tracing.
 void unquiesce()
          Unquiesce all the domains on a device (managed domains and unmanaged domains).
 
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

createDevice

public static ProgressContainer createDevice(java.lang.String symbolicName,
                                             java.lang.String hostname,
                                             java.lang.String userid,
                                             java.lang.String password,
                                             int hlmPort)
                                      throws FullException
Create a background task to add a new device to the Manager. You can retrieve the Device from the Manager after the ProgressContainer indicates that this is complete. The device created by this task is an unmanaged device. The device is managed once it is added to a ManagedSet.

As a user of the clientAPI, you should invoke this method instead of the Device constructor. This is a long-running operation that requires a conversation with the device to fetch the required attributes (i.e., hardware serial number, device type, etc.) This method will return quickly, and you should monitor the returned ProgressContainer for status and results.

Parameters:
symbolicName - symbolic (human-readable) name of the device - this is an arbitrary name that the caller specifies, and is usually a short name, like DP1, DP2, etc. The Manager.getDeviceBySymbolicName(String) method uses this value to find the device.
hostname - network hostname or IP address of the device. This is the value used as an address to establish a connection to the device. Note: Hostname must be a valid host name per RFC 952 and RFC 1123.
userid - administrative userid
password - password for the administrative userid
hlmPort - device's network port for HLM (AMP)
Returns:
the object that contains the method's progress and result information. If the ProgressContainer indicates successful completion, you can retrieve the newly-created Device object instance from the ProgressContainer.

getManagedDomains

public Domain[] getManagedDomains()
                           throws DeletedException
Get the managed Domains on this Device

Returns:
an array of the Domains that are managed. If no managed domains exist on the device, or if this is an unmanaged device, then this array will have zero elements.

createManagedDomain

public Domain createManagedDomain(java.lang.String domainName)
                           throws AlreadyExistsInRepositoryException,
                                  DeletedException,
                                  NotManagedException,
                                  DatastoreException,
                                  LockBusyException,
                                  AMPException,
                                  NotExistException,
                                  InUseException
Create a managed domain on this Device. This Device must be a member of a ManagedSet to call this method, otherwise a NotManagedException is thrown. Note that for a new domain, i.e. a domain that does not yet exist on the physical device, the domain does not get created on the physical device until the configuration is deployed. Additionally, no DomainVersion objects will be created until the domain is deployed to the device. Domain synchronization can be enabled, but synchronization will not occur until Domain.setSourceConfiguration(URLSource) and optionally Domain.setDeploymentPolicy(URLSource, String, String) are called.

If the domainName specified matches an unmanaged domain on the Device the managed domain object will still be created. Deploying the new Domain will overwrite the existing domain.

Managed domains should be deleted (unmanaged) via removeManagedDomain(String) on the Device or ManagedSet object.

Parameters:
domainName - the name of the managed domain to be created
Returns:
the Domain object
See Also:
Domain, ManagedSet.createManagedDomain(String, URLSource, URLSource, String, String)

isDeviceReachable

public boolean isDeviceReachable()
Check if a device is reachable. By reachable, it means that the device must be able to respond to an application-level requests correctly. Incorrect user ID or password, for example, will make the device unreachable even the device is up and running. Note that is is not a real time status. It will only be updated when a device is created, loaded from repository or heart-beat task is executed for managed devices.


deleteDomain

public void deleteDomain(java.lang.String domainName)
                  throws DeletedException,
                         InvalidParameterException,
                         AMPException
Delete a domain on a device. This will only work for an unmanagedDomain, if a managed domain is to be deleted on a device, then the Domain object must first be destroyed by calling removeManagedDomain(String)

Parameters:
domainName - - the domain to be deleted

removeManagedDomain

public void removeManagedDomain(java.lang.String domainName)
                         throws DeletedException,
                                NotExistException,
                                LockBusyException,
                                DatastoreException,
                                InUseException,
                                InvalidParameterException,
                                NotEmptyException
Stop managing a domain on the device. This will destroy the domain object in the manager and remove it from persistence but leave the device as-is.

Parameters:
domainName - the domain to stop managing

getManagedDomain

public Domain getManagedDomain(java.lang.String targetDomainName)
                        throws DeletedException
Get the managed Domain with the specified domain name on this device.

Parameters:
targetDomainName - the name of the target domain.
Returns:
the managed Domain which has the specified domain name. If the targetDomainName is not managed or is not found, this method will return null.

getSupportedOperations

public ManagementOperations[] getSupportedOperations()
Get a list of operations that are supported on this device.

Returns:
a list of ManagementOperations objects

getDeviceContext

public DeviceContext getDeviceContext()
                               throws DeletedException
Returns the DeviceContext for this device, necessary for AMP calls.


getSerialNumber

public java.lang.String getSerialNumber()
                                 throws DeletedException
Get the unique ID of this device, which is its hardware serial number. The serial number is a unique value hardcoded inside the device, and is the same serial number that appears in the WebGUI. You can not set the serial number, it is automatically loaded from the device when it is added to the Manager. This ID is the primary key of this object in the manager. The ID is immutable, so there is no public setID(String) method.

Returns:
the device's unique hardware serial number. Can be null if the device ID hasn't been set yet, which can occur before the device has been added to the manager.

getPrimaryKey

public java.lang.String getPrimaryKey()
                               throws DeletedException
Returns the primary key of this device as a String


getByPrimaryKey

public static Device getByPrimaryKey(java.lang.String targetKey)
Retrieve a reference to the device that has the specified primary key. Internal use only

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

getSymbolicName

public java.lang.String getSymbolicName()
                                 throws DeletedException
Get the symbolic name of this Device. This name is designed to be human-consumable.

Returns:
the device Name
See Also:
setSymbolicName(String)

setSymbolicName

public void setSymbolicName(java.lang.String name)
                     throws AlreadyExistsInRepositoryException,
                            AlreadyExistsInRepositoryException,
                            DeletedException,
                            DatastoreException
Set the symbolic name of this Device. This name is designed to be human-consumable. This name must be unique, but it is mutable. The symbolic name is typically set when the method createDevice(String, String, String, String, int) is called

Parameters:
name - the device name
See Also:
getSymbolicName()

getHostname

public java.lang.String getHostname()
                             throws DeletedException
Get the hostname or IP address of this device.

Returns:
the device's hostname or IP address
See Also:
setHostname(String)

setHostname

public void setHostname(java.lang.String hostname)
                 throws DeletedException,
                        DatastoreException,
                        AlreadyExistsException
Set the hostname or IP address of this device. This value is used when the manager attempts to communicate with the device via AMP.

Parameters:
hostname - the new hostname or IP address for this device
See Also:
getHostname()

getUserId

public java.lang.String getUserId()
                           throws DeletedException
Get the administrative userid of this device.

Returns:
the device's administrative userid.
See Also:
setUserId(String)

setUserId

public void setUserId(java.lang.String userid)
               throws DeletedException,
                      DatastoreException
Set the administrative userid for this device. This value is used when the manager attempts to communicate with the device via AMP, so it should have administrative privileges on the device.

Parameters:
userid - the new administrative userid
See Also:
getUserId()

setPassword

public void setPassword(java.lang.String password)
                 throws DeletedException,
                        DatastoreException
Set the password for the administrative userid for this device. This value is used when the manager attempts to communicate with the device via AMP. For security reasons, there is no public getPassword() method.

Parameters:
password - the new administrative password

getHLMPort

public int getHLMPort()
               throws DeletedException
Get the device's port number for AMP (HLM) communication.

Returns:
the device's port number for AMP (HLM) communication
See Also:
setHLMPort(int)

setHLMPort

public void setHLMPort(int hlmPort)
                throws DeletedException,
                       DatastoreException,
                       AlreadyExistsException
Set the device's port number to which the AMP (HLM) client will attempt to connect. This is generally the device's XML Management Interface that has the AMP endpoint enabled.

Parameters:
hlmPort - the device's port number for AMP (HLM) communication.
See Also:
getHLMPort()

getGUIPort

public int getGUIPort()
               throws DeletedException
Get the device's port for the WebGUI.

Returns:
the device's port for the WebGUI
See Also:
setGUIPort(int)

setGUIPort

public void setGUIPort(int guiPort)
                throws DeletedException,
                       DatastoreException
Set the device's port for the WebGUI. This value may be used for automatically launching an external web browser to the device's WebGUI. This value is automatically populated when a device is added to the manager by probing the device cached info, so you do not need to invoke this method unless there is a special reason to do so.

Parameters:
guiPort - the device's port for the WebGUI
See Also:
getGUIPort()

getDeviceType

public DeviceType getDeviceType()
                         throws DeletedException
Get the device type. DeviceType is immutable, so there is no setDeviceType method.

Returns:
the device's device type, i.e., "XS35", "XS40", "XI50"

getCurrentAMPVersion

public java.lang.String getCurrentAMPVersion()
                                      throws DeletedException
Returns the current AMP version supported by this device. The AMP version is the string representation of the numeric version. The AMP version supported is determined by the firmware.

Returns:
String

getModelType

public ModelType getModelType()
                       throws DeletedException
Get the device's model type. ModelType is immutable, so there is no setModelType method.

Returns:
the device's model type, i.e., "9003", etc.

getFeatureLicenses

public StringCollection getFeatureLicenses()
                                    throws DeletedException
Get the list of Strings that represent the feature entitlements (licensed features) for this device. This list is a union of the licensed strict and non-strict features.

Returns:
the list of Strings that represent the feature entitlements for this device, i.e., "MQ", "TAM", "Tibco-EMS", etc.

getManagedSet

public ManagedSet getManagedSet()
                         throws DeletedException
Return this device's ManagedSet membership.

Returns:
the ManagedSet this device's ManagedSet. If the device is not a member of any ManagedSet, then this value will be null.
See Also:
ManagedSet.addDevice(Device), "useCases section 4.2"

getAllDomainNames

public StringCollection getAllDomainNames()
Get a list of all the domains on the specified device, including those that are not managed. Managed domains should be deleted (unmanaged) via ManagedSet.removeManagedDomain(String). This list is cached from the device from the last query.

Returns:
a List of Strings representing all the domains on this device
See Also:
ManagedSet.removeManagedDomain(String)

getOperationStatusOfDomain

public OperationStatus getOperationStatusOfDomain(Domain domain)
                                           throws DeletedException
Get the operation status of a managed domain.

Parameters:
domain - the domain to get the operation status of
Returns:
the operation status of a managed domain

getActualFirmwareLevel

public java.lang.String getActualFirmwareLevel()
Get the firmware level that is currently deployed to this device. In general, all the devices in a managedSet should have the same level of firmware, but situations may cause this to be false. This should reflect the actual firmware that is currently deployed to this device. The returned value was cached from the device from the last query.

Returns:
the firmware level that is currently deployed to this device

meetsMinimumFirmwareLevel

public boolean meetsMinimumFirmwareLevel(java.lang.String minimumLevel)
Compare a specific firmware level (represented as a string) to the the firmware level that is currently deployed to this device. This is useful for checking to see if the device has a firmware level greater than or equal to a level required by a particular feature.

Parameters:
minimumLevel - The firmware level required by a certain feature
Returns:
a boolean result from the comparison. If the device's firmware is greater than or equal to minimumLevel then the return value is true, otherwise the return value is false.

getManagementStatusOfFirmware

public ManagementStatus getManagementStatusOfFirmware()
Get the management status of the firmware. Firmware does not have an operational status, only management status.

Returns:
the management status of the firmware.

getManagementStatusOfDevice

public ManagementStatus getManagementStatusOfDevice()
Get the management status of the device. The management status is for the device reboot

Returns:
the management status of the device.

getRollupOperationStatus

public OperationStatus getRollupOperationStatus()
Rollup the operation status of all the domains on this device, and return that aggregated value.

Returns:
the aggregated operation status of all the domains on this device. Firmware does not have an operation status. If there are no domains being managed, then consider the device's operation status to be "up", because we know everything ("unknown" doesn't apply) and nothing is down (don't need to alarm the customer).

getWebGUIURL

public ProgressContainer getWebGUIURL(Domain domain)
                               throws DeletedException,
                                      DatastoreException,
                                      LockBusyException,
                                      FullException
Create a background task to get the URL of the device's WebGUI. This can be used to direct the user's browser for on-the-glass integration. If the device's administrator userid and password are known, it will also generate and append a SAMLart so that the URL will automatically login the browser to the WebGUI Control Panel. If there is a problem generating the SAMLart then no automatic login to the WebGUI will be performed. Because the login token (SAMLart) is generated on the device, this operation is considered long running, which is why it is queued as a background task.

Parameters:
domain - if you wish to jump directly to a specific domain in the WebGUI, include the name of the domain here. If you do not wish to jump directly to a specific domain in the WebGUI, set this value to null.
Returns:
a ProgressContainer for monitoring this long-running task. When the task has completed successfully you can retrieve a URL object from this ProgressContainer.
See Also:
"useCases section 4.1"

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.

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.

getModelTypeFromDeviceID

public static ModelType getModelTypeFromDeviceID(java.lang.String deviceID)
Determine the ModelType from the String returned from Commands.getDeviceMetaInfo(DeviceContext). This value is used to populate DeviceMetaInfo.getModelType().

Parameters:
deviceID - the DeviceID as returned to us from the device via AMP. This String may look like "9002-XS40-03" in the case of 9003's and earlier, or it may look like "923522X" in the case of 9235 (9004) and later.
Returns:
the matching ModelType.

getHardwareOptionsFromDeviceID

public static java.lang.String getHardwareOptionsFromDeviceID(java.lang.String deviceID)
Determine the descriptive hardware options String from the String returned from Commands.getDeviceMetaInfo(DeviceContext). This value is used to populate DeviceMetaInfo.getHardwareOptions().

Parameters:
deviceID - the DeviceID as returned to us from the device via AMP. This String may look like "9002-XS40-03" in the case of 9003's and earlier, or it may look like "923522X" in the case of 9235 (9004) and later.
Returns:
the String which describes the hardware options. This will probably require more mapping to be human-readable.

getCurrentAMPVersionFromGetDeviceInfoResponse

public static java.lang.String getCurrentAMPVersionFromGetDeviceInfoResponse(java.lang.String ampVersion)
Determine the current AMP version

Parameters:
ampVersion - A String containing the supported AMP version such as "1.0", "2.0" or "3.0".
Returns:
the String representing the current AMP version for the device. If the input string was null, current AMP version is defaulted to "1.0".

setSourceFirmwareLevel

public void setSourceFirmwareLevel(java.lang.String desiredLevel)
                            throws DeletedException,
                                   NotExistException,
                                   DeviceTypeIncompatibilityException,
                                   ModelTypeIncompatibilityException,
                                   MissingFeaturesInFirmwareException,
                                   UnlicensedFeaturesInFirmwareException

An alternative to setSourceFirmwareVersion(FirmwareVersion), this method accepts a firmware "level" (e.g., "3.8.0.1") instead of a specific FirmwareVersion object. It looks for the best match in the Manager. An appropriate match must have been previously loaded into the Manager, otherwise a NotExistException will be thrown.

Set the firmware to be deployed by deploySourceFirmwareVersion() to the best matching firmware version according to Manager.getBestFirmware(DeviceType, ModelType, StringCollection, String).

Firmware management operations are disabled on zBX. The operation will not be executed. An informational message will be logged.

Parameters:
desiredLevel -

setSourceFirmwareVersion

public ProgressContainer setSourceFirmwareVersion(FirmwareVersion desiredFirmwareVersion)
                                           throws DeletedException,
                                                  FullException,
                                                  NotExistException,
                                                  DeviceTypeIncompatibilityException,
                                                  ModelTypeIncompatibilityException,
                                                  MissingFeaturesInFirmwareException,
                                                  UnlicensedFeaturesInFirmwareException
Schedules a task to set the FirmwareVersion for this device. This task is available to a unmanaged device or a device in a managed set. A subscription is not required to perform this task.

Firmware management operations are disabled on zBX. The operation will not be executed. An informational message will be logged.

Use Firmware.getIncompatibilityReason to check for failures.

Parameters:
desiredFirmwareVersion -
Returns:
ProgressContainer. Check for completion and error.

getSourceFirmwareVersion

public FirmwareVersion getSourceFirmwareVersion()
Returns the source FirmwareVersion that is set for this device.

Returns:
the source FirmwareVersion for the device

deploySourceFirmwareVersion

public ProgressContainer deploySourceFirmwareVersion()
                                              throws DeletedException,
                                                     FullException
Schedules a task to deploy a FirmwareVersion. This task is available to a unmanaged device or a device in a managed set. A subscription is not required to perform this task. Input firmware version is optional. Note: All Firmware operations are disabled on zBX.

Returns:
ProgressContainer
See Also:
setSourceFirmwareVersion(FirmwareVersion), ManagedSet.setSourceFirmwareLevel(String)

getCommands

public Commands getCommands()
                     throws AMPException
Get the commands implementation to use for this device.


getSOMACommands

public SOMACommands getSOMACommands()
                             throws SOMAException
Get the SOMA commands implementation to use for this device.


setSynchronizationModeForManagedDomains

public java.util.Hashtable setSynchronizationModeForManagedDomains(DomainSynchronizationMode synchMode)
                                                            throws DeletedException,
                                                                   FullException
Set the Synchronization Mode for the all domains on device. Synchronization mode defaults to DomainSynchronizationMode.MANUAL. Valid synchronization modes are DomainSynchronizationMode.MANUAL and DomainSynchronizationMode.AUTO

Parameters:
synchMode - sSynch Mode to be set on the managed domains for this Device
Returns:
Hashtable of failed Domains - with Domain(key)/Exception(value)
See Also:
DomainSynchronizationMode.AUTO, DomainSynchronizationMode.MANUAL, ManagedSet.setSynchronizationModeForDomain(String, DomainSynchronizationMode)

backup

public ProgressContainer backup(java.lang.String cryptoCertificateName,
                                URLSource cryptoImage,
                                java.net.URI backupDestination,
                                boolean includeISCSI,
                                boolean includeRaid)
                         throws DatastoreException,
                                LockBusyException,
                                DeletedException,
                                FullException,
                                InvalidParameterException,
                                java.net.URISyntaxException,
                                MissingFeaturesInFirmwareException

Takes a backup of a DataPower appliance which can be replicated to a compatible appliance. A compatible appliance is one that has the identical firmware level and storage space. The main purpose of this function is disaster recovery, but it can also be used to take the configurations from one appliance and replicate it on another appliance. This task is available to a unmanaged device or a device in a managed set. This is a long running task that will be placed on a queue.

For more information about the backup capability in a DataPower appliance see the link to article provided below.

Find information about generating keys and certificates using Crypto Tools and Crypto Identification Credentials in the infocenter. See links provided below.

Use this to backup a device so that its state can be restored if the device fails or becomes inoperable. A Crypto Certificate is used for the encryption during backup and the corresponding Crypto Identification Credential will be required for later for a successful restore.


This operation is available on managed and unmanaged devices and must satisfy minimum firmware level requirements.

If secure backup fails to complete successfully, check the system logs on the DataPower appliance for further details.

NOTE: This function is available only if you enabled disaster recovery mode during the initial firmware setup of the appliance. If not enabled, you must reinitialize the appliance and enable disaster recovery. To determine if disaster recovery is available, click Administration -> Device-> System Settings. If the Backup Mode property is set to Secure, disaster recovery is available.

Parameters:
cryptoCertificateName - certificate object name on the Device. This is the Crypto Certificate used for the encryption The corresponding Crypto Identification Credential will be required for the secure restore.
cryptoImage - - the location of the certificate used to encrypt the backup. Must be file, http or https. The cryptoCertificate or the certObjectName must be specified. Both cannot be specified; one of them must be null.
backupDestination - is the URI of a directory where the backup files will be written. Supported protocols are "local:", "temporary:", "ftp:" and "file:". The location must be a directory, not a file name. All backup will be copied to the destination. If the specified destination is a "file:", any existing backup files will be overwritten.
includeISCSI - A value of "true" will include the iSCSI device data in the secure-backup files. A value of "false" will omit the iSCSI device data in the secure-backup files.
includeRaid - A value of "true" will include the RAID device data in the secure-backup files. A value of "false" will omit the RAID device data in the secure-backup files.

Sample Usage:

To backup with cryptoCertificateName
-->
URI backupFileLocation = new URI ("local:///Backup");
String certName="myCert";
ProgressContainer pg1 = device1.backup(certName, null, backupFileLocation, false, false);

To backup with cryptoImage location specified
--> String certificateLocation = new URLSource("file:///c:/l3/myCert-sscert.pem");
ProgressContainer pg1 = device1.backup(null, certificateLocation , backupFileLocation,false,false);

Returns:
ProgressContainer which will indicate if the task completed successfully
See Also:
Secure backup-restore for WebSphere DataPower SOA Appliances, a developerWorks Article
, Generating keys and certificates using Crypto Tools
, Crypto Indentification Credential

restore

public ProgressContainer restore(java.lang.String cryptoCredentialName,
                                 java.net.URI backupSource,
                                 boolean validate)
                          throws NotExistException,
                                 DatastoreException,
                                 LockBusyException,
                                 DeletedException,
                                 FullException,
                                 InvalidParameterException,
                                 java.net.URISyntaxException,
                                 MissingFeaturesInFirmwareException,
                                 java.io.IOException,
                                 InUseException,
                                 NotEmptyException

Restores the configuration and secure data from a successful secure backup. The main purpose of this function is disaster recovery, but it can also be used to take the configurations from one appliance and replicate it on another applicance. It can be used to restore a device that has been remanufactured or replaced to its previous state.

This task is available to a unmanaged device or a device in a managed set. This is a long running task that will be placed on a queue. This operation must also satisfy minimum firmware level requirements.

For more information about the restore capability in a DataPower appliance see the link to article provided below.

Find information about generating keys and certificates using Crypto Tools and Crypto Identification Credentials in the infocenter. See links provided below.

If restore fails to complete successfully, check the system logs on the DataPower applicance for further details.

If the device is an "managed device", it will be removed from its managed set on successful completion. The clientAPI user should delete the device object and recreate a new device object, since the earlier object may not reflect the current restored configuration.

Note: When the restore operation completes, the appliance will have an administrator user id of "admin" and a preset password. The password change must be done through the webGUI or the command line and cannot be done with the manager.

The disaster recovery mode will be enabled on the device as a result of the restore operation, if it was not previously enabled. To determine if disaster recovery is available, click Administration -> Device-> System Settings. If the Backup Mode property is set to Secure, disaster recovery is available.

Note: Restore operation is disabled on zBX.

Sample Usage:

To validate restore with cryptoCredentialName
-->
URI backupFileLocation = new URI ("local:///Backup");
String cryptoCredentialName = "myCertCID";
ProgressContainer pg3 = device1.restore(cryptoCredentialName, backupFileLocation,true);;

To perform restore from backup files
-->
URI backupFileLocation = new URI ("local:///Backup");
* String cryptoCredentialName = "myCertCID";
ProgressContainer pg3 = device1.restore(cryptoCredentialName, backupFileLocation,false);;

Parameters:
cryptoCredentialName - is the object name of the Crypto Identification Credentials which includes the private Crypyto Key and the Certificate. It used to decrypt the backup files.
backupSource - the location of the backup files which will be used to restore the device configuration. It is the URI of a directory where the backup files are available. Supported protocols are "local:", "temporary:", "ftp:" and "file:". The location must be a directory, not a file name.
validate - if true will check for items such as firmware compatibility, the manifest file's digital signature, and auxillary storage matches. The Validate option only performs the validation between the backup files and the appliance to be restored. The restore itself not initiated.
Returns:
ProgressContainer that will indicate the success of the task
See Also:
Secure backup-restore for WebSphere DataPower SOA Appliances, a developerWorks Article
, Generating keys and certificates using Crypto Tools
, Crypto Indentification Credential

quiesce

public void quiesce()
             throws AMPException,
                    DeletedException,
                    UnsuccessfulOperationException
Quiesce all the domains on a device (managed domains and unmanaged domains). This can be used before an operation that affects the entire device, like a firmware update.


unquiesce

public void unquiesce()
               throws AMPException,
                      DeletedException,
                      UnsuccessfulOperationException
Unquiesce all the domains on a device (managed domains and unmanaged domains). This method is complimentary to quiesce()


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.

This value only pertains to Firmware levels 3.8.1.0 or later. Earlier levels of firmware do not support quiesce.

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

isSecureBackupSupported

public boolean isSecureBackupSupported()
Check if secure backup is enabled on the device. Thie method is only supported on device with AMP v3. If it's invoked on a device that does not support AMP v3, UnsupportedOperationException will be thrown.


isPrimary

public boolean isPrimary()
Check if the device is primary.


acceptLicenseForFirmware

public void acceptLicenseForFirmware()
Assert license acceptance for subsequent firmware update.


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

reboot

public ProgressContainer reboot()
                         throws DeletedException,
                                FullException
reboot this device.



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