<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.

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:

1. Resolves the host name to an actual host. If no such host exists, an error is issued.

2. 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.

3. 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.

4. 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.

5. 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>