1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
Contracts for Java is a contract programming framework for Java, which
uses annotation processing and bytecode instrumentation to provide
run-time checking.
1. DEPENDENCIES
Contracts fo Java requires Java version 6 for annotation processing
and bytecode instrumentation. The bytecode rewriter depends on the ASM
bytecode manipulation library, version 4.x or higher.
Since the Java agent rewrites bytecode in order to inject contracts
into the loaded code, the ASM library needs to be available in the
class path at run time if contract checking is enforced through the
agent. Pre-contracted class files do not need the ASM library or the
agent to run with contracts enabled.
2. CONFIGURATION
In order for the build script to run properly, you must at least
specify the correct path to Cofoja's dependencies in your local build
properties file:
./local.properties
This file does not exist by default; you can either create it or start
from a copy of the default configuration file:
./default.properties
That file also contains all user-settable properties with their
descriptions and default values. Once you're done, set the following
property to true to let Ant run:
configured=true
3. QUICK START
To build a JAR file containing all Cofoja classes, run:
ant dist
The JAR file will be located at:
./dist/lib/cofoja-<version>.jar
It can be used both as a Java agent and annotation processor and
should be added to your class path.
To compile code with contract annotations, run:
javac -processor com.google.java.contract.core.apt.AnnotationProcessor <someclass>.java
To execute code compiled with contract checking enabled, make sure the
generated files (additional .class and .contracts files) are in your
class path, and run:
java -javaagent:path/to/cofoja-<version>.jar <someclass>
4. ADVANCED BUILD
Contracts for Java is annotated with its own contracts, which can be
compiled, tested and bundled into the result JAR file so it checks its
own contracts when compiling and checking your program's contracts!
Please note that running such a build will necessarily be slower than
running an unchecked version of Contracts for Java, but is a great way
for you to contribute to the project by helping exercise its own
capabilities while using it.
To build a contracted version of Contracts for Java, you need to have
a Cofoja JAR file ready first (see previous section; or you could
reuse one you've built with a previous run of this bootstrap
process). Copy the JAR file to:
./build/bootstrap.jar
Then run:
ant bootstrap
Once the contracted version is complete, you can run the test suite
with:
ant test
Aside from self-contracted builds, Cofoja JAR files bundled with ASM
library classes can also be produced, for the sake of easier
distribution:
ant -Dasmjar=path/to/asm-all-<version>.jar dist
5. USAGE
Contracts for Java consists of an annotation processor, an
instrumentation agent, as well as an offline bytecode rewriter. The
annotation processor compiles annotations into separate contract class
files. The instrumentation agent weaves these contract files with the
real classes before they are loaded into the JVM. Alternatively, the
offline bytecode rewriter can be used to produce pre-weaved class
files that can be directly deployed without any Cofoja dependency.
The following instructions assume that you have the Cofoja and ASM JAR
files in your class path.
The annotation processor's entry point is (for use with the -processor
javac option):
com.google.java.contract.core.apt.AnnotationProcessor
The Java agent can be invoked from the compiled JAR file (for use with
the -javaagent java option):
./dist/cofoja-<version>.jar
The offline instrumenter can be run with:
java -Dcom.google.java.contract.classoutput=<outdir> \
com.google.java.contract.core.agent.PreMain <someclass>.class
Please refer to the official online documentation for more
information:
http://code.google.com/p/cofoja/wiki/QuickReference
6. BUGS
Contracts for Java is a very young project. Please help us make it
better by reporting bugs and posting patches at:
http://code.google.com/p/cofoja/issues/
|
