How to download AnnoJ

The latest release of AnnoJ can be downloaded here.

Where can I read the API documentation?

The documentation can be generated (see next point) or can be read here.

Where to start?

After reading this FAQ see "@ToString manual" and "@Loggable manual"

How to use AnnoJ?

If you want to build AnnoJ from source you have to install apache ant and download the source files from the cvs repository.
To use it instantly download the archive from the download page and uncompress it to your local filesystem. Then add annoj.jar and the other jar files in the lib directory to your project's classpath.
To generate code documentation execute this command is annoj's directory:

	ant javadoc

The documentation wwill be generated to %ANNOJ_HOME%/doc. IMPORTANT At the moment AnnoJ can't be used in application servers and isnt "classloader-safe", ie. if another classloader had loaded a class and AnnoJ attempts to load it again then the application crashes.
After building AnnoJ one can use it in his applications. annoj.jar, log4j*.jar and javassist.jar must be on the classpath.

Show me an example! (bootstraping)

AnnoJ easily can be used with applications that have a class with main method. Thre's a class called annoj.loader.MainMethodBootstrap. It's responsibility is to call another classes main as if it was started from command line. Its only method is callMainMethod with two parameters: the first is the name of the class in which the main method is and the second is the array of the arguments to pass.
Example:

	public class StarterClass{
		public static void main(String[] args){
			MainMethodBootstrap.callMainMethod("ClassWithMainMethod",
						 new String[]{"something"}); 
		}
	}

The effect of bootstraping is that all classes are loaded with a special classloader that can intrepret AnnoJ's annotations and modify the class bytecode accordingly.
So for example if the class below is loaded in a bootstrappd program then every iunvocation of its methods will be logged and a toString method will be generated in it.:

	@Loggable
	@ToString
	public class InterestingClass{
		public void interestingMethod(){
		}
	}

For details of the use of the annotations consult the generated API documentation.

How to use @ToString

With @ToString annotation you can tell AnnoJ to generate a toString method in a specific class. The only thing you have to do is to place the annotation before the definition of the class and bootstrap the application.
If you want to generate toString method in all classes of a package, you need to create a class called PackageInfo in that package and annotate it with @ToString.
If you place the @Exclude annotation before a field then that field wonQt appear in the string returned by toString.

How to use @Loggable

With @Loggable you can tell AnnoJ to generate logging method calls to the begining of some or all methods of a class.
If @Loggable is used without parameters before a class definition then all methods will be logged.
Or you can specifi which methods to log in the following way:

	@Loggable(methods={""})
	public class InterestingClass{
		public void interestingMethod(){

		}
		//other methods
	}

In the above example only the invocations ofinterestingMethod will be logged.
If you annotate a method with @Loggable then that method will alway be logged.
You can use PackageInfo class in the same way as stated in the previous point.

What is javassist?

Javassist is a bytecode modification tool. It can be used to define methods on-the-fly. Examples of using and integrating it with other technologies can be read at my java blog (in hungarian)
AnnoJ utilizes javassist for example for generating toString() mehtods.

Why make AnnoJ debugging easier

Consider an application full of generated classes (by wsimport, for example). When many methods accepts this generated types as parameters logging/debugging is mere pain. If a method is called and you need to see the internal state of the paraeter object you have to work hard - unless you have an efficient tool for the job.
With @ToString annotation AnnoJ is able to generate toString() methods so you only have to print the parameters out the object will show you its internal state.
Or think about logging. Sometimes it's important to log when a method is called. How does AnnoJ help you? By using @Loggable annotation it can implement this kind (and many other kinds in the future) of logging.

What features does AnnoJ have?

The features provided (at the moment):

• @ToString annotation for generating toString() methods for classes or classes in a package
• @Exclude,@Include annotations to control toString()
  generation
• @Loggable annotation for automatic logging (uses log4j)
• ToStringBuilder for generating the string representation of objects

What features are planned?

• equals() and hashCode() generation
• custom classloader to eliminate configuration file
• etc.

Who are you?

I'm Akos Tajti. For details see my LinkedIn profile.