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