## org.apache.tools.ant.taskdefs.optional
Class IContract

    java.lang.Object
      |
      +--org.apache.tools.ant.ProjectComponent
            |
            +--org.apache.tools.ant.Task
                  |
                  +--org.apache.tools.ant.taskdefs.MatchingTask
                        |
                        +--org.apache.tools.ant.taskdefs.optional.IContract

All Implemented Interfaces:
  SelectorContainer

public class IContract
extends MatchingTask

Instruments Java classes with iContract DBC preprocessor.
The task can generate a properties file for iControl, a graphical user interface that lets you turn on/off assertions. iControl generates a control file that you can refer to from this task using the controlfile attribute. iContract is at http://www.reliable-systems.com/tools/

Thanks to Rainer Schmitz for enhancements and comments.

Attribute | Description | Required
srcdir | Location of the java files. | Yes
instrumentdir | Indicates where the instrumented source files should go. | Yes
repositorydir | Indicates where the repository source files should go. | Yes
builddir | Indicates where the compiled instrumented classes should go. Defaults to the value of instrumentdir. NOTE: Don't use the same directory for compiled instrumented classes and uninstrumented classes. It will break the dependency checking. (Classes will not be reinstrumented if you change them). | No
repbuilddir | Indicates where the compiled repository classes should go. Defaults to the value of repositorydir. | No
pre | Indicates whether or not to instrument for preconditions. Defaults to `true` unless controlfile is specified, in which case it defaults to `false`. | No
post | Indicates whether or not to instrument for postconditions. Defaults to `true` unless controlfile is specified, in which case it defaults to `false`. | No
invariant | Indicates whether or not to instrument for invariants. Defaults to `true` unless controlfile is specified, in which case it defaults to `false`. | No
failthrowable | The full name of the Throwable (Exception) that should be thrown when an assertion is violated. Defaults to `java.lang.Error` | No
verbosity | Indicates the verbosity level of iContract. Any combination of `error*,warning*,note*,info*,progress*,debug*` (comma separated) can be used. Defaults to `error*` | No
quiet | Indicates if iContract should be quiet. Turn it off if many your classes extend uninstrumented classes and you don't want warnings about this. Defaults to `false` | No
updateicontrol | If set to true, it indicates that the properties file for iControl in the current directory should be updated (or created if it doesn't exist). Defaults to `false`. | No
controlfile | The name of the control file to pass to iContract. Consider using iControl to generate the file. Default is not to pass a file. | Only if `updateicontrol=true`
classdir | Indicates where compiled (unistrumented) classes are located. This is required in order to properly update the icontrol.properties file, not for instrumentation. | Only if `updateicontrol=true`
targets | Name of the file that will be generated by this task, which lists all the classes that iContract will instrument. If specified, the file will not be deleted after execution. If not specified, a file will still be created, but it will be deleted after execution. | No

Note: iContract will use the java compiler indicated by the project's `build.compiler` property. See documentation of the Javac task for more information.

Nested includes and excludes are also supported.

Example:

     <icontract
        srcdir="${build.src}"
        instrumentdir="${build.instrument}"
        repositorydir="${build.repository}"
        builddir="${build.instrclasses}"
        updateicontrol="true"
        classdir="${build.classes}"
        controlfile="control"
        targets="targets"
        verbosity="error*,warning*"
        quiet="true"
     >
        <classpath refid="compile-classpath"/>
     </icontract>

Field Summary

Fields inherited from class org.apache.tools.ant.taskdefs.MatchingTask
`fileset`

Fields inherited from class org.apache.tools.ant.Task
`description, location, target, taskName, taskType, wrapper`

Fields inherited from class org.apache.tools.ant.ProjectComponent
`project`

Constructor Summary
`IContract()`

Method Summary
`Path` `createClasspath()` Sets the classpath.
`void` `execute()` Executes the task
`void` `setBuilddir(java.io.File buildDir)` Sets the build directory for instrumented classes.
`void` `setClassdir(java.io.File classDir)` Sets the class directory (uninstrumented classes).
`void` `setClasspath(Path path)` Sets the classpath to be used for invocation of iContract.
`void` `setClasspathRef(Reference reference)` Adds a reference to a classpath defined elsewhere.
`void` `setControlfile(java.io.File controlFile)` Sets the control file to pass to iContract.
`void` `setFailthrowable(java.lang.String clazz)` Sets the Throwable (Exception) to be thrown on assertion violation.
`void` `setInstrumentdir(java.io.File instrumentDir)` Sets the instrumentation directory.
`void` `setInvariant(boolean invariant)` Turns on/off invariant instrumentation.
`void` `setPost(boolean post)` Turns on/off postcondition instrumentation.
`void` `setPre(boolean pre)` Turns on/off precondition instrumentation.
`void` `setQuiet(boolean quiet)` Tells iContract to be quiet.
`void` `setRepbuilddir(java.io.File repBuildDir)` Sets the build directory for instrumented classes.
`void` `setRepositorydir(java.io.File repositoryDir)` Sets the build directory for repository classes.
`void` `setSrcdir(java.io.File srcDir)` Sets the source directory.
`void` `setTargets(java.io.File targets)` Sets the name of the file where targets will be written.
`void` `setUpdateicontrol(boolean updateIcontrol)` If true, updates iControl properties file
`void` `setVerbosity(java.lang.String verbosity)` Sets the verbosity level of iContract.

Methods inherited from class org.apache.tools.ant.taskdefs.MatchingTask

`add, addAnd, addContains, addContainsRegexp, addCustom, addDate, addDepend, addDepth, addDifferent, addFilename, addMajority, addModified, addNone, addNot, addOr, addPresent, addSelector, addSize, addType, appendSelector, createExclude, createExcludesFile, createInclude, createIncludesFile, createPatternSet, getDirectoryScanner, getImplicitFileSet, getSelectors, hasSelectors, selectorCount, selectorElements, setCaseSensitive, setDefaultexcludes, setExcludes, setExcludesfile, setFollowSymlinks, setIncludes, setIncludesfile, setProject, XsetIgnore, XsetItems`

Methods inherited from class org.apache.tools.ant.Task
`getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

Methods inherited from class org.apache.tools.ant.ProjectComponent
`getProject`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### IContract

    public IContract()

Method Detail

### setSrcdir

    public void setSrcdir(java.io.File srcDir)

  Sets the source directory.

  Parameters:
    `srcDir` - the source directory

### setClassdir

    public void setClassdir(java.io.File classDir)

  Sets the class directory (uninstrumented classes).

  Parameters:
    `classDir` - the source directory

### setInstrumentdir

    public void setInstrumentdir(java.io.File instrumentDir)

  Sets the instrumentation directory.

  Parameters:
    `instrumentDir` - the source directory

### setBuilddir

    public void setBuilddir(java.io.File buildDir)

  Sets the build directory for instrumented classes.

  Parameters:
    `buildDir` - the build directory

### setRepositorydir

    public void setRepositorydir(java.io.File repositoryDir)

  Sets the build directory for repository classes.

  Parameters:
    `repositoryDir` - the source directory

### setRepbuilddir

    public void setRepbuilddir(java.io.File repBuildDir)

  Sets the build directory for instrumented classes.

  Parameters:
    `repBuildDir` - the build directory

### setPre

    public void setPre(boolean pre)

  Turns on/off precondition instrumentation.

  Parameters:
    `pre` - true turns it on

### setPost

    public void setPost(boolean post)

  Turns on/off postcondition instrumentation.

  Parameters:
    `post` - true turns it on

### setInvariant

    public void setInvariant(boolean invariant)

  Turns on/off invariant instrumentation.

  Parameters:
    `invariant` - true turns it on

### setFailthrowable

    public void setFailthrowable(java.lang.String clazz)

  Sets the Throwable (Exception) to be thrown on assertion violation.

  Parameters:
    `clazz` - the fully qualified Throwable class name

### setVerbosity

    public void setVerbosity(java.lang.String verbosity)

  Sets the verbosity level of iContract. Any combination of error*,warning*,note*,info*,progress*,debug* (comma separated) can be used. Defaults to error*,warning*

  Parameters:
    `verbosity` - verbosity level

### setQuiet

    public void setQuiet(boolean quiet)

  Tells iContract to be quiet.

  Parameters:
    `quiet` - true if iContract should be quiet.

### setTargets

    public void setTargets(java.io.File targets)

  Sets the name of the file where targets will be written. That is the file that tells iContract what files to process.

  Parameters:
    `targets` - the targets file name

### setControlfile

    public void setControlfile(java.io.File controlFile)

  Sets the control file to pass to iContract.

  Parameters:
    `controlFile` - the control file

### setClasspath

    public void setClasspath(Path path)

  Sets the classpath to be used for invocation of iContract.

  Parameters:
    `path` - the classpath

### createClasspath

    public Path createClasspath()

  Sets the classpath.

  Returns:
    the nested classpath element
  To do:
    this overwrites the classpath so only one effective classpath element would work. This is not how we do this elsewhere.

### setClasspathRef

    public void setClasspathRef(Reference reference)

  Adds a reference to a classpath defined elsewhere.

  Parameters:
    `reference` - referenced classpath

### setUpdateicontrol

    public void setUpdateicontrol(boolean updateIcontrol)

  If true, updates iControl properties file

  Parameters:
    `updateIcontrol` - true if iControl properties file should be updated

### execute

    public void execute()
                 throws BuildException

  Executes the task

  Overrides:
    `execute` in class `Task`
  Throws:
    `BuildException` - if the instrumentation fails

Copyright © 2000-2004 Apache Software Foundation. All Rights Reserved.