B. Usage of the OCL Tool

This chapter describes, how to use the instrumentation tool. Section contains an example quickly demonstrating the main features. Section provides a complete reference of the command line options.

B.1 Example

B.1.0.0.1 Step 1:

First, get the following files: dresden-ocl-injector.jar, xerces.jar and royloy.jar. These files are available on our website at dresden-ocl.sourceforge.net or may be produced from the sources using the makeJar script. Put these files into one directory and change into that directory.

The file royloy.jar contains the example code. To unzip it type:

jar -xf royloy.jar

You may now have a look at the example code, its in tudresden/ocl/test/royloy/. The java code already contains OCL expressions in javadoc comments, for an easy start see Person.java and Company.java. Additional OCL is in the file oclexpressions.

B.1.0.0.2 Step 2:

Now it's time to start the OCL tool. Type the following command on a single line. Note, that the wildcards require a Unix shell to be expanded.

java -jar dresden-ocl-injector.jar 
   -r tudresden.ocl.test.royloy 
   -modify tudresden/ocl/test/royloy/*.java 

The example java code has now been modified. The modified code will have the same behavior as the original code, but will additionally check the OCL constraints embedded in the javadoc comments.

B.1.0.0.3 Step 3:

To check this, compile the modified java code (again type everything on a single line):

javac 
   -classpath dresden-ocl-injector.jar 
   tudresden/ocl/test/royloy/*.java

and

B.1.0.0.4 Step 4:

Run the test main function provided:

java 
   -cp .:dresden-ocl-injector.jar 
   tudresden.ocl.test.TestInjectionRoyloy 

Enjoy the messages about violated OCL constraints running down the screen. Messages contain information about the violated constraint and the object involved.

B.1.0.0.5 Step 5:

Clean the code from the modifications the OCL tool made.

java -jar dresden-ocl-injector.jar 
   -clean -modify tudresden/ocl/test/royloy/*.java 

The example code is now exactly the same as you downloaded it.

Note, that the code actually was cleaned. No backups involved. To check this, try the following:

1. Make a backup of one or more java files just before running the OCL tool (step 2).
2. After running the tool make some small modifications to the files, you made a backup for. For example just add a single System.out.println to a method body.
3. Proceed until step 5.
4. Compare the cleaned code to your backup.

The difference will be just the small modifications you made.

B.2 Reference

Synopsis is below.

java tudresden.ocl.injection.Main [options] file.java ..

Provide all java files to be modified.

Options recognized are below. Most options have a short and a long version. Long versions try to be self explanatory and should be used in scripts.

-m -modify

Enables modifying java files. If not provided, the modified java code is written to file.java.injected. This switch serves as a safety check, whether you really want to replace your source code with the output of the OCL tool.

-c -clean

Performs cleaning of source files instead of instrumentation. After cleaning, the source code should show no differences to the version before running the OCL tool.

-f -constraint-file constraints.txt

Specifies the text file containing the constraints. Usually not needed, since constraints may and should be placed into javadoc comments. See section .

-r -reflection-model modelpackage

Specifies the java packages containing the model covered. If there is a constraint context Person, the type checker will look for class Person in all packages given by this option. This is some kind of ``import for OCL''. For multiple packages use multiple options.

-n -name-adapter [none|argo]

Specifies the name adapter. Default is none. If you don't use code generated by Argo/UML, the default is sufficient. Further information on name adapters is available at [FF00] section 3.5.1 and 3.5.6.

-is -invariant-scope 

      [all|private|protected|package|public|explicit]

Specifies the the scope of invariants used. See section for a detailed explanation. Access modifiers select methods having the same or a more public access modifier. Thus, all and private are equivalent. Default is all.

-vm -violation-macro macro

Specifies what to do, if a constraint fails. This string is inserted verbatim into the code. The OCL tool appends a pair of parents enclosing a suitable message string. Good candidates are System.out.println (the default) or throw new RuntimeException. Note, that the latter must be enclosed in "" on Unix shells.

The exception thrown must not be a checked exception as specified by [GJS96] section 11.2. Otherwise the modified code will not compile!

-tt -trace-types

Performs type tracing of collection elements. See section for details. The information gathered is written to a log file specified by property tudresden.ocl.injection.lib.TypeTracer.log.

Note, that the log file must be specified when running the user program, not the OCL tool! For example use -Dtudresden.ocl.injection.lib.TypeTracer.log=example.ocltypetrace. If not specified, the type information is written to standard out.

-insert-immediately

Triggers immediate insertion of wrapper methods. Otherwise wrapper methods are inserted at the end of each class. Immediate insertion allows easier tracing of the modifications. This option is mainly useful for debugging.

-trace-checking

Adds code logging each constraint checked on an object to standard out. Useful for debugging.

-simple-hash

Uses simple hash functions in HashSize, instead of the sophisticated hash functions in HashExact. Simple hash functions just return the size of the collection, so they will detect insertions/deletions only. Reduces CPU load for big models.

-modcount-hash

Uses hash functions in HashModCount, instead of the hash functions in HashExact. HashModCount functions are even better in modification detection than functions in HashExact. Also, they are almost as fast as HashSize. However, they heavily depend on internals of the java collections implementation. Use at your own risk. See section .