N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide

Chapter 2 Shared Schema Used by Components and Simple Plans

This chapter describes these shared entities that can be used by both simple plans and components:

Unless indicated, attributes described in this chapter cannot reference component-scoped substitution variables.

Shared Steps

This section lists steps that can be used in either a component or a simple plan.

`<call>` Step

Use the <call> step to execute a control block associated with a component installed on the target host.

The <call> step has the following child elements:

<argList> – An optional element that is a list of arguments to pass to the control block. If you specify this element, it can only appear one time.
Installed component targeter – An optional element that identifies the component containing the control block to execute. This element is optional if the <call> step appears in a component, but not if the step appears in a plan. If this element is omitted, <thisComponent> is used. If you specify this element, it can only appear one time. See Installed Component Targeters.

Attributes for the `<call>` Step

The <call> element has one required attribute of type entityName, blockName, which is the name of the control block to execute on the installed component.

`<argList>` Element

The <argList> element is a child of the <call>, <install>, <uninstall>, <execSubplan>, and <addSnapshot> steps. This element specifies a list of variables to be passed as arguments to the called service.

The called service declares the variables that it expects by using a <paramList> element. The variables within the <argList> and the called <paramList> need not be the same. However, for each variable in the called <paramList> that does not have a default value, a variable with the same name must be present in the <argList>, or a preflight error is raised at plan runtime. For each variable in the called <paramList> for which there is a corresponding variable in the <argList>, the value of the variable in <paramList> will obtain the value of the corresponding variable in <argList> for the duration of the execution of the called service.

Variables in <argList> that do not correspond to a variable in the called <paramList> are silently ignored. Thus, services can be redefined with additional parameters, while still ensuring backward compatibility. So, one plan could call both old and new versions of the service.

The arguments of the <argList> element are expressed as attributes. The order in which the attributes appear is not significant. The following <argList> declares two arguments, password and path:

<argList password=":[password]" path="/tmp"/>

Attributes for the `<argList>` Element

The <argList> element must have at least one attribute. Each attribute is treated as a named variable to be passed to the called service. The name of each attribute must be an identifier without substitution variable references. The attribute name should correspond to the name of a parameter in the called service. The value of each attribute is an arbitrary string that can include references to variables in the enclosing scope, but not other arguments within the <argList>.

`<checkDependency>` Step

Use the <checkDependency> step to verify that a particular component has been installed on the target host. If an appropriate component has not been installed, the step fails and execution stops.

The dependency is checked by using the contained component targeter. If the targeter successfully resolves a component, the dependency is satisfied. Otherwise, the dependency is failed.

The <checkDependency> step has one required child element, an installed component targeter, which identifies the component to check for dependency. See Installed Component Targeters.

`<execJava>` Step

This step executes a Java^TM Executor instance on the target host. If the executor instance raises an exception, the step fails and execution stops.

The <execJava> step has one optional child element, <argList>, which is a list of arguments to pass to the Executor instance. If you specify this element, it can only appear one time.

Attributes for the `<execJava>` Step

The <execJava> element has the following attributes:

className – A required attribute that is the full name of a public class with a public no-arg constructor that implements the ExecutorFactory interface (as specified by the Plan Executor). This attribute can reference simple substitution variables.
classPath – An optional attribute that is the class path that contains the class named by the className attribute. If this attribute is omitted, the system class path of the remote agent is used. The class path format is a semicolon-separated list of absolute paths to Java Archive (JAR) files on the agent. This attribute can reference simple substitution variables.
timeout – An optional attribute of type positiveInteger, which specifies the number of seconds to wait for the command to complete before timing out. If this attribute is omitted, the plan's <execNative> timeout period applies. The value should be greater than 0.

When an <execJava> step is contained within a component, the step typically calls classes that are contained within one or more resources that are deployed by that component. When the step is contained within a plan, the classes called are already resident on the agent, either as a system class of the agent itself or as a resource that was deployed with an existing component.

`<execNative>` Step

The <execNative> step executes a command native to the operating system on the target host. If the command produces an unexpected result, the step fails and execution stops.

The <execNative< step has the following child elements:

<env> – An optional element that specifies environment variables for the child process. For each environment variable, specify one <env> element.
<background> – An optional element that specifies that the command is to run as a background process. If you specify this element, it can only appear one time. If you specify the <background> element, you must also specify the <outputFile> and <errorFile> elements.
<outputFile> – An optional element that is the name of the file in which to store standard output from the command. If you specify this element, it can only appear one time. This element is required if the <background> element is specified.
<errorFile> – An optional element that is the name of the file in which to store standard error output from the command. If you specify this element, it can only appear one time. This element is required if the <background> element is specified.
<inputText> – An optional element that is text to be used as standard input to the command. If you specify this element, it can only appear one time. This element is mutually exclusive with the <inputFile> element.
<inputFile> – An optional element that is the name of the file to be used as standard input to the command. If you specify this element, it can only appear one time. This element is mutually exclusive with the <inputText> element.
<exec> – A required element that specifies the name of the executable to run. This element is mutually exclusive with the <shell> element.
<shell> – A required element that specifies a shell command to run. This element can only appear one time. This element is mutually exclusive with the <exec> element.
<successCriteria> – An optional element that is the criteria used to determine whether this step succeeded or failed. If you specify this element, it can only appear one time.

Attributes for the `<execNative>` Step

The <execNative> step has the following attributes:

userToRunAs – An optional attribute that is the name of the user to run this command. If this attribute is omitted, the command is run as the value of defaultUserToRunAs in the configuration file. The value can be either a string user name or a numeric user ID. The value should be a nonempty string. This attribute can reference simple substitution variables.
dir – An optional attribute that is the absolute path to the working directory for the command. If this attribute is omitted, the value defaults to the agent-specific configurable directory. This value should be a nonempty string. This attribute can reference simple substitution variables.
timeout – An optional attribute of type positiveInteger, which specifies the number of seconds to wait for the command to complete before timing out. If this attribute is omitted, the plan's <execNative> timeout period applies. The value should be greater than 0.

`<env>` Element

The <execNative> element can optionally have <env> elements to specify environment variables for the command. You can use <env> to supply new variables for the command's environment or to override existing variables.

The set of the command's environment variables is a union of the set of the remote agent's environment variables and the variables supplied by using the <env> elements.

Attributes for the `<env>` Element

The <env> element has the following attributes. They can reference simple substitution variables.

name – A required attribute that is the name of the environment variable. The value should be a nonempty string.
value – A required attribute that is the value of an environment variable. The value can contain ${var-name} strings to refer to the values of the remote agent's environment variables. If var-name refers to a variable that is overridden by an <env> element, the substituted value is the one that is defined in the remote agent's environment, not the overridden one. If the string ${ must appear in the value, escape this string by using ${{. All instances of ${{ are replaced by ${.

`<background>` Element

The <background> element is a child of the <execNative> element. When present, this element specifies that the command should be executed as a background process. This element has no attributes or child elements.

An <execNative> with a <background> element has the following constraints:

<successCriteria> need not be specified. The step succeeds if no issues arise when starting the background process. If specified, the <successCriteria> is tested against the script that is used to run the command as a background process.
No standard output or standard error output is captured for the executed command.

By viewing the details in the browser interface, you see an exit status of 0 and the empty standard output and standard error output. However, if problems occurred when starting the native command in the background, a different exit status is shown. The value depends on the nature of the error and diagnostic output.
The <outputFile> and <errorFile> elements must be specified. If the specified files already exist, they are overwritten.

`<outputFile>` Element

The <outputFile> element is a child of the <execNative> element. The <outputFile> element specifies the path to a local file on the agent in which to store the standard output of the command that is being executed. Specify the path to the local file by using the <outputFile> name attribute. Relative paths are interpreted as being relative to the command's working directory.

You must specify the <outputFile> element if you specify the <background> element.

If <outputFile> is not specified and the <successCriteria> element does not specify outputMatches, the command output is not stored and will be lost. If outputMatches is specified, the standard output is stored in a temporary file that is deleted after the command finishes executing.

Attributes for the `<outputFile>` Element

The <outputFile> element has one required attribute, name, which is the name of the file to which the standard output of the command is written. This value should be a nonempty string. This attribute can reference simple substitution variables.

`<errorFile>` Element

The <errorFile> element specifies the path to a local file on the agent in which to store the error output of the command that is being executed. The path to the local file is specified by using the <errorFile> name attribute. Relative paths are interpreted as being relative to the command's working directory.

You must specify the <errorFile> element if you specify the <background> element.

If <errorFile> is not specified and the <successCriteria> element does not specify errorMatches, the command output is not stored and will be lost. If errorMatches is specified, the error output is stored in a temporary file that is deleted after the command finishes executing.

Attributes for the `<errorFile>` Element

The <errorFile> element has one required attribute, name, which is the name of the file to which the standard error output of the command is written. This value should be a nonempty string. This attribute can reference simple substitution variables.

`<inputText>` Element

The <inputText> element is a child element of the <execNative> element. This child element specifies the arbitrary text that should be used as standard input to the command. The text is specified as the contents of this element.

<execNative>
    <inputText>
        ls -l | fgrep `*test*' | sort -u > file.out
    </inputText>
    <command exec=”sh”/>
</execNative>

The body of the <inputText> element can be enclosed in a CDATA section to preserve the formatting of the input and to avoid parsing errors that might be caused by input that contains the & and < characters.

If the <inputText> is specified, it is always enclosed within a CDATA section when generating XML for the <execNative> step. All of the characters within <inputText> are passed as standard input to the command that is being executed. If <inputText> contains only white spaces, those white spaces are passed, exactly as specified, to the command that is being executed.

The contents of <inputText> are config-generated.

The <inputText> element has no attributes.

`<inputFile>` Element

The <inputFile> element is a child element of <execNative>. This child element specifies the path to a local file on the remote agent whose contents are used as standard input to the command being executed. The path to the local file is specified by using the <inputFile> name attribute.

Note –

The <inputFile> element cannot be used with the <inputText> element in an <execNative> command.

Attributes for the `<inputFile>` Element

The <inputFile> element as one required attribute, name, which is the file to act as standard input to the command. This value should be a nonempty string. If a relative path is specified, it is relative to the command's working directory. This attribute can reference simple substitution variables.

`<exec>` Element

An <execNative> step can contain only one <exec> element. The <exec> element specifies the details of the native command to be executed.

The <exec> element contains the following attributes:

A cmd attribute that specifies the name of the command to execute
A set of nested <arg> elements for each of the arguments of the cmd command

<execNative> executes the command specified by cmd with the arguments in the order in which they are specified.

For example, the following <execNative> step executes the ps -fu sps command:

<execNative>
    <exec cmd=”ps”>
        <arg value=”-fu”/>
        <arg value=”sps”/>
    </exec>
</execNative>

The <exec> element has an optional child element, <arg>. Specify one <arg> element for each argument to the command that you want to execute.

The <arg> element has one required attribute, value, which is the argument value. This argument is supplied as the nth argument to the command, where <arg> is the nth child of the command element. This attribute can reference simple substitution variables.

Attributes for the `<exec>` Element

The <exec> element has one required attribute, cmd, which is the path of the command to execute. If the specified path is not absolute, the command is found by using the platform-specified PATH environment variable set for the remote agent. This value should be a nonempty string. This attribute can reference simple substitution variables.

`<shell>` Element

The <shell> element is a child element of <execNative>. The contents of the <shell> element specifies the command to be executed. The command to be executed is interpreted using an interpreter, which is specified by the cmd attribute. The command is executed by using sh -c “command” syntax for the platform. In this form, the cmd attribute must be specified to indicate the shell command to use to execute the command.

For example:

<execNative>
    <shell cmd=”/usr/bin/bash -c”>
        ls -l | fgrep `*test*' | sort -u > file.out
    </shell>
</execNative>

The previous <execNative> example executes the following command:

/usr/bin/bash -c `ls -l | fgrep `*test*' | sort -u > file.out'

To preserve formatting and to avoid XML parsing problems, the text contents of the command is always enclosed within a CDATA element when the XML representation is generated from the <execNative> step.

A command string cannot be empty or contain only white space characters. The command string is supplied exactly as it is specified, including surrounding white space, to the shell.

The contents of the <shell> element are config-generated.

Attributes for the `<shell>` Element

The <shell> element has one required attribute, cmd, which is the shell command in the sh -c syntax. The string should not contain any embedded quote characters. The string is parsed to retrieve the shell name and the arguments by using white space as delimiters. For example, /usr/bin/bash -c should be a nonempty string. This attribute can reference simple substitution variables.

`<successCriteria>` Element

The <successCriteria> element is a child element of <execNative>. This child element specifies the criteria to be used to evaluate whether an <execNative> step executed successfully. If this element is not specified, the default value is <successCriteria status=”0”/>.

If the specified <successCriteria> is empty, it is ignored.

If you specify <successCriteria/>, the step always succeeds no matter what output or exit code the command generated.

Attributes for the `<successCriteria>` Element

The <successCriteria> element has the following optional attributes. If more than one of the status, outputMatches, and errorMatches attributes are specified, they are ANDed together.

status – An optional attribute of type integer, which is the desired exit status of the command. This value should be a positive integer.
outputMatches – An optional attribute that is a regular expression to match the standard output that is generated by the command. This value should be a nonempty string. This attribute can reference simple substitution variables.
errorMatches – An optional attribute that is a regular expression to match the standard error output that is generated by the command. This value should be a nonempty string. This attribute can reference simple substitution variables.
inverse – An optional attribute of type Boolean, which, if set to true, negates each of the conditionals specified in <successCriteria>. The default value is false. The step succeeds only if the conditions that are specified through each attribute of <successCriteria> are not met.

For example, an <execNative> step with the following <successCriteria> succeeds if status is not 1, the standard output does not match bin, and standard error does not match none.
<successCriteria status=”1” outputMatches=”bin” errorMatches=”none” inverse=”true”/>
A <successCriteria> element that contains only the inverse attribute is saved without the inverse attribute. So, if you specify the following statement, the element is stored as <successCriteria/>, and the <successCriteria> element is ignored.
<successCriteria inverse=”true”/>

`<if>` Step

This step is used to conditionally execute a block of steps. This step has no attributes. Its child elements are <condition>, <then>, and <else>. The <condition> and <then> elements must appear one time. If you specify the <else> element, it can only appear one time.

If the contents of the <condition> element evaluates to true, the steps of the <then> block are executed. Otherwise, the steps of the <else> block are executed, if present.

Example 2–1 Using the `<if>` Step

The following example shows an <if> step that is used to conditionally restart.

<if>
    <condition><istrue value=":[restart]"/></condition>
    <then>
        <call blockName="restart"/>
    </then>
</if>

`<condition>` Element

The <condition> element is a child of the <if> step and specifies a Boolean expression. This element has no attributes and must contain exactly one Boolean operator child element. See Boolean Operators.

`<then>` Element

The <then> element is a child element of the <if> step. This element specifies the steps to execute if the associated condition is true. The <then> element can contain any number of steps that are permitted within the scope of the block that contains the <if> step.

`<else>` Element

The <else> element is a child element of the <if> step. This element specifies the steps to execute if the associated condition is not true. The <else> element can contain any number of steps that are permitted within the scope of the block that contains the <if> step.

`<pause>` Step

The <pause> step pauses the execution of a plan for a specified amount of time. You can use <pause> to make a plan wait for required services to come online after being started.

Attributes for the `<pause>` Step

The <pause> element has one required attribute of type positiveInteger, delaySecs, which is the number of seconds to wait.

`<processTest>` Step

The <processTest> step is used to verify that a particular process is running on the target host. If the specified process does not exist, the step fails and execution stops.

Note –

This step only applies to UNIX® systems.

Attributes for the `<processTest>` Step

The <processTest> step has the following attributes:

delaySecs – A required attribute of type positiveInteger, which is the number of seconds to wait before testing whether the process exists.
timeoutSecs – A required attribute of type positiveInteger, which is the number of seconds to wait for the process to come online before failing. Time starts after the delay has completed.
processNamePattern – A required attribute, which is a glob-style pattern to use to match the specified process name. This attribute can reference simple substitution variables.
user – An optional attribute that is a glob-style pattern to use to match the name of the process owner. If this attribute is omitted, the process owner is not considered as part of the test. This attribute can reference simple substitution variables.

`<raise>` Step

The <raise> step is a step that always fails, though it can be caught and handled by a <try> step. This step has a single attribute, message, and has no child elements.

The <raise> step is used to indicate a failure condition without having to construct an artificial step to do so. This step most often appears within a <catch> block to propagate an error condition after cleaning up.

Attributes for the `<raise>` Step

The <raise> element has one optional attribute, message, which is a message that describes the error condition. By default, the message is a generic system-specified message. This attribute can reference simple substitution variables.

Example 2–2 Using the `<raise>` Step

The following example shows how the <raise> step is used to repropagate an error condition from within a <catch> block, after noting the error in a log.

<control blockName="default">
    <try>
        <block>
            <!-- some arbitrary processing here -->
        </block>
        <catch>
            <!-- note error in log -->
            <execNative>
                <exec cmd="appendLog">
                    <arg value="an error occurred"/>
                </exec>
            </execNative>
            <!-- rethrow error -->
            <raise/>
        </catch>
    </try>
</control>

MS Windows: `<reboot>` Step

This step causes the agent to reboot before running the rest of the plan. You can only use this step on Microsoft Windows (MS Windows) based systems. If encountered on a system other than MS Windows, an error is issued. If you reboot an agent that resides on the same host as the master server, an error is issued. These errors are preflight errors.

MS Windows: Attributes for the `<reboot>` Step

The <reboot> step has one optional attribute of type positiveInteger, timeout, which is the maximum number of seconds to wait for the server to reboot. If this attribute is omitted, the plan's <execNative> timeout period applies.

`<retarget>` Step

This step changes the execution target for a set of steps. Retarget steps can be nested.

The <retarget> step has the following child elements:

<varList> – An optional element that lists the local variables available to the contained steps. The variables are evaluated within the scope of the new host. If you specify this element, it can only appear one time.
Steps – An optional element that contains the steps to execute on the new host. The steps can be any that are permitted within the scope of the block that contains the <retarget> step. You can specify more than one step. For an example, see Example 2–3.

Attributes for the `<retarget>` Step

The <retarget> step has a required attribute, host, which is the host on which the contained steps should be executed. This attribute can reference simple substitution variables.

This attribute is used by the <retarget> step, as well as by various component targeter elements. Its value is the name of a host, which can include substitution variable references. The value can also include the symbolic name / to reference the root physical host of the current execution target, or ..(/..)* to reference a parent host of the current execution target.

Note –

When a host attribute is specified within a component targeter, it is semantically equivalent to enclosing the containing step in a <retarget> step.

`<retarget>` Step Execution Semantics

When a <retarget> step is encountered, the host attribute is first evaluated in the context of the current host of the caller.

If the value of the host attribute is different from the name of the current host, the provisioning software takes the following steps:

Resolves the host name to an actual host. If no such host exists, an error is issued.
Verifies that the current user has “execute” permission on the given host for the plan's folder or for the component that contains this step. If not, an error is issued.
Verifies that the following conditions are met for the root physical host of the host:
- It contains a remote agent.
- You can connect to it.
- It is updated and prepared.
If these conditions are not met, an error is issued.
Obtains a lock on the host, while retaining locks on all previously visited hosts. If the current execution thread already locks the host, this operation is effectively a no-op. If the host is already locked by another execution thread, this operation blocks until the host is unlocked. If the request for a lock would result in a deadlock, an error is issued.
Resets the host to become the new “current” host. The “physical” host is reset based on the new “current” host. The “initial” host does not change.

After the previous steps complete, variables of the <varList> element are evaluated in the context of the new current host. Local variables can hide variables of enclosing scopes. Then, each of the steps is executed in the context of the new current host.

Finally, if the retarget operation changed the current host, it is unlocked, as appropriate, and the current host is reset to the current host of the caller. If the host was locked previously in the current execution thread, it remains locked until the block that first acquired the lock completes.

You can use an empty <retarget> block to prevalidate that the current user has the appropriate permissions and that the host is properly prepared.

Example 2–3 Using the `<retarget>` Step

This example shows a “restart” control service that you might find on a WebLogic managed server. This control service is implemented by calling a control on the administrative server to stop the managed server. Then it makes a call on the local server to start the server.

The adminHostName variable is evaluated on the current host of the caller, which is assumed to be the virtual host that contains the managed server. The domainName variable is evaluated on the retargeted host, which is assumed to be the virtual host that contains the administrative server. The ADMIN_SERVER component is also resolved on the retargeted host.

<control name="restart">
    <varList>
        <var name="adminHostName" default=":[target:adminHostName]"/>
    </varList>
    <retarget host=":[adminHostName]">
        <varList>
            <var name="domainName" default=":[target:domainName]"/>
        </varList>
        <call blockName="stopServer">
            <argList serverName=":[serverName]"
	      domainName=":[domainName]"/>
            <installedComponent name="ADMIN_SERVER"/>
        </call>
    </retarget>
    <call blockName="start"/>
</control>

`<sendCustomEvent>` Step

The <sendCustomEvent> step is used to generate a custom event with a particular message. This step can be used in conjunction with the notification rules module to send an email any time this step is encountered on a particular host.

Attributes for the `<sendCustomEvent>` Step

The <sendCustomEvent> step has one required attribute, message, which is the message to include as the event text. This attribute can reference simple substitution variables.

`<transform>` Step

The <transform> step is used to perform a text-based transformation on a file on the target host. Currently, Perl-type and XSLT-based transformations are supported.

The <transform> child elements specify the transformation to be applied to the input file. The child elements can be any one of the following elements:

A single <stylesheet> element that defines the XSLT transformation to apply to the input source
One or more <subst> elements that define Perl-like substitution patterns to apply sequentially to the input source
A single <source> element that names the external file that contains the transformation
Empty, which means that the contents of the input file is copied directly to the output file

This situation is useful for extracting from or writing to zip archives.

Attributes for the `<transform>` Step

The <transform> step has the following attributes:

input – An optional attribute that is the generalized path of the file on the target host on which to apply the transformation. If this attribute is omitted, input is read from the output file. This attribute can reference simple substitution variables.
output – A required attribute that is the generalized path of the file on the target host to which to write the result of the transformation. This attribute can reference simple substitution variables.

The input and output attributes can reference the same or distinct files. The value of these attributes is a generalized path that can include zip archives or zip derivatives, such as JAR, as directory elements. For example, a path might be webapp/myapp.jar/config.xml.

`<stylesheet>` Element

The <stylesheet> element is a child of the <transform> step and specifies an XSLT transformation to apply to the input source. At most one <stylesheet> element can appear as a child of a particular <transform> element. You cannot use the <stylesheet> element in conjunction with other child elements.

The <stylesheet> element is an XSLT Version 1.0 element as defined by the http://www.w3.org/1999/XSL/Transform name space. For more information, see Version 1.0 of the XSL Transformations (XSLT) specification at http://www.w3.org/TR/xslt.html. Only the XSLT <stylesheet> element is accepted as a child of the <transform> element. In particular, neither the XSLT synonym <transform> nor the simplified XSLT transform syntax described in Section 2.3 of the XSLT specification is supported as a child of the <transform> element.

The <stylesheet> element body can include substitution variable references if the body is still a valid XSLT without first undergoing variable substitution.

When a <stylesheet> element is used as a transformation, the input file must be written in XML. For more information, see Version 1.0 of the XSL Transformations (XSLT) specification.

Example 2–4 Using the `<stylesheet>` Element

<transform output="/etc/hosts">
    <xsl:stylesheet version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:template match="/">
            <xsl:for-each select="a">
                <xsl:value-of select="b"/>
            </xsl:for-each>
        </xsl:template>
    </xsl:stylesheet>
</transform>

`<subst>` Element

The <subst> element is a child of the <transform> step. This element specifies a Perl-like substitution pattern to apply as a transformation. One or more <subst> elements can appear as children of the <transform> element, but they cannot be used in conjunction with other child elements. When more than one <subst> element appears, they are applied sequentially.

All occurrences of the pattern in the input file are replaced, including multiple occurrences within a line.

For information about the supported syntax, see Java documentation (class java.util.regex.Pattern).

Attributes for the `<subst>` Element

The <subst> element has the following attributes:

match – A required attribute that is a case-sensitive Perl-like regular expression that is sought after in the input. This attribute can reference simple substitution variables.
replace – A required attribute that is a Perl-like replacement value that is substituted for each occurrence of the pattern given by match. This value is not interpreted verbatim: the $n construct is interpreted as the nth parenthetical expression inside the matching expression. This attribute can reference simple substitution variables.

Example 2–5 Using the `<subst>` Element

The following transformation converts all occurrences of the string 127.0.0.xxx to 10.10.0.xxx in the /etc/hosts file:

<transform output=”/etc/hosts”>
    <subst match="127\.0\.0\.(\d+)"
    replace="10.10.0.$1"/>
</transform>

`<source>` Element

The <source> element is a child of the <transform> step. This element specifies an external file on the target host that contains the transformation to be applied to the input file. At most one <source> element can appear as a child of a particular <transform> element. You cannot use the <source> element in conjunction with other child elements.

Configuration generation is not performed on the specified source file as part of the <transform> step. However, the specified source file can be a config-type resource file that is deployed as part of a component installation. In such as case, substitution variables that are contained in the source file would have been substituted when the file was deployed.

Attributes for the `<source>` Element

The <source> element has the following attributes:

type – A required element that is the type of transformation that is contained in the specified file. The following values are permitted:
- PERL – A Perl-like transformation that is similar to that of the <subst> element. In this case, the specified file should have format similar to the following format:
  <?xml version='1.0'?> <transform> <subst match="127\.0\.0\.(\d+)" replace="10.10.0.$1"/> </transform>
  Perl-type external transformation files can contain any number of <subst> elements.
- XSLT – An XSLT transformation. In this case, the specified file contains a standard XSLT Version 1.0 transformation as defined by the name space http://www.w3.org/1999/XSL/Transform. Unlike inline transformations, which only permit the XSLT <stylesheet> element, XSLT transformations that are contained in external source files can include any valid top-level XSLT transformation element. Such elements are <stylesheet>, <transform>, and simplified XSLT syntax. The simplified XSLT syntax is described in Section 2.3 of the XSLT specification.
name – A required attribute that is the name of the file on the target host that contains the transformation. The contents of the file must correspond to the type defined by the type attribute. The name cannot include zip archives as directory elements. This attribute can reference simple substitution variables.

`<try>` Step

The <try> step is used to specify typical error handling and cleanup logic for a block of steps. This step has no attributes. This step has these child elements: <block>, <catch>, and <finally>.

The <try> step is executed as follows:

The steps in the <block> element are executed in order until all have completed or until a step fails. The failure for each step is determined by the Plan Executor.
If and only if a <catch> element is defined and the execution of the block element terminated with a step failure other than plan abort or plan timeout, the steps in the <catch> element are executed in order until all have completed or a step fails.
If a <finally> element is defined, its steps are executed in order until all have completed or a step fails. This happens regardless of the success of the previous two elements unless either of them failed due to plan abort or plan timeout.
If any contained step fails with a plan abort or plan (not step) timeout, no other contained steps are executed. Execution of the <try> step ends with a failure.

The <catch> element is used to suppress and recover from errors that are encountered in the <block> element. The <finally> element is used to unconditionally perform some cleanup, regardless of whether typical errors were encountered.

The <try> step either succeeds or fails as follows:

If the <try> step contains only a <finally> element, it fails if the execution of either the <block> or the <finally> element fails.
If the <try> step contains only a <catch> element, it fails only if the <catch> element executes and fails, or the <block> element fails due to plan abort or plan timeout.
If the <try> step contains both a <catch> and a <finally> element, it fails only if one of the following situations occurs:
- The <catch> or the <finally> element executes and fails.
- The <finally> element executes and fails.
- The <block> element fails due to plan abort or plan timeout.

Failures in the <block> element are suppressed by the presence of a <catch> element.

The <try> step has the following child elements:

<block> – A required element that consists of the steps initially executed.
<catch> – An optional element that contains the steps to execute in case of a typical error. You must specify this element if the <finally> element is not specified. If you specify this element, it can only appear one time.
<finally> – An optional element that contains the steps to execute regardless of typical errors. You must specify this element if the <catch> element is not specified. If you specify this element, it can only appear one time.

`<block>` Element

The <block> element is a child element of the <try> step. This element specifies the primary steps that are executed by the <try> step. The <block> element contains one or more steps that are permitted within the scope of the block that contains the <try> step.

`<catch>` Element

The <catch> element is a child element of the <try> step. This element specifies the steps to execute if a typical error occurs while executing the steps of the <block> element. The <catch> element can contain any number of steps that are permitted within the scope of the block that contains the <try> step.

The <catch> element serves both to suppress typical errors of the <block> element and to define typical error recovery actions. This element can be empty, in which case <catch> only suppresses typical errors.

`<finally>` Element

A child element of the <try> step. <finally> specifies the steps to execute regardless of whether a typical error occurred earlier within the <try> or <catch> steps. An atypical error can be a plan abort or a plan timeout, in which case the steps of the <finally> element are skipped. <finally> can contain any number of steps that are permitted within the scope of the block that contains the <try> step.

The <finally> element is used primarily to specify cleanup steps that should always be run regardless of an error. To run cleanup steps in response to an error, put them in the <catch> element instead.

Example 2–6 Using the `<try>` Step

In this example, the component installation consists of resource deployment followed by a restart. In this case, the component is considered to be installed after its resources are deployed, and a failure during restart should not affect its installed state. Typical errors can be suppressed during the restart as follows:

<installSteps blockName="default">
    <deployResource/>
    <try>
        <block>
            <call blockName="restart"><thisComponent/></call>
        </block>
        <catch/><!-- suppress all typical errors -->  
    </try>
</installSteps>

You can use <try> blocks to model intelligent auto-upgrades. Version 1.1 of a component has two different installation routines. One performs a fresh installation of the component. The other performs an upgrade installation if Version 1.0 of that component was previously installed. You can model this situation in a single installation block, as follows:

<installSteps blockName="default">
    <try>
        <block>
          <checkDependency>
              <installedComponent name="foo" version="1.0"/>
          </checkDependency>
          <!-- 1.0 installation exists, do upgrade -->
        </block>
        <catch>
          <!-- 1.0 installation doesn't exist, do fresh installation -->
        </catch>
    </try>
</installSteps>

The <finally> block is most often used to clean up temporary resources. The following example creates a temporary file, processes it, and then removes it.

<control blockName="default">
    <varList>
        <var name="file" default="/tmp/file.txt"/>
    </varList>
    <execNative outputFile=":[file]">
        <exec cmd="ls"><arg value="-l"/></exec>
    </execNative>
    <try>
        <block>
            <!-- process file in some way -->
        </block>
        <finally>
            <execNative>
                <exec cmd="rm"><arg value=":[file]"/></exec>
            </execNative>
        </finally>
    </try>
</control>

`<urlTest>` Step

This step is used to verify that the contents of a particular URL match an expected pattern. If the desired pattern is not matched, the step fails and execution stops.

Attributes for the `<urlTest>` Step

The <urlTest> step has the following attributes:

delaySecs – A required attribute of type positiveInteger, which is the number of seconds to wait before testing the URL contents.
timeoutSecs – A required attribute of type positiveInteger, which is the number of seconds to wait to receive the URL contents before failing. Time starts after the delay has completed.
URL – A required attribute that is the URL whose contents should be tested. Currently, only the HTTP protocol is supported. This attribute can reference simple substitution variables.
pattern – A required attribute that is a glob-style pattern that is expected to match the contents of the URL that is being tested. This value supports multibyte encoding. This attribute can reference simple substitution variables.

Installed Component Targeters

This section describes the elements that identify an installed component as the target of the containing step (for example, control service call). All targeters cannot be used with all targeted steps. Each targeter specifies the steps with which it can be used.

`<installedComponent>` Installed Component Targeter

The <installedComponent> element identifies a particular installed component that is assumed to be installed on the target host.

This element can be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps.

This targeter matches the specified component directly and cannot be used to match derived instances of that component. Use the <systemType> targeter to target components that are derived from a particular type.

Attributes for the `<installedComponent>` Targeter

This targeter has the following attributes:

name – A required attribute of type entityName, which is the name of the installed component.
path – An optional attribute of type pathReference, which is the path of the component. If this attribute is omitted, the path of the containing entity is assumed.
version – An optional attribute of type version, which is the version of the installed component. If this attribute is omitted, the most recently installed component, regardless of the version, is used.
versionOp – An optional attribute that specifies the operator to use when comparing the version attribute with versions of components that are installed on the target host. If more than one installed component applies, the most recently installed component is used. These values are permitted: =, >=, and >.

The >= operator is used by default. If version is not specified, versionOp is ignored.
onlyCompat – An optional attribute that specifies the components that should match.

If the value is true, only components that are call compatible with the component of version version should be matched. A component of version version must exist. By default, the value is false. If version is omitted, this element is ignored.
installPath – An optional attribute that is the install path of the installed component. If this attribute is omitted, the most recently installed component in any path is used. The value is converted to universal format prior to component resolution. This attribute can reference simple substitution variables.
host – An optional attribute that is the host on which the component is installed. By default, host is the current host. See the description of the host attribute in Attributes for the <retarget> Step. This attribute can reference simple substitution variables.

`<systemService>` Installed Component Targeter

The <systemService> element identifies a particular system service component that is assumed to be installed on the current physical host. If the system service is defined by a plug-in, the service name should be prefixed with the plug-in name, such as pluginName#serviceName.

This element can be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps.

Use of the <systemService> targeter implicitly retargets to the root physical host of the current host. If you need to target a system service on a different host, a <retarget> step must be used. You cannot otherwise specify a new host within the <systemService> targeter.

Attributes for the `<systemService>` Targeter

The <systemService> targeter has one required attribute of type systemName, name, which is the name of the system service component. If the system service is defined by a plug-in, the system service name should be prefixed with the plug-in name, such as pluginName#serviceName.

`<systemType>` Installed Component Targeter

The <systemType> element identifies a component that is an instance of a particular type that is assumed to be installed on the target host. If more than one installed component matches the specified criteria, the component that was most recently installed is used.

The <systemType> element can be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps.

Attributes for the `<systemType>` Targeter

The <systemType> targeter has the following attributes:

name – A required attribute of type systemName, which is the name of the system type component. If the system type is defined by a plug-in, the system type name should be prefixed with the plug-in name, such as pluginName#typeName.
installPath – An optional attribute that is the install path of the desired component. The value is converted to universal format prior to component resolution. This attribute can reference simple substitution variables.
host – An optional attribute that is the host on which the component is installed. By default, host is the current host. See the description of the host attribute in Attributes for the <retarget> Step. This attribute can reference simple substitution variables.

`<thisComponent>` Installed Component Targeter

The <thisComponent> element specifies that the component that contains the step should be used as target of the step. Only steps that are contained in a component can use this targeter. This element has no attributes.

The <thisComponent> element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps.

If the steps listed do not contain a component targeter element, <thisComponent> is assumed by default.

`<superComponent>` Installed Component Targeter

The <superComponent> element specifies that the base component of the component that contains the step should be used as target of the step. Only steps that are contained in a derived component can use this targeter.

The <superComponent> element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps. This element has no attributes.

This targeter always binds to the base component's definition of the step in question, even if the derived component overrides it.

`<nestedRef>` Installed Component Targeter

The <nestedRef> element identifies a nested component reference declared or inherited by the current composite component. Only steps that are in a composite component can use this targeter.

The <nestedRef> element can be used as a targeter for the <checkDependency>, <call>, <uninstall>, and <addSnapshot> steps.

The specified component reference is assumed to already be installed by the calling component. Otherwise, an error is issued. If the nested component reference was installed on a host other than the current target host, use of the <nestedRef> targeter implicitly retargets the associated step to that host.

Attributes for the `<nestedRef>` Targeter

The <nestedRef> targeter has one required attribute of type identifier, name, which is the name of a nested component reference in this component.

`<allNestedRefs>` Installed Component Targeter

The <allNestedRefs> element identifies the set of all nested component references that are declared or inherited by the current composite component. Only steps within composite components can use this targeter.

This element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps.

This targeter can identify any number of components. If it identifies no components, the step is a no-op. If it identifies more than one component, the step is semantically expanded as if a separate occurrence of the step that uses the <nestedRef> targeter exists for each of the identified components. The steps are executed serially rather than in parallel. The ordering of the steps varies based on the step type. If the execution of the step on one of the components causes an error, the step is not executed on the remaining matching components.

When used as a targeter for a <call> or <addSnapshot> step, this targeter matches all of the nested component references that are currently installed by this component. The component matches are in the order of installation.

When used as a targeter for an <uninstall> step, the targeter matches all of the nested component references that are currently installed by this component. The component matches are in the reverse order of installation.

`<toplevelRef>` Installed Component Targeter

The <toplevelRef> element identifies a top-level component reference that is declared or inherited by the current composite component. Only steps that are in composite components can use this targeter.

The <toplevelRef> element can be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps.

This targeter is semantically equivalent to the <installedComponent> targeter, except that the name, path, and version attributes are predefined based on the referenced component. See <installedComponent> Installed Component Targeter.

Attributes for the `<toplevelRef>` Targeter

The <toplevelRef> targeter has the following attributes:

name – A required attribute of type identifier, which is the name of a top-level component reference in this component.
versionOp – An optional attribute that specifies the operator to use when comparing the version of the referenced component with versions of components that are installed on the target host. If more than one installed component applies, the most recently installed component is used.

These values are permitted: =, >=, and >. If this attribute is omitted, >= is used.
onlyCompat – An optional attribute that specifies the components that are matched. If true, this attribute specifies that only components that are call compatible with the referenced component should be matched. The default value is false.
installPath – An optional attribute that is the install path of the referenced component. If this attribute is omitted, the most recent installation of the referenced component in any path is used. The value is converted to universal format prior to component resolution. This attribute can reference simple substitution variables.
host – An optional attribute that is the host on which the referenced component is installed. By default, host is the current host. See the description of the host attribute in Attributes for the <retarget> Step. This attribute can reference simple substitution variables.

`<dependee>` Installed Component Targeter

The <dependee> element identifies an installed component on which the calling component has a declared dependency that was created by <createDependency>. Only steps that are in components can use this targeter.

The <dependee> element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps.

Attributes for the `<dependee>` Targeter

The <dependee> targeter has one required attribute of type identifier, name, which is the name of a dependency that is created by this component.

`<allDependants>` Installed Component Targeter

The <allDependants> element identifies the set of installed components that have a declared dependency on the calling component, which was created by <createDependency>. Only steps in components can use this targeter.

The <allDependants> element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps.

This targeter functions similarly to the <addNestedRefs> targeter in that it causes the containing step to be mapped over all of the matching components. The order of the mapping over the dependent components is unspecified.

Attributes for the `<allDependants>` Targeter

The <allDependants> targeter has one required attribute of type identifier, name, which is the name of a dependency that is created on this component by other components.

`<targetableComponent>` Installed Component Targeter

The <targetableComponent> element identifies a targetable component that is associated with a particular component targeting host.

The <targetableComponent> element can be used as a targeter for the <call>, <uninstall>, <checkDependency>, <createDependency>, and <addSnapshot> steps.

Attributes for the `<targetableComponent>` Targeter

The <targetableComponent> targeter has one optional attribute, name, which is the name of a component targeting host. If this attribute is omitted, the value is the current target host. This attribute can reference simple substitution variables.

Universal Install Path Format

You can specify an install path within an installed component reference. In these cases, the installPath attribute value is converted to universal format before the installed component reference is resolved. This conversion occurs because the install path of the installed component is also stored in universal format.

In universal format, all occurrences of the path separator in the install path are replaced by a slash (/). The path separator is specific to the operating system that is running on the master server. Trailing slashes are dropped. The root install path (/) is not converted to the empty path.

When the Master Server application is running on UNIX based systems, trailing slashes are ignored. Thus, both /opt/apache/ and /opt/apache can be used to refer to the component that is installed in the /opt/apache directory.

Repository Component Targeters

This section describes elements that identify a particular component that resides in the master server repository as the target of the containing step, such as install. All targeters cannot be used with all targeted steps. Each targeter specifies the steps with which it can be used.

`<component>` Repository Component Targeter

The <component> element identifies a particular component that is assumed to exist in the component repository. Only steps that are contained in a simple plan can use this targeter.