iControl

Download iControl.zip
Download iControl.tar.gz
Check out iContract Extras

iControl is a graphical user interface that lets you choose where iContract assertions should be enabled/disabled. It generates a control file that can be passed to iContract during instrumentation.

iControl is a great tool if you have a lot of source code that doesn't have iContract assertions (and possibly bad quality javadoc which would confuse iContract). You can pinpoint down to the method level what should be processed by iContract and what shouldn't.

If you have just discovered iContract and nobody else on your project have a clue what it is and your project manager is all sceptical about using it all over the project, then iControl is for you. You can start writing @pre @post and @invariant comments in your own code, use iControl to tell iContract to instrument only that code, and start experimenting with DBC right away!

Here is how you can run it from Ant: (NB! Remember to change the location of your tools.jar!)

<!-- =================================================================== -->
<!-- Runs iControl                                                       -->
<!-- =================================================================== -->
<target name="icontrol" depends="compile" description="Runs iControl">
   <java classname="${devlib.dir}/iControl.jar" fork="yes">
      <!-- We need JavaP on the classpath. It's in JDK's tools.jar -->

      <!-- for some reason, this line doesn't work... -->
      <!--jvmarg value="-Xbootclasspath/a:${java.home}/lib/tools.jar"/-->
      <!-- but this one does -->
      <jvmarg value="-Xbootclasspath/a:F:/jdk1.3/lib/tools.jar"/>
      <jvmarg value="-jar"/>
   </java>
</target>

The classes must be compiled (without iContract) before iControl can run, hence the dependance of the compile target.
iControl uses JDK's Javap to analyse the method signatures.

When you execute this target, iControl will pop up empty.
Now, you should pick a properties file that iControl will use to figure out what classes it should analyze, where to write the configuration files etc.
The properties file can be generated for you by the iContract Ant task if you specify updateicontrol="true". (See documentation for the iContract task).
Therefore, you should execute the iContract task once before the first time you execute the iControl target, so this file can be generated automatically for you.

This is what it would look like if you were to instrument the sources from the tutorial:

A black checked box indicates that the next time iControl is run, it will instrument for the associated assertion type (in the column) on the associated program element (a row in the tree). A program element is either the whole project, a package, a class or a method.

A gray checked box means that some sub elements of the associated program elements will be instrumented, and some not. Play around a little, it should be pretty obvious.

Note that for methods and constructors, you can't turn on/off invariants, as invariants apply to classes only.

The settings tab is a simple classpath editor where you can see what's on the classpath. This can be useful if you get warning boxes from iControl complaining about classes that can't be found.

The five properties in icontrol.properties are as follows (in case you need to modify them manually):
sourceRoot: The root directory of your sources that iContract will instrument.
classpath: The classpath that iControl needs to analyse the classes to be instrumented. This is the same classpath which is required to compile the classes.
classRoot: The root directory of the compiled classes.
controlFile: The name of the control file that iControl will generate. This is the file that iContract will use to decide what parts of the code should be instrumented. In order for iContract to actually use this file, the controlfile attribute of the iContract Ant task must refer to the same file.
targetsFile: The name of the targets file that iControl will generate. This is the file that iContract will use to decide what source files should be instrumented. In order for iContract to actually use this file, the targets attribute of the iContract Ant task must refer to the same file.

If you can't get it to work, it's probably not your fault, but the incomplete or wrong instructions. It might even be a bug. In any case, please contact the author if you have questions or suggestions.