JDefProg tutorial

Updated to release 0.4.3.

You can check the JDefProg website for a newer version.

For ANY question, criticisms, feedback and so on you are STRONGLY INVITED to contact the author at f.tomassetti@gmail.com

Obtain JDefProg

Download it from https://sourceforge.net/project/showfiles.php?group_id=260360. and unzip it wherever uou prefer.

Setup a project in Eclipse to use JDefProg (with load-time weaving)

To use JDefProg we need first of all to set the project to use the annotations' processor. This is the component that check the code to verify that the assertions are used correctly and signal errors directly on the code. To set the annotations' processor we have to copy the file called JDefProg_AnnoProcWD_version into our project and then select in Eclipse the project, open the context menu (right click) and select "Properties". Under "Properties" we have to choose "Java Compiler", expand it and select Annotation Processing. In that page we have to select "Enable project specific settings" and then "Enable annotation processing" and "Enable processing in the editor". Now let's go to the page Factory Path, click on "Add JARs..." and select JDefProg_AnnoProcWD_version. It's done! The Annotations Processessor is setted correctly. Now just include into the build path JDefProg_ClientWD_version.

The first annotation

Let's try to use the first annotation. JDefProf offers both specific annotations for checks that are very common and generic annotations to implement the full-blended Design-by-Contract. Let's start with a common check. Create a class called MyClass, and copy the following code:

public class MyClass {
        public void printHashCode(@Nn Object myObject){
                System.out.println("The hash code for "+myObject+" is:"+myObject.hashCode());
        }
        public void sumInts(int a, @Nn int b){
                System.out.println(""+a+"+"+b+"="+(a+b));
        } 
}

If we configured the project correctly we should see an error signaled on sumInts because the constraint @Nn has no-sense on primitive-types like int. This feature will be particular useful on more complex annotations.

At this point we are able to specify constraints and obtain error signalations at compile-time. Now we need to enforce theese constraints. To do that JDefProg modify the bytecode inserting the code that check the constraints and throw exceptions when constraints are not satisfied. How? We can do this in two different ways: the first is to use the JDefProg-Agent to modify the cose while it loaded, the second is to to use the JDefProf-Weaver to modify permanently the compiled code changing the classes and jars bytecode. In this tutorial we are going to examinate the first possibility. The bytecode modification at load-time can be obtained just specify an option to the jvm, no else.

Lets' modify the code of the class previoulsy written removing the method addInts and adding the main method:

public static void main(String[] args){ 
	MyClass mc = new MyClass();
	printHashCode(mc); 
	printHashCode("a string"); 
	printHashCode(null); 
}

Now select the class and open the context menu. Select "Run As" and "Run configurations...". Select the tab "Arguments" and under "VM Arguments:" insert "-javaagent:/path/to/JDefProg_AgentWD_version". You can just copy JDefProg_AgentWD_version into the project and insert "-javaagent:JDefProg_AgentWD_version". Now select run. If everything is correct we should obtain an exception on the call: printHashCode(null);

The other common-checks annotations

To be written...

Design by Contract

To be written...