com.ibm.datapower.wamt.amp
Interface Commands


public interface Commands

A list of high-level commands that the DataPower device should support via SOAP invocation. These are commands sent from a manager to the device. Note that there is additional event communication sent from the device to the manager via Notification. These commands are long-running methods that contact the device via the network and will block until the device responds that the command has been completed. For the reason of being long-running with the potential for high variability in the completion time, it is recommended that you invoke these methods on a different thread than what may be running an interactive user interface.

This communication currently is scoped only for multi-box management. It does not include future requirements for application enablement. This should be an interface instead of a class, because it is expected that there may be more than one AMP client implementation.

See Also:
Notification

Field Summary
static int BACKUP_DEVICE
           
static java.lang.String COPYRIGHT_2009_2012
           
static int DELETE_DOMAIN
           
static int DELETE_FILE
           
static int DELETE_SERVICE
           
static int GET_DEVICE_METAINFO
           
static int GET_DOMAIN
           
static int GET_DOMAIN_DIFFERENCES
           
static int GET_DOMAIN_LIST
           
static int GET_DOMAIN_STATUS
           
static int GET_ERROR_REPORT
           
static int GET_INTERDEPENDENT_SERVICES_FILE
           
static int GET_INTERDEPENDENT_SERVICES_IMAGE
           
static int GET_KEY_FILENAMES
           
static int GET_REFERENCED_OBJECTS
           
static int GET_SAML_TOKEN
           
static int GET_SERVICE_LIST_FROM_DOMAIN
           
static int GET_SERVICE_LIST_FROM_EXPORT_FILE
           
static int GET_SERVICE_LIST_FROM_EXPORT_IMAGE
           
static int IS_DOMAIN_DIFFERENT
           
static int PING_DEVICE
           
static int QUIESCE_DEVICE
           
static int QUIESCE_DOMAIN
           
static int QUIESCE_SERVICE
           
static int REBOOT
           
static int RESTART_DOMAIN
           
static int RESTORE_DEVICE
           
static java.lang.String SCM_REVISION
           
static int SET_DOMAIN
           
static int SET_DOMAIN_BY_SERVICE_FILE
           
static int SET_DOMAIN_BY_SERVICE_IMAGE
           
static int SET_FILE
           
static int SET_FIRMWARE_IMAGE
           
static int SET_FIRMWARE_IMAGE_ACCEPT_LICENSE
           
static int SET_FIRMWARE_STREAM
           
static int SET_FIRMWARE_STREAM_ACCEPT_LICENSE
           
static int START_DOMAIN
           
static int START_SERVICE
           
static int STOP_DOMAIN
           
static int STOP_SERVICE
           
static int SUBSCRIBE_TO_DEVICE
           
static int UNQUIESCE_DEVICE
           
static int UNQUIESCE_DOMAIN
           
static int UNQUIESCE_SERVICE
           
static int UNSUBSCRIBE_FROM_DEVICE
           
 
Method Summary
 java.util.Hashtable backupDevice(DeviceContext device, java.lang.String cryptoCertificateName, byte[] cryptoImage, java.lang.String secureBackupDestination, boolean includeISCSI, boolean includeRaid)
          Perform a backup of the entire device.
 void deleteDomain(DeviceContext device, java.lang.String domainName)
          Delete a DataPower domain and all the contents of that domain from the specified device.
 void deleteFile(DeviceContext device, java.lang.String domainName, java.lang.String fileNameOnDevice)
          Delete a file to the persistent store on the device.
 DeleteObjectResult[] deleteService(DeviceContext device, java.lang.String domainName, java.lang.String objectName, java.lang.String objectClassName, ConfigObject[] excludeObjects, boolean deleteReferencedFiles)
          Given domain name, service class, service name, delete the service object and all its dependent objects.
 DeviceMetaInfo getDeviceMetaInfo(DeviceContext device)
          Get the high-level information about this device, as listed in DeviceMetaInfo.
 byte[] getDomain(DeviceContext device, java.lang.String domainName)
          Get a domain from the device into an opaque blob (byte array).
 java.net.URL getDomainDifferences(java.lang.String domainName, byte[] configImage1, byte[] configImage2, DeviceContext device)
          Compare two configuration images obtained from getDomainViaBackup, and return a URL where the differences can be viewed.
 java.lang.String[] getDomainList(DeviceContext device)
          Get a list of all the domains on the specified device, even the ones not managed by any external manager.
 DomainStatus getDomainStatus(DeviceContext device, java.lang.String domainName)
          Get the domain status (op-state).
 ErrorReport getErrorReport(DeviceContext device)
          Retrieve error report stored on the device.
 InterDependentServiceCollection getInterDependentServices(DeviceContext device, java.lang.String domainName, byte[] packageImage, ConfigObject[] objectArray)
          Getting inter-dependent service on device.
 InterDependentServiceCollection getInterDependentServices(DeviceContext device, java.lang.String domainName, java.lang.String fileDomainName, java.lang.String fileNameOnDevice, ConfigObject[] objects)
          Getting inter-dependent service on device.
 java.lang.String[] getKeyFilenames(DeviceContext device, java.lang.String domainName)
          For the specified domain, get a list of filenames of items in the special device filestores that are used by services in this domain.
 ReferencedObjectCollection getReferencedObjects(DeviceContext device, java.lang.String domainName, java.lang.String objectName, java.lang.String objectClassName)
          Get the referenced objects
 java.lang.String getSAMLToken(DeviceContext device, java.lang.String domainName)
          Retrieve a SAML token for automatic login to the WebGUI.
 RuntimeService[] getServiceListFromDomain(DeviceContext device, java.lang.String domainName)
          Getting all the services under that domain together with their status.
 ConfigService[] getServiceListFromExport(DeviceContext device, byte[] packageImage)
          Getting all services from an export/backup package.
 ConfigService[] getServiceListFromExport(DeviceContext device, java.lang.String fileDomainName, java.lang.String fileNameOnDevice)
          Getting all services from an export/backup package.
 boolean isDomainDifferent(java.lang.String domainName, byte[] configImage1, byte[] configImage2, DeviceContext device)
          Compare two configuration images obtained from getDomain(DeviceContext, String), and see if they are equivalent.
 PingResponse pingDevice(DeviceContext device, java.lang.String subscriptionID)
          This is used periodically to send a heartbeat request to a device and verify that it responds, and to check on the subscription state.
 void quiesceDevice(DeviceContext device, int timeout)
          Quiesce a device.
 void quiesceDomain(DeviceContext device, java.lang.String domain, int timeout)
          Quiesce a domain.
 void quiesceService(DeviceContext device, java.lang.String domain, ConfigObject[] objects, int timeout)
          Quiesce all the services specified in the request for the domain.
 void reboot(DeviceContext device)
          Reboot the referenced device, based on the Shutdown -> Reboot System command in the System Control menu of the WebGUI.
 void restartDomain(DeviceContext device, java.lang.String domainName)
          Restart the referenced domain on the referenced device, based on the action of the same name in the System Control menu of the WebGUI.
 void restoreDevice(DeviceContext device, java.lang.String cryptoCredentialName, boolean validate, java.net.URI secureBackupSource, java.util.Hashtable<java.lang.String,byte[]> backupFilesTable)
          Restore a device from a backup.
 void setDomain(DeviceContext device, java.lang.String domainName, byte[] domainImage, DeploymentPolicy policy)
          Load a domain onto a device using an image that was previously retrived via getDomain(DeviceContext, String).
 void setDomainByService(DeviceContext device, java.lang.String domainName, ConfigObject[] objects, byte[] domainImage, DeploymentPolicy policy, boolean importAllFiles)
          Given an export/backup package, a domain name and a list of services, all the dependent configuration objects and files will be deploied to the specified domain.
 void setDomainByService(DeviceContext device, java.lang.String domainName, ConfigObject[] objects, java.lang.String fileDomainName, java.lang.String fileNameOnDevice, DeploymentPolicy policy, boolean importAllFiles)
          Given an export/backup package, a domain name and a list of services, all the dependent configuration objects and files will be deploy to the specified domain.
 void setFile(DeviceContext device, java.lang.String domainName, java.lang.String filenameOnDevice, byte[] contents)
          Send a file to the persistent store on the device.
 void setFirmware(DeviceContext device, byte[] firmwareImage)
          Deprecated. 
 void setFirmware(DeviceContext device, byte[] firmwareImage, boolean acceptLicense)
          Transmit the specified firmware image into the device, make it the active firmware.
 void setFirmware(DeviceContext device, java.io.InputStream inputStream)
          Deprecated. 
 void setFirmware(DeviceContext device, java.io.InputStream inputStream, boolean acceptLicense)
          Same as setFirmware(DeviceContext, byte[], boolean), but allows for the large boot image to be specified in in a stream instead of in-memory byte array.
 void startDomain(DeviceContext device, java.lang.String domainName)
          Set the domain op-state to "up".
 void startService(DeviceContext device, java.lang.String domainName, ConfigObject[] objects)
          Start a service by changing its administrative state to "enabled"
 void stopDomain(DeviceContext device, java.lang.String domainName)
          Set the domain op-state to "down".
 void stopService(DeviceContext device, java.lang.String domainName, ConfigObject[] objects)
          Stop a service by changing its administrative state to "disabled"
 SubscriptionResponseCode subscribeToDevice(DeviceContext device, java.lang.String subscriptionId, StringCollection topics, java.net.URL callback)
          Create a subscription so that the device will inform the callback when a configuration change or related action happens on the specified device.
 void unquiesceDevice(DeviceContext device)
          Unquiesce a device, which brings the device to an operationally ready state.
 void unquiesceDomain(DeviceContext device, java.lang.String domain)
          Unquiesce a domain which brings the domain objects to an operationally ready state.
 void unquiesceService(DeviceContext device, java.lang.String domainName, ConfigObject[] objects)
          UnQuiesce all the services specified in the request for the specified domain.
 void unsubscribeFromDevice(DeviceContext device, java.lang.String subscriptionID, StringCollection topics)
          Delete a subscription that was created with subscribeToDevice(DeviceContext, String, StringCollection, URL).
 

Field Detail

COPYRIGHT_2009_2012

static final java.lang.String COPYRIGHT_2009_2012
See Also:
Constant Field Values

SCM_REVISION

static final java.lang.String SCM_REVISION
See Also:
Constant Field Values

BACKUP_DEVICE

static final int BACKUP_DEVICE
See Also:
Constant Field Values

DELETE_DOMAIN

static final int DELETE_DOMAIN
See Also:
Constant Field Values

DELETE_FILE

static final int DELETE_FILE
See Also:
Constant Field Values

DELETE_SERVICE

static final int DELETE_SERVICE
See Also:
Constant Field Values

GET_DEVICE_METAINFO

static final int GET_DEVICE_METAINFO
See Also:
Constant Field Values

GET_DOMAIN

static final int GET_DOMAIN
See Also:
Constant Field Values

GET_DOMAIN_DIFFERENCES

static final int GET_DOMAIN_DIFFERENCES
See Also:
Constant Field Values

GET_DOMAIN_LIST

static final int GET_DOMAIN_LIST
See Also:
Constant Field Values

GET_DOMAIN_STATUS

static final int GET_DOMAIN_STATUS
See Also:
Constant Field Values

GET_ERROR_REPORT

static final int GET_ERROR_REPORT
See Also:
Constant Field Values

GET_INTERDEPENDENT_SERVICES_IMAGE

static final int GET_INTERDEPENDENT_SERVICES_IMAGE
See Also:
Constant Field Values

GET_INTERDEPENDENT_SERVICES_FILE

static final int GET_INTERDEPENDENT_SERVICES_FILE
See Also:
Constant Field Values

GET_KEY_FILENAMES

static final int GET_KEY_FILENAMES
See Also:
Constant Field Values

GET_REFERENCED_OBJECTS

static final int GET_REFERENCED_OBJECTS
See Also:
Constant Field Values

GET_SAML_TOKEN

static final int GET_SAML_TOKEN
See Also:
Constant Field Values

GET_SERVICE_LIST_FROM_DOMAIN

static final int GET_SERVICE_LIST_FROM_DOMAIN
See Also:
Constant Field Values

GET_SERVICE_LIST_FROM_EXPORT_IMAGE

static final int GET_SERVICE_LIST_FROM_EXPORT_IMAGE
See Also:
Constant Field Values

GET_SERVICE_LIST_FROM_EXPORT_FILE

static final int GET_SERVICE_LIST_FROM_EXPORT_FILE
See Also:
Constant Field Values

IS_DOMAIN_DIFFERENT

static final int IS_DOMAIN_DIFFERENT
See Also:
Constant Field Values

PING_DEVICE

static final int PING_DEVICE
See Also:
Constant Field Values

QUIESCE_DEVICE

static final int QUIESCE_DEVICE
See Also:
Constant Field Values

QUIESCE_DOMAIN

static final int QUIESCE_DOMAIN
See Also:
Constant Field Values

QUIESCE_SERVICE

static final int QUIESCE_SERVICE
See Also:
Constant Field Values

REBOOT

static final int REBOOT
See Also:
Constant Field Values

RESTART_DOMAIN

static final int RESTART_DOMAIN
See Also:
Constant Field Values

RESTORE_DEVICE

static final int RESTORE_DEVICE
See Also:
Constant Field Values

SET_DOMAIN

static final int SET_DOMAIN
See Also:
Constant Field Values

SET_DOMAIN_BY_SERVICE_IMAGE

static final int SET_DOMAIN_BY_SERVICE_IMAGE
See Also:
Constant Field Values

SET_DOMAIN_BY_SERVICE_FILE

static final int SET_DOMAIN_BY_SERVICE_FILE
See Also:
Constant Field Values

SET_FILE

static final int SET_FILE
See Also:
Constant Field Values

SET_FIRMWARE_IMAGE

static final int SET_FIRMWARE_IMAGE
See Also:
Constant Field Values

SET_FIRMWARE_STREAM

static final int SET_FIRMWARE_STREAM
See Also:
Constant Field Values

SET_FIRMWARE_IMAGE_ACCEPT_LICENSE

static final int SET_FIRMWARE_IMAGE_ACCEPT_LICENSE
See Also:
Constant Field Values

SET_FIRMWARE_STREAM_ACCEPT_LICENSE

static final int SET_FIRMWARE_STREAM_ACCEPT_LICENSE
See Also:
Constant Field Values

START_DOMAIN

static final int START_DOMAIN
See Also:
Constant Field Values

STOP_DOMAIN

static final int STOP_DOMAIN
See Also:
Constant Field Values

START_SERVICE

static final int START_SERVICE
See Also:
Constant Field Values

STOP_SERVICE

static final int STOP_SERVICE
See Also:
Constant Field Values

SUBSCRIBE_TO_DEVICE

static final int SUBSCRIBE_TO_DEVICE
See Also:
Constant Field Values

UNQUIESCE_DEVICE

static final int UNQUIESCE_DEVICE
See Also:
Constant Field Values

UNQUIESCE_DOMAIN

static final int UNQUIESCE_DOMAIN
See Also:
Constant Field Values

UNQUIESCE_SERVICE

static final int UNQUIESCE_SERVICE
See Also:
Constant Field Values

UNSUBSCRIBE_FROM_DEVICE

static final int UNSUBSCRIBE_FROM_DEVICE
See Also:
Constant Field Values
Method Detail

subscribeToDevice

SubscriptionResponseCode subscribeToDevice(DeviceContext device,
                                           java.lang.String subscriptionId,
                                           StringCollection topics,
                                           java.net.URL callback)
                                           throws InvalidCredentialsException,
                                                  AMPIOException,
                                                  DeviceExecutionException,
                                                  AMPException
Create a subscription so that the device will inform the callback when a configuration change or related action happens on the specified device. For a list of the events that we should be notified of see Notification. If an attempt is made to create a duplicate subscription to the same device with the same topic, this will not result in receiving duplicate notifications. Only one manager may be subscribed to a device at a time. To check the status of the subscription, use pingDevice(DeviceContext, String).

Parameters:
device - the DataPower device that the subscriber wants to monitor
subscriptionId - This id is used later to unsubscribe via unsubscribeFromDevice(DeviceContext, String, StringCollection), and to check the status of the subscription via pingDevice(DeviceContext, String). This value should be unique for each subscriber, so it is up to the subscriber to pick unique ids that will not have collisions on the device.
topics - a collection of String values indicating the topic(s) on the device to subscribe to
callback - a URL in the subscriber that should be invoked by the device to send the notification from the device to the subscriber
Returns:
a code which indicates if the subscription was successful.
See Also:
unsubscribeFromDevice(DeviceContext, String, StringCollection), pingDevice(DeviceContext, String), Notification, NotificationCatcher

unsubscribeFromDevice

void unsubscribeFromDevice(DeviceContext device,
                           java.lang.String subscriptionID,
                           StringCollection topics)
                           throws NotExistException,
                                  InvalidCredentialsException,
                                  DeviceExecutionException,
                                  AMPIOException,
                                  AMPException
Delete a subscription that was created with subscribeToDevice(DeviceContext, String, StringCollection, URL). To check the status of the subscription, use pingDevice(DeviceContext, String).

Parameters:
device - the DataPower device that the subscriber is monitoring
subscriptionID - the subscription id that was returned from subscribeToDevice(DeviceContext, String, StringCollection, URL)
topics - a collection of String values indicating the topic(s) on the device to unsubscribe from
See Also:
subscribeToDevice(DeviceContext, String, StringCollection, URL), pingDevice(DeviceContext, String)

pingDevice

PingResponse pingDevice(DeviceContext device,
                        java.lang.String subscriptionID)
                        throws InvalidCredentialsException,
                               DeviceExecutionException,
                               AMPIOException,
                               AMPException
This is used periodically to send a heartbeat request to a device and verify that it responds, and to check on the subscription state. It will block until a response is received or an error condition occurs (timeout, invalid device credentials, etc).

Parameters:
device - the DataPower device to query
subscriptionID - the subscription id that was returned from subscribeToDevice(DeviceContext, String, StringCollection, URL). This will keep the subscription alive on the device, and it will enable the device to indicate in a PingResponse any error state regarding the subscription.
Returns:
a PingResponse, which indicates the state of the subscription on the device.
See Also:
PingResponse, getDeviceMetaInfo(DeviceContext)

getDeviceMetaInfo

DeviceMetaInfo getDeviceMetaInfo(DeviceContext device)
                                 throws InvalidCredentialsException,
                                        DeviceExecutionException,
                                        AMPIOException,
                                        AMPException
Get the high-level information about this device, as listed in DeviceMetaInfo. This info is unlikely to change frequently. All of the returned data will be treated as read-only.

Parameters:
device - the DataPower device to query.
Returns:
a collection of device attributes
See Also:
DeviceMetaInfo, PingResponse

reboot

void reboot(DeviceContext device)
            throws InvalidCredentialsException,
                   DeviceExecutionException,
                   AMPIOException,
                   AMPException
Reboot the referenced device, based on the Shutdown -> Reboot System command in the System Control menu of the WebGUI.

Parameters:
device - the device to reboot
See Also:
restartDomain(DeviceContext, String)

getDomainList

java.lang.String[] getDomainList(DeviceContext device)
                                 throws InvalidCredentialsException,
                                        DeviceExecutionException,
                                        AMPIOException,
                                        AMPException
Get a list of all the domains on the specified device, even the ones not managed by any external manager.

Parameters:
device - the DataPower device to query.
Returns:
a String array representation of domain names. Each item in this array should be a single domain name. These same String values can be used on other methods that require a domain name. The "default" domain will be included in this list.

getDomain

byte[] getDomain(DeviceContext device,
                 java.lang.String domainName)
                 throws NotExistException,
                        InvalidCredentialsException,
                        DeviceExecutionException,
                        AMPIOException,
                        AMPException
Get a domain from the device into an opaque blob (byte array). In DataPower terms, this is a Backup instead of an Export, as we want all the referenced files via a Backup. If you invoke this method on the "default" domain it will include only the service configuration objects.

Note that this does not include any items from the cert:, sharedcert:, or pubcert: filestores. Items in those filestores will not be obtained using this method, as those filestores are considered unexportable via AMP, WebGUI, and CLI. It will be the responsbility of the user to manually copy items in those filestores to each device device from their own external store.

Parameters:
device - the DataPower device from which to export the domain
domainName - the domain on the device to export
Returns:
an opaque blob that represents the domain. The code does not care about the contents of this blob, other than it needs to be in a form that the device can recognized later in setDomain. Note that this blob probably (depending upon the implementation) is a zip file in the same format as if you had performed a "Create backup of one or more application domains" from the WebGUI, and you could also use this content on a "Compare Configuration" in the WebGUI as a "Backup ZIP Bundle". Additionally, this content may be Base64 encoded (again, depending on the implementation).
See Also:
setDomain(DeviceContext, String, byte[], DeploymentPolicy)

setDomain

void setDomain(DeviceContext device,
               java.lang.String domainName,
               byte[] domainImage,
               DeploymentPolicy policy)
               throws InvalidCredentialsException,
                      DeviceExecutionException,
                      AMPIOException,
                      AMPException,
                      DeletedException
Load a domain onto a device using an image that was previously retrived via getDomain(DeviceContext, String). In DataPower terms, this is a Restore instead of an Import, as we want all the referenced files, not only the configuration objects. This can also be used to install domains on a device different from where it was originally retrieved. This method should delete any domain of the same name that already exists on the device, load this domain into the running configuration, start all the services that are in this domain, mark the domain as runnable (op-state up), and persist it to the device's non-volatile storage (save config).

If a domain was backed up from a device that has a different firmware version that the device it is being restored/installed to, it is assumed that the target device will handle any changes to the domain backup image that may be necessary for it to work properly on the target device.

If the domain is being installed to a different deviceType than it was retrieved from (i.e., XS40), it is assumed that loading the domain to a higher function device (i.e., XI50) will work appropriately. Installing the domain on a lower function device (i.e., XA35) may result in domain services that do not behave as desired. Because of this, the caller also needs to keep track of the deviceType that this domain was exported from.

Parameters:
device - the DataPower device to which the domain is restored or installed
domainName - the name of the domain being loaded
domainImage - an opaque blob that represents the domain. This is the same blob that was obtained from getDomain(DeviceContext, String), see the javadoc for that method for more information about this blob.
policy - a deployment policy to be used when setting the domain
See Also:
getDomain(DeviceContext, String), deleteDomain(DeviceContext, String)

deleteDomain

void deleteDomain(DeviceContext device,
                  java.lang.String domainName)
                  throws NotExistException,
                         InvalidCredentialsException,
                         DeviceExecutionException,
                         AMPIOException,
                         AMPException
Delete a DataPower domain and all the contents of that domain from the specified device.

Parameters:
device - the DataPower device from which to delete the named domain
domainName - the domain on that device to delete. The default domain cannot be deleted.
See Also:
setDomain(DeviceContext, String, byte[], DeploymentPolicy)

getDomainStatus

DomainStatus getDomainStatus(DeviceContext device,
                             java.lang.String domainName)
                             throws NotExistException,
                                    InvalidCredentialsException,
                                    DeviceExecutionException,
                                    AMPIOException,
                                    AMPException
Get the domain status (op-state). The domain op-state is a rollup of all the services in the domain. A change in status should trigger a Notification.

Parameters:
device - the DataPower device on which the domain resides
domainName - the domain to get the status of
Returns:
a contains of status indicators
See Also:
Notification, startDomain(DeviceContext, String), stopDomain(DeviceContext, String)

startDomain

void startDomain(DeviceContext device,
                 java.lang.String domainName)
                 throws NotExistException,
                        InvalidCredentialsException,
                        DeviceExecutionException,
                        AMPIOException,
                        AMPException
Set the domain op-state to "up".

Parameters:
device - the device in which the domain resides
domainName - the name of the domain to start
See Also:
stopDomain(DeviceContext, String), getDomainStatus(DeviceContext, String)

stopDomain

void stopDomain(DeviceContext device,
                java.lang.String domainName)
                throws NotExistException,
                       InvalidCredentialsException,
                       DeviceExecutionException,
                       AMPIOException,
                       AMPException
Set the domain op-state to "down".

Parameters:
device - the device in which the domain resides
domainName - the name of the domain to stop
See Also:
startDomain(DeviceContext, String), getDomainStatus(DeviceContext, String)

restartDomain

void restartDomain(DeviceContext device,
                   java.lang.String domainName)
                   throws NotExistException,
                          InvalidCredentialsException,
                          DeviceExecutionException,
                          AMPIOException,
                          AMPException
Restart the referenced domain on the referenced device, based on the action of the same name in the System Control menu of the WebGUI.

Parameters:
device - the device in which the domain resides
domainName - the name of the domain to restart
See Also:
reboot(DeviceContext)

setFirmware

@Deprecated
void setFirmware(DeviceContext device,
                            byte[] firmwareImage)
                 throws InvalidCredentialsException,
                        DeviceExecutionException,
                        AMPIOException,
                        AMPException
Deprecated. 

Transmit the specified firmware image into the device, make it the active firmware.

If a change in the firmware causes either an existing configuration element to no longer be valid, or a missing configuration element to be required, it is assumed that the target device will handle any changes to the configuration element that may be necessary for it to work properly.

A single SOAP method on the device will be used by both this method and setFirmware(DeviceContext, InputStream). This method will return after the firmware has been installed and a reboot is scheduled.

Parameters:
device - the device to load the firmware onto
firmwareImage - an opaque blob firmware binary image as retrieved from the DataPower web site or from distributable media
See Also:
setFirmware(DeviceContext, InputStream)

setFirmware

@Deprecated
void setFirmware(DeviceContext device,
                            java.io.InputStream inputStream)
                 throws InvalidCredentialsException,
                        DeviceExecutionException,
                        AMPIOException,
                        AMPException
Deprecated. 

Same as setFirmware(DeviceContext, byte[]), but allows for the large boot image to be specified in in a stream instead of in-memory byte array. The image can be 20MB or larger, so for performance purposes you may not want it in a byte array.

A single SOAP method on the device will be used by both this method and setFirmware(DeviceContext, byte[]).

Parameters:
device - the device to load the firmware onto
inputStream - an inputStream to an opaque blob firmware binary image as retrieved from the DataPower web site or from distributable media. It is expected that this inputStream references content that is already base64-encoded. This is a special case not present on the other AMP commands. The reason for this is that firmware is such a large object 15-30MB that doing a base64 encode to prepare it for transmission each time it is transmitted to a device is a memory-intensive operation that we need to avoid. If it was unencoded, XMLBeans would create multiple copies of this large blob, which may blow up the heap size and cause out-of-memory errors. So to tune for this situation, the firmware blob is stored in the repository already encoded in base64 format, and thus does not need to be encoded for transmission to devices.
See Also:
setFirmware(DeviceContext, byte[])

getKeyFilenames

java.lang.String[] getKeyFilenames(DeviceContext device,
                                   java.lang.String domainName)
                                   throws InvalidCredentialsException,
                                          DeviceExecutionException,
                                          AMPIOException,
                                          AMPException
For the specified domain, get a list of filenames of items in the special device filestores that are used by services in this domain. This would include the cert:, sharedcert:, and pubcert: filestores. Those device filestores are considered unexportable. This means that items in these filestores will not be included in a domain backup, they need to be installed separately when installing the backup image. This method will enable the application to determine which keys are needed when installing the backup image. Those needed keys could be pulled from an external repository, or the administrator could be prompted to manually supply these key files. This does not export the keys from the device, it only provides their names. This is a nice-to-have, not a requirement.

Parameters:
device - the DataPower device which has the specified domain
domainName - the domain to check for key filenames
Returns:
an array of filenames in the format used by the device, i.e., cert:///mycert.pem. These filename should be usable in the setFile(DeviceContext, String, String, byte[])method and should include the name of the filestore.
See Also:
setFile(DeviceContext, String, String, byte[])

setFile

void setFile(DeviceContext device,
             java.lang.String domainName,
             java.lang.String filenameOnDevice,
             byte[] contents)
             throws NotExistException,
                    InvalidCredentialsException,
                    DeviceExecutionException,
                    AMPIOException,
                    AMPException
Send a file to the persistent store on the device. This will likely be used to install a key file to a device. The name of the key file may have been retrieved from getKeyFilenames(DeviceContext, String). But it could be used to install any file to any of the device filestores.

Parameters:
device - the DataPower device which has the specified domain
domainName - the domain in which to install the file
filenameOnDevice - the name of the file in the format used by the device, i.e., cert:///mycert.pem
contents - the raw file contents (i.e., no Base64 encoding)
See Also:
getKeyFilenames(DeviceContext, String)

isDomainDifferent

boolean isDomainDifferent(java.lang.String domainName,
                          byte[] configImage1,
                          byte[] configImage2,
                          DeviceContext device)
                          throws InvalidCredentialsException,
                                 DeviceExecutionException,
                                 AMPIOException,
                                 AMPException
Compare two configuration images obtained from getDomain(DeviceContext, String), and see if they are equivalent. Because this application does not have any knowledge of the device configuration object model (it is opaque), the diff is performed on the device.

See getDomainDifferences(String, byte[], byte[], DeviceContext) for an alternate way to visually display the blob differences.

Parameters:
domainName - the name of the domain specified in configImage1
configImage1 - an opaque blob obtained from getDomain()
configImage2 - an opaque blob obtained from getDomain() If this parameter is null, then the device should use its own persisted domain as the second input to the comparison. If this parameter is not null, then the comparison can be performed on any device, it does not require that the device already contain the domain, or that the device firmware match the firmware used when the domain was retrieved.
device - a device on which to execute the comparison
Returns:
true if there are differences, false if they are equivalent
See Also:
getDomainDifferences(String, byte[], byte[], DeviceContext)

getDomainDifferences

java.net.URL getDomainDifferences(java.lang.String domainName,
                                  byte[] configImage1,
                                  byte[] configImage2,
                                  DeviceContext device)
                                  throws InvalidCredentialsException,
                                         DeviceExecutionException,
                                         AMPIOException,
                                         AMPException
Compare two configuration images obtained from getDomainViaBackup, and return a URL where the differences can be viewed. Because the application does not have any knowledge of the device configuration object model (it is opaque), the diff is performed on the device.

Because the blob parameters are basically a ZIP backup (see getDomain(DeviceContext, String), you could also use the WebGUI (Compare Configuration - Backup ZIP Bundle) with these blobs as an alternate way to display the differences.

Parameters:
domainName - the name of the domain specified in configImage1
configImage1 - an opaque blob obtained from getDomain()
configImage2 - an opaque blob obtained from getDomain(). If this parameter is null, then the device should use its own persisted domain as the second input to the comparison. If this parameter is not null, then the comparison can be performed on any device, it does not require that the device already contain the domain, or that the device firmware match the firmware used when the domain was retrieved.
device - a device on which to execute the difference fetch. If configImage2 is not null, then the domain image does not need to exist on the device.
Returns:
a URL where a representation of the differences between the two configImages is rendered visually without requiring the application to have knowledge of the device configuration object model.
See Also:
isDomainDifferent(String, byte[], byte[], DeviceContext)

getErrorReport

ErrorReport getErrorReport(DeviceContext device)
                           throws InvalidCredentialsException,
                                  DeviceExecutionException,
                                  AMPIOException,
                                  AMPException
Retrieve error report stored on the device.

Parameters:
device - a device on which to retrieve the error report
Returns:
an ErrorReport object which lists the domain, location, filename, and actual bytes of the error report from the device

getSAMLToken

java.lang.String getSAMLToken(DeviceContext device,
                              java.lang.String domainName)
                              throws InvalidCredentialsException,
                                     DeviceExecutionException,
                                     AMPIOException,
                                     AMPException
Retrieve a SAML token for automatic login to the WebGUI. This SAML token (artifact) is needed when generating a URL so that an external web browser can automatically logon to the device's WebGUI (do not need to enter administrative userid and password in the web browser).

Parameters:
device - the deviceContext of the device on which to retrieve the SAML token from
domainName - the domainName to be forwarded to
Returns:
a String containing the SAML token

backupDevice

java.util.Hashtable backupDevice(DeviceContext device,
                                 java.lang.String cryptoCertificateName,
                                 byte[] cryptoImage,
                                 java.lang.String secureBackupDestination,
                                 boolean includeISCSI,
                                 boolean includeRaid)
                                 throws AMPIOException,
                                        InvalidCredentialsException,
                                        AMPException
Perform a backup of the entire device. The purpose is to be able to restore a device to the same state upon failure. This includes all configuration, crypto material, and user credentials from the device.

Parameters:
device - the deviceContext of the device to perform a backup on
cryptoCertificateName - the cyrpto certificate object name
cryptoImage - the content of the certificate used to encrypt the backup
secureBackupDestination - the location where the backed up files will be stored
Returns:
Hashtable with filenames as Key and byte[] as values

restoreDevice

void restoreDevice(DeviceContext device,
                   java.lang.String cryptoCredentialName,
                   boolean validate,
                   java.net.URI secureBackupSource,
                   java.util.Hashtable<java.lang.String,byte[]> backupFilesTable)
                   throws AMPIOException,
                          InvalidCredentialsException,
                          AMPException
Restore a device from a backup.

Parameters:
device - the deviceContext of the device to perform the restore
cryptoCredentialName - the object name of the Crypto Identification Credentials used to decrypt the backup
secureBackupSource - location of the backup files. This may be local: temporary: or ftp
backupFilesTable - a Hashtable with the file names(keys) and contents (values) of the backup file, if the were saved on a file system and have to embedded in the restore request

quiesceDomain

void quiesceDomain(DeviceContext device,
                   java.lang.String domain,
                   int timeout)
                   throws AMPIOException,
                          InvalidCredentialsException,
                          AMPException
Quiesce a domain. The purpose is to allow domain modifications or perform troubleshooting without affecting data traffic.

Parameters:
device - the deviceContext of the device containing the domain to quiesce
domain - the name of the domain to quiesce
timeout - the amount of time in seconds to wait for the quiesce to complete. Once the timeout is reached, existing connections may be terminated.

unquiesceDomain

void unquiesceDomain(DeviceContext device,
                     java.lang.String domain)
                     throws AMPIOException,
                            InvalidCredentialsException,
                            AMPException
Unquiesce a domain which brings the domain objects to an operationally ready state.

Parameters:
device - the deviceContext of the device containing the domain to unquiesce
domain - the name of the domain to unquiesce

quiesceDevice

void quiesceDevice(DeviceContext device,
                   int timeout)
                   throws AMPIOException,
                          InvalidCredentialsException,
                          AMPException
Quiesce a device. The purpose is to allow firmware modifications or perform troubleshooting without affecting data traffic.

Parameters:
device - the deviceContext of the device to quiesce
timeout - the amount of time in seconds to wait for the quiesce to complete. Once the timeout is reached, existing connections may be terminated.

unquiesceDevice

void unquiesceDevice(DeviceContext device)
                     throws AMPIOException,
                            InvalidCredentialsException,
                            AMPException
Unquiesce a device, which brings the device to an operationally ready state.

Parameters:
device - the deviceContext of the device to unquiesce

getServiceListFromDomain

RuntimeService[] getServiceListFromDomain(DeviceContext device,
                                          java.lang.String domainName)
                                          throws DeviceExecutionException,
                                                 AMPIOException,
                                                 AMPException
Getting all the services under that domain together with their status.

Parameters:
device - the DataPower device to query.
domainName - the domain on that device to get the service List
Returns:
a String array representation of all service. Each item in this array should be a configObject.

getInterDependentServices

InterDependentServiceCollection getInterDependentServices(DeviceContext device,
                                                          java.lang.String domainName,
                                                          java.lang.String fileDomainName,
                                                          java.lang.String fileNameOnDevice,
                                                          ConfigObject[] objects)
                                                          throws NotExistException,
                                                                 InvalidCredentialsException,
                                                                 DeviceExecutionException,
                                                                 AMPIOException,
                                                                 AMPException
Getting inter-dependent service on device. Given an export/backup package, a domain name and a list of services, return all the services in that domain on the device that are dependent with any of the dependent configuration objects of the specified services in the export package. The purpose is to check if the services to be deployed has any interdependencies with services already on device.

Parameters:
device - the DataPower device to query.
domainName - the domain on that device to get the inter dependent services
fileDomainName - the domain on that device to get the export/backup package
fileNameOnDevice - the name of export/backup package in the format used by the device, i.e., temporary:///package.zip
objectArray - the objects context array
Returns:
the InterDependentServiceCollection object
See Also:
getInterDependentServices(DeviceContext, String, byte[], ConfigObject[])

getInterDependentServices

InterDependentServiceCollection getInterDependentServices(DeviceContext device,
                                                          java.lang.String domainName,
                                                          byte[] packageImage,
                                                          ConfigObject[] objectArray)
                                                          throws NotExistException,
                                                                 InvalidCredentialsException,
                                                                 DeviceExecutionException,
                                                                 AMPIOException,
                                                                 AMPException
Getting inter-dependent service on device. Given an export/backup package, a domain name and a list of services, return all the services in that domain on the device that are dependent with any of the dependent configuration objects of the specified services in the export package. The purpose is to check if the services to be deployed has any interdependencies with services already on device.

Parameters:
device - the DataPower device to get the interDependentServices
domainName - the domain on that device to get the inter dependent services
packageImage - an opaque blob that represents the of export/backup package, It is expected that this packageImage content is already base64-encoded.
Returns:
the InterDependentServiceCollection object
See Also:
getInterDependentServices(DeviceContext, String, String, String, ConfigObject[])

getServiceListFromExport

ConfigService[] getServiceListFromExport(DeviceContext device,
                                         java.lang.String fileDomainName,
                                         java.lang.String fileNameOnDevice)
                                         throws NotExistException,
                                                InvalidCredentialsException,
                                                DeviceExecutionException,
                                                AMPIOException,
                                                AMPException
Getting all services from an export/backup package. Given an export/backup package, return list of services in that package that are supported on the device.

Parameters:
device - the DataPower device to get Service List from export/backup package
fileDomainName - the domain in which the export/backup package is
fileNameOnDevice - the name of export/backup package in the format used by the device, i.e., temporary:///package.zip
Returns:
the ConfigObject array contains the services
See Also:
getServiceListFromExport(DeviceContext, byte[])

getServiceListFromExport

ConfigService[] getServiceListFromExport(DeviceContext device,
                                         byte[] packageImage)
                                         throws NotExistException,
                                                InvalidCredentialsException,
                                                DeviceExecutionException,
                                                AMPIOException,
                                                AMPException
Getting all services from an export/backup package. Given an export/backup package, return list of services in that package that are supported on the device.

Parameters:
device - the DataPower device to get service list from export/backup package
packageImage - an opaque blob represents the export/backup package, It is expected that this packageImage content is already base64-encoded.
Returns:
the Service array contains the services
See Also:
getServiceListFromExport(DeviceContext, String, String)

getReferencedObjects

ReferencedObjectCollection getReferencedObjects(DeviceContext device,
                                                java.lang.String domainName,
                                                java.lang.String objectName,
                                                java.lang.String objectClassName)
                                                throws NotExistException,
                                                       InvalidCredentialsException,
                                                       DeviceExecutionException,
                                                       AMPIOException,
                                                       AMPException
Get the referenced objects

Parameters:
device - the DataPower device to get referenced objects
domainName - the domain in where the object to get the referenced
objectName - the name of object
objectClassName - the class name of the object
Returns:
the ObjectCollection object contains the detail of referenced objects

deleteService

DeleteObjectResult[] deleteService(DeviceContext device,
                                   java.lang.String domainName,
                                   java.lang.String objectName,
                                   java.lang.String objectClassName,
                                   ConfigObject[] excludeObjects,
                                   boolean deleteReferencedFiles)
                                   throws NotExistException,
                                          InvalidCredentialsException,
                                          DeviceExecutionException,
                                          AMPIOException,
                                          AMPException
Given domain name, service class, service name, delete the service object and all its dependent objects. If desired, user can specify the object they do NOT want to delete. The response will contain the deleting results for each object to indicate if an object is deleted or excluded

Parameters:
device - the DataPower device to delete service
domainName - the domain in which the service to be deleted
objectName - name of the service to be deleted
objectClassName - class name of the service to be delted
excludeObjects - Object array to be deleted exclusively
deleteReferencedFiles - a boolean value if delete the referenced files
Returns:
ConfigObjectStatus array contains the detail of sevices to be deleted

quiesceService

void quiesceService(DeviceContext device,
                    java.lang.String domain,
                    ConfigObject[] objects,
                    int timeout)
                    throws InvalidCredentialsException,
                           DeviceExecutionException,
                           AMPIOException,
                           AMPException
Quiesce all the services specified in the request for the domain. One timeout value will be used for all services.

Parameters:
device - the DataPower device to quiesce the service
domainName - the name of domain in which the services to be quiesced
objects - the service object to be quiesced
timeout - the amount of time in seconds to wait for the quiesce to complete. Once the timeout is reached, existing connections may be terminated.

unquiesceService

void unquiesceService(DeviceContext device,
                      java.lang.String domainName,
                      ConfigObject[] objects)
                      throws InvalidCredentialsException,
                             DeviceExecutionException,
                             AMPIOException,
                             AMPException
UnQuiesce all the services specified in the request for the specified domain.

Parameters:
device - the DataPower device to unquiesce the service
domainName - the name of domain in which the services to be unquiesced
objects - the service objects to be unquiesced

startService

void startService(DeviceContext device,
                  java.lang.String domainName,
                  ConfigObject[] objects)
                  throws InvalidCredentialsException,
                         DeviceExecutionException,
                         AMPIOException,
                         AMPException
Start a service by changing its administrative state to "enabled"

Parameters:
device - the DataPower device to start the services
domainName - the name of domain in which services to be started
objects - the service objects to be started

stopService

void stopService(DeviceContext device,
                 java.lang.String domainName,
                 ConfigObject[] objects)
                 throws InvalidCredentialsException,
                        DeviceExecutionException,
                        AMPIOException,
                        AMPException
Stop a service by changing its administrative state to "disabled"

Parameters:
device - the DataPower device to start the service
domainName - the name of domain in which services to be stoped
objects - the service objects to be stoped

setDomainByService

void setDomainByService(DeviceContext device,
                        java.lang.String domainName,
                        ConfigObject[] objects,
                        byte[] domainImage,
                        DeploymentPolicy policy,
                        boolean importAllFiles)
                        throws InvalidCredentialsException,
                               DeviceExecutionException,
                               AMPIOException,
                               AMPException,
                               DeletedException
Given an export/backup package, a domain name and a list of services, all the dependent configuration objects and files will be deploied to the specified domain. Objects and files with the same names will be overwritten. Dependent services should be quiesced separately first.

Parameters:
device - the DataPower device to which the domain is restored or installed.
domainName - the name of the domain being loaded
objects - services want to be set
domainImage - an opaque blob that represents the domain. This is the same blob that was obtained from getDomain(DeviceContext, String), see the javadoc for that method for more information about this blob.
policy - a deployment policy to be used when setting the domain
importAllFiles - a boolean value if import all files in the export/backup package
See Also:
quiesceService(DeviceContext, String, ConfigObject[], int)

setDomainByService

void setDomainByService(DeviceContext device,
                        java.lang.String domainName,
                        ConfigObject[] objects,
                        java.lang.String fileDomainName,
                        java.lang.String fileNameOnDevice,
                        DeploymentPolicy policy,
                        boolean importAllFiles)
                        throws InvalidCredentialsException,
                               DeviceExecutionException,
                               AMPIOException,
                               AMPException,
                               DeletedException
Given an export/backup package, a domain name and a list of services, all the dependent configuration objects and files will be deploy to the specified domain. Objects and files with the same names will be overwritten. Dependent services should be quiesced separately first.

Parameters:
device - the DataPower device to which the domain is restored or installed.
domainName - the name of the domain to be set
objects - services want to be set
fileDomainName - the domain in which to get the file
filenameOnDevice - the name of the file in the format used by the device, i.e., temporary:///package.zip *
policy - a deployment policy to be used when setting the domain
importAllFiles - a boolean value if import all files in the export/backup package

setFirmware

void setFirmware(DeviceContext device,
                 byte[] firmwareImage,
                 boolean acceptLicense)
                 throws InvalidCredentialsException,
                        DeviceExecutionException,
                        AMPIOException,
                        AMPException
Transmit the specified firmware image into the device, make it the active firmware.

If a change in the firmware causes either an existing configuration element to no longer be valid, or a missing configuration element to be required, it is assumed that the target device will handle any changes to the configuration element that may be necessary for it to work properly.

A single SOAP method on the device will be used by both this method and setFirmware(DeviceContext, InputStream). This method will return after the firmware has been installed and a reboot is scheduled.

Parameters:
device - the device to load the firmware onto
firmwareImage - an opaque blob firmware binary image as retrieved from the DataPower web site or from distributable media
acceptLicense - a boolean value if accept license, must be ture to continue the firmware setting.
See Also:
setFirmware(DeviceContext, InputStream)

setFirmware

void setFirmware(DeviceContext device,
                 java.io.InputStream inputStream,
                 boolean acceptLicense)
                 throws InvalidCredentialsException,
                        DeviceExecutionException,
                        AMPIOException,
                        AMPException
Same as setFirmware(DeviceContext, byte[], boolean), but allows for the large boot image to be specified in in a stream instead of in-memory byte array. The image can be 20MB or larger, so for performance purposes you may not want it in a byte array.

A single SOAP method on the device will be used by both this method and setFirmware(DeviceContext, byte[], boolean).

Parameters:
device - the device to load the firmware onto
inputStream - an inputStream to an opaque blob firmware binary image as retrieved from the DataPower web site or from distributable media. It is expected that this inputStream references content that is already base64-encoded. This is a special case not present on the other AMP commands. The reason for this is that firmware is such a large object 15-30MB that doing a base64 encode to prepare it for transmission each time it is transmitted to a device is a memory-intensive operation that we need to avoid. If it was unencoded, XMLBeans would create multiple copies of this large blob, which may blow up the heap size and cause out-of-memory errors. So to tune for this situation, the firmware blob is stored in the repository already encoded in base64 format, and thus does not need to be encoded for transmission to devices.
acceptLicense - a boolean value if accept license, must be ture to continue the firmware setting.
See Also:
setFirmware(DeviceContext, byte[])

deleteFile

void deleteFile(DeviceContext device,
                java.lang.String domainName,
                java.lang.String fileNameOnDevice)
                throws InvalidCredentialsException,
                       DeviceExecutionException,
                       AMPIOException,
                       AMPException
Delete a file to the persistent store on the device.

Parameters:
device - the DataPower device which has the specified domain
domainName - the domain in which to delete the file
filenameOnDevice - the name of the file in the format used by the device, i.e., temporary:///package.zip
See Also:
getKeyFilenames(DeviceContext, String), setFile(DeviceContext, String, String, byte[])


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