retarget Step

A step that changes the execution target for a set of steps. Retarget steps may be nested.

retarget Step attributes

retarget Step Child Elements

retarget Step host Attribute

The "host" attribute is used in the <retarget> step, as well as in various component targeter elements. Its value is the name of a host, which may include substitution variable references. It may also include symbolic names "/" to reference the root physical host of the current execution target, or "..(/..)*" to reference a parent host of the current execution target. The complete syntax supported is specified in the "host redirects" section of Chapter 16.

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

retarget Step Execution Semantics

When a <retarget> step is encountered, we first evaluate the "host" attribute 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, then the following steps are taken:

1. We resolve the host name to an actual host. If no such host exists, an error is raised.

2. We verify that the current user has "plan run" permission on the the given host. If not, an error is raised.

3. We verify that the root physical host of the host contains an RA, can be connected to, and is updated and prepared. If not, an error is raised.

4. We obtain 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 will block until the host is unlocked. If the request for a lock would result it a deadlock, then an error is raised.

5. The host becomes the new "current" host. The "physical" host is reset based on the new "current" host. The "initial" host does not change.

Once the above has completed, variables of the <varList> element are evaluated in the context of the new current host. Local variables may 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, then it is unlocked as appropriate and the current host is reset to the current host of the caller. Note that if the host was locked previously in the current execution thread, then it remains locked until the block that first acquired the lock completes.

An empty <retarget> block is still useful as a mechanism to prevalidate that the current user has appropriate permissions, and that the host is properly prepared.

retarget Step Example

The following is an example of a "restart" control service one might expect to find on a WebLogic managed server. It is implemented by calling a control on the admin server to "stop" the managed server, and then making a call on the local machine to start the server.

The "adminHostName" variable is evaluated on the current host of the caller (which is assumed to be the vhost containing the managed server). The domainName variable is evaluated on the retargeted host (which is assumed to be the vhost containing the admin 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>