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