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