Understanding AMXAdminTask

AMXAdminTask specifies an action, data and property files, the objects on which the action is performed, and various behavioral attributes. 

<AMXAdminTask 
 action="action" 
 dataFile="path to data file"
 propsFile="path to properties file"
 [createIfNotExists = "{true|false}"]
 [failOnError="{true|false}"]
 [force="{true|false}"] 
 [merge="{true|false}"]
 [objectSelector="XPath expression"]
 [options="nostart|immediate|terminate|resolve|auto-resolve|stable|handle-dependencies"]
 [overwrite="{true|false}"]
 [timeout="timeout value"/>

Parameters

Attribute Type Req? Description
action String Yes The action to be performed on the objects in the data file. The action is case insensitive.
  • Unless objectSelector is specified, the action is applied to every object in the data file.
  • The order in which the action is applied to the objects is either breadth first or depth first. The method used is determined by the action.
    • Breadth first - add, edit, install, start, stop
    • Depth first - delete, uninstall
  • Some actions are not performed against certain object formats.
    • For the most part, add and edit are applied only to objects specified in full format. Objects not in this format are skipped.
createIfNotExists Boolean No Applicable to the edit action.

If an object is to be edited but doesn’t yet exist and this flag is true, then the object is added.

If this flag is false and the object to be edited doesn't exist, an error is reported.

Default: true.

dataFile String Yes The path to the XML file containing the object data.
failOnError Boolean No Causes the Ant task to fail when an unrecoverable error is reported. The option stops processing of targets in the depends list or specified on the command line.
force Boolean No Forces an action even if the object has dependent objects or is not in the appropriate state. Applies to the following actions and objects:
  • delete - Node, Application, Environment, ResourceTemplate, ResourceInstance
  • undeploy - Application
  • stop - Application, Component, Binding
  • uninstall - Node, ResourceInstance
For example:
  • A node must be in the uninstalled state before it can be deleted and it must be stopped before it can be uninstalled. If any problems occur moving the node to one of these states, and force is true, the node is deleted even if it is not in the uninstalled state or uninstalled even if it is not stopped.
  • An application must be in the undeployed state before it can be deleted and it must be stopped before it can be undeployed. If any problems occur moving the application to one of these states, and force is true, the application is deleted even if it is not in the undeployed state.
Caution: You should exercise extreme caution when using this option as it may leave your system in a non-working state.

Default: false.

merge Boolean No Applicable to the add action, and only if the overwrite flag was used and is true.
If an object to be added already exists and
  • If merge is true and overwrite is true, then the existing object is overwritten by merging with the new object. That is, the old object's data is updated with the new object's data.
  • If merge is false but overwrite is true, then the existing object is deleted and replaced by the new object. The old object's children and access control lists, if any, are lost in the process.

Default: true.

objectSelector String No Specifies the set of objects to be processed by an XPath expression. For information on the XPath language, see http://www.w3.org/TR/xpath. If this attribute is not specified:
  • All of the objects in the data file are processed.
  • The heuristic used to determine the order in which the objects are processed depends on the action option.
options String No The following actions have additional options:
  • deploy - nostart prevents applications from being started after deployment.
  • stop - immediate allows applications, components, bindings, and nodes to perform a quick cleanup and then stop. terminate applies only to nodes and causes the node process to be killed without any cleanup.
  • install, add, remove, deploy, undeploy - resolve causes nodes to be restarted when a node is installed, a feature is added or removed from a node, or an application is deployed or undeployed from a node.

    auto-resolve applies to the resource instance. It causes the node to be re-started only if needed.

    stable is an option available when installing resource instances. Prevents the nodes from restarting. In this mode what you deploy should not affect any other running code in the runtime.

    handle-dependenciesre-installs all dependant resource instances and restart applications that use these resource instances.

overwrite Boolean No. Applicable to the add action. If an object to be added already exists and the overwrite is true, then the existing object is overwritten.

There are two ways in which an object can be overwritten: it can be merged, or created from scratch. The strategy used is determined by the merge option.

Default: true.

propsFile String Yes The path to the properties file containing the Administrator server location and user-specific information data.
skipIfNotExists Boolean No Used when deleting an object.

When set to true, no attempt is made to delete the object if it does not exist.

When set to false, an error is reported if the object to be deleted does not exist.

Default: false.

timeout Integer No Length of time in seconds that a target will wait for an action to complete before reporting an error. If a timeout occurs and failOnError is true, the Ant task will fail. If a timeout occurs and failOnError is false, the script will report an error but the script will continue to process targets.
This option applies only to the following asynchronous actions and objects:
  • deploy, undeploy - Application, Plug-in
  • install and uninstall - Node, ResourceInstance
  • start - Node

Default: 0, which means the task will never time out. You should not change the default unless you are creating large amounts of data and leaving the script run unattended or have a requirement that node startup satisfies a timing constraint.

create

Assume you have an environment env1 in the database. Your data file has environment env1 and a node node1. If you specify the edit action and

  • createIfNotExists = false. env1 already exists, so its data is edited to match env1 in the data file. node1 doesn’t exist, so is not updated.
  • createIfNotExists = true. env1 already exists, so its data is edited to match env1 in the data file. node1doesn’t exist, so it is added to env1.

force

Assume you have an environment env1 and node node1 in both the database and the data file. node1 is in the Started state. If you do a delete and

  • force = false. node1 is in the Started state. There are two possible outcomes:
    • The stop and uninstall are successful. node1 and env1 are deleted.
    • The stop or uninstall fails. node1 is not in the uninstalled state so it cannot be deleted. The delete does not complete.
  • force = true. node1 is in the Started state. There are two possible outcomes:
    • The stop and uninstall are successful. node1 is deleted. env1 is deleted.
    • The stop or uninstall fails. node1 is not in the uninstalled state but is forcefully deleted. env1 is deleted.

objectSelector

  • objectSelector="//*"

    Process all objects.

  • objectSelector="//Node"

    Process all nodes.

  • objectSelector=”/Environment[@name=’env1’]/Node[@name=’node1’]"

    Process node1 in environment env1.

overwrite and merge

Assume you have environment env1 and node2 in the database. If you specify the add action with a data file that contains env1 and node1:

  • overwrite = false (merge is then ignored). Nothing happens to env1. node1 is added.
  • overwrite = true and merge = false. env1 is deleted and replaced with the env1 in the data file and node2 is deleted. node1 doesn’t exist yet and is added.
  • overwrite = true and merge = true. The existing env1 is updated with data from the env1 in the data file. Nothing happens to node2 and node1 is added.