try Step

The <try> step is used to specify typical error handling and cleanup logic for a block of steps. It has no attributes, and children consist of a <block>, <catch>, and <finally> element.

The <try> step is executed as follows:

• The steps in the <block> element are executed in order until all have completed or a step fails (as per the plan executor"s definition of failure for each step).

• 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, then 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 the two previous elements failed due to plan abort or plan timeout.

• A corollary of the above rules is that if any contained step fails due to plan abort or plan (not step) timeout, then no other contained steps are executed, and execution of the <try> step ends with a failure.

The <catch> element is used to suppress and recover from errors 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 just a <finally> element (but no <catch>), then it fails if the execution of either the <block> or the <finally> element fails.

• If the <try> step contains just a <catch> element (but no <finally>), then it fails if and 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, then it fails if and only if

  • the <catch> or the <finally> element executes and fails,

  • the <finally> element executes and fails, or

  • the <block> element fails due to plan abort or plan timeout

The critical point of the above is that failures in the <block> element are suppressed by the presence of a <catch> element.

try Step Child Elements

try Step Examples

Suppose you have a component whose installation consists of resource deployment followed by a restart. In this case, the component is really considered 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> 

Try blocks can also be used to model intelligent auto-upgrades. Suppose you are working with version 1.1 of a component, and you have two different install routines depending on whether version 1.0 was previously installed or not (fresh install versus upgrade install). On can model this in a single install block, as follows:

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

The <finally> block is most often used to cleanup temporary resources. The following example creates a temp 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> 

block Element

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

catch Element

The <catch> element is a child element of the <try> step that specifies the steps to execute in the event that a typical error occurs while executing the steps of the <block> element. It may contain any number of steps that are permitted within the scope of the block containing the <try> step.

The <catch> element serves both to suppress typical errors of the <block> element, and to define typical error recovery actions. Note that it may be empty, in which case it serves only to suppress typical errors.

finally Element

A child element of the <try> step that specifies the steps to execute regardless of whether a typical error occurred earlier within the <try> or <catch> steps; typical errors comprise plan abort or plan timeout, in which case the steps of the <finally> element are skipped altogether. It may contain any number of steps that are permitted within the scope of the block containing the <try> step.

The <finally> element is used primarily to specify steps to clean up and release resources, when the cleanup should be triggered regardless of other typical error conditions.