TryCatchTask (Ant Contrib)
Date: 2016-06-25

net.sf.antcontrib.logic

## Class TryCatchTask

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - net.sf.antcontrib.logic.TryCatchTask

- All Implemented Interfaces:
    java.lang.Cloneable

      public class TryCatchTask
      extends org.apache.tools.ant.Task

  A wrapper that lets you run a set of tasks and optionally run a different set of tasks if the first set fails and yet another set after the first one has finished.

  This mirrors Java's try/catch/finally.

  The tasks inside of the required `<try>` element will be run. If one of them should throw a `BuildException` several things can happen:

  - If there is no `<catch>` block, the exception will be passed through to Ant.
  - If the property attribute has been set, a property of the given name will be set to the message of the exception.
  - If the reference attribute has been set, a reference of the given id will be created and point to the exception object.
  - If there is a `<catch>` block, the tasks nested into it will be run.

  If a `<finally>` block is present, the task nested into it will be run, no matter whether the first tasks have thrown an exception or not.

  Attributes:

  Name | Description | Required
  property | Name of a property that will receive the message of the exception that has been caught (if any) | No
  reference | Id of a reference that will point to the exception object that has been caught (if any) | No

  Use the following task to define the `<trycatch>` task before you use it the first time:

         <taskdef name="trycatch"
                  classname="net.sf.antcontrib.logic.TryCatchTask" />

  ### Crude Example

       <trycatch property="foo" reference="bar">
         <try>
           <fail>Tada!</fail>
         </try>

         <catch>
           <echo>In &lt;catch&gt;.</echo>
         </catch>

         <finally>
           <echo>In &lt;finally&gt;.</echo>
         </finally>
       </trycatch>

       <echo>As property: ${foo}</echo>
       <property name="baz" refid="bar" />
       <echo>From reference: ${baz}</echo>

  results in

         [trycatch] Caught exception: Tada!
             [echo] In <catch>.
             [echo] In <finally>.
             [echo] As property: Tada!
             [echo] From reference: Tada!

  Author:
    Stefan Bodewig, Dan Ritchey

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TryCatchTask.CatchBlock`

  - ### Field Summary

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TryCatchTask()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addCatch(TryCatchTask.CatchBlock cb)`
    `void` | `addFinally(org.apache.tools.ant.taskdefs.Sequential seq)` Adds a nested <finally> block - at most one is allowed.
    `void` | `addTry(org.apache.tools.ant.taskdefs.Sequential seq)` Adds a nested <try> block - one is required, more is forbidden.
    `void` | `execute()` The heart of the task.
    `void` | `setProperty(java.lang.String p)` Sets the property attribute.
    `void` | `setReference(java.lang.String r)` Sets the reference attribute.

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### TryCatchTask

          public TryCatchTask()

  - ### Method Detail

    - #### addTry

          public void addTry(org.apache.tools.ant.taskdefs.Sequential seq)
                      throws org.apache.tools.ant.BuildException

      Adds a nested <try> block - one is required, more is forbidden.
      Throws:
        `org.apache.tools.ant.BuildException`

    - #### addCatch

          public void addCatch(TryCatchTask.CatchBlock cb)

    - #### addFinally

          public void addFinally(org.apache.tools.ant.taskdefs.Sequential seq)
                          throws org.apache.tools.ant.BuildException

      Adds a nested <finally> block - at most one is allowed.
      Throws:
        `org.apache.tools.ant.BuildException`

    - #### setProperty

          public void setProperty(java.lang.String p)

      Sets the property attribute.

    - #### setReference

          public void setReference(java.lang.String r)

      Sets the reference attribute.

    - #### execute

          public void execute()
                       throws org.apache.tools.ant.BuildException

      The heart of the task.
      Overrides:
        `execute` in class `org.apache.tools.ant.Task`
      Throws:
        `org.apache.tools.ant.BuildException`