jarnotator on the command line

Last Updated on Tuesday, 24 August 2010 20:14 Written by jarnotator Monday, 16 August 2010 10:01

The jarnotator tool aims at being easy to use. To that end it is also possible to invoke jarnotator on the command line. The command line tools support all the parameters as its ant task and maven2 plugin counterparts.

The command line tool is ideally suited to analyse third party jars since you are less likely to build those from source.

For all command line tools the story always boils down to passing the right options. The key is to know which options are needed. With jarnotator this is very simple, just invoke it without options. It will display the available options. All options are available in both a short and long version. Let's begin with a simple invocation.

As illustrated below invoke the jarnotator jar as you would any other java program. We advice on using the version of the jar which includes the open source libraries need by jarnotator. This jar follows as simple jarnotator-version_here-jar-with-dependencies.jar naming convention. In the example below we'll use the jarnotator-free-1.0-jar-with-dependencies.jar

Please take a look into the download section for the most up to date jarnotator release

Running jarnotator

Just type:

java -jar jarnotator\target\jarnotator-free-1.0-jar-with-dependencies.jar

This call lacks the single most important options, the '-f' which point to jar or directory containing the class to analyze and annotated. Since no options are provided at all the available command line options are list. The actual description of the different option is provided on another page so we will not detail those here.

To analyse and possible annotate a jar called unknown_lib.jar the command would be:

java -jar jarnotator\target\jarnotator-free-1.0-jar-with-dependencies.jar -f path/to/jar/unknown_lib.jar

This invocation will produce a new jar with the same name as the original. The content will be mostly identical to the original jar. Resource type files, like xml, properties and manifest files will remain unchanged. However when necessary bytecode of classes which could benefit of additional annotations will be modified.

You can now run findbugs (TM) on this jar. Alternatively you can simply use this version of the jar in the auxilliary classpath during a findbugs analysis. Indeed, findbugs (TM) takes jsr305 annotation into account when analyzing your classes. In doing so you'll safeguard your code from imperfection in third party libraries.

The short options list

A short options consists of a hyphen ('-') followed by a single character. Often the character will be the first letter of the word describing the option. At the time of this writing the available short options are:

Short options:
-a      Whether annotation are propagated to abstract methods, value(s)=true/yes/1 optional
-b      Extension to use when creating a backup, value(s)=string optional
-cpath  Class path needed by analysed code at runtime, value(s)=comma seperated list of file paths optional
-d      Display some basic debugging info, value(s)=true/yes/1 optional
-f      Location of classes to analyse a jar or a classes directory, value(s)=valid path MANDATORY
-i      Whether annotation are propagated to interfaces, value(s)=true/yes/1 optional
-k      Whether the orignal classes are kept (see backup extension), value(s)=true/yes/1 optional
-o      Process pre java5 bytecode, value(s)=true/yes/1 optional
-q      Suppress output to stdout, value(s)=true/yes/1 optional
-r      Save report of the performed annotation, value(s)=true/yes/1 optional
-s      Display the bytecode, value(s)=true/yes/1 optional
-v      Verify bytecode upon read and write, value(s)=true/yes/1 optional

The long options list

For every short option there exists a long option. Long options start with a double hyphen ('--') and often provide a better description of the option. At the time of this writing the available long options are:

Long options:
--annotate-abstract     Whether annotation are propagated to abstract methods, value(s)=true/yes/1 optional
--annotate-interface    Whether annotation are propagated to interfaces, value(s)=true/yes/1 optional
--backup-extension      Extension to use when creating a backup, value(s)=string optional
--file  Location of classes to analyse a jar or a classes directory, value(s)=valid path MANDATORY
--keep-original Whether the orignal classes are kept (see backup extension), value(s)=true/yes/1 optional
--older-java    Process pre java5 bytecode, value(s)=true/yes/1 optional
--quiet Suppress output to stdout, value(s)=true/yes/1 optional
--save-report   Save report of the performed annotation, value(s)=true/yes/1 optional
--show-bytecode Display the bytecode, value(s)=true/yes/1 optional
--simple-debug  Display some basic debugging info, value(s)=true/yes/1 optional
--verify-bytecode       Verify bytecode upon read and write, value(s)=true/yes/1 optional

Putting it all together

%>java -jar jarnotator\target\jarnotator-free-1.0-jar-with-dependencies.jar
Options: long and short versions exist
Short options:
-a      Whether annotation are propagated to abstract methods, value(s)=true/yes/1 optional
-b      Extension to use when creating a backup, value(s)=string optional
-cpath  Class path needed by analysed code at runtime, value(s)=comma seperated list of file paths optional
-d      Display some basic debugging info, value(s)=true/yes/1 optional
-f      Location of classes to analyse a jar or a classes directory, value(s)=valid path MANDATORY
-i      Whether annotation are propagated to interfaces, value(s)=true/yes/1 optional
-k      Whether the orignal classes are kept (see backup extension), value(s)=true/yes/1 optional
-o      Process pre java5 bytecode, value(s)=true/yes/1 optional
-q      Suppress output to stdout, value(s)=true/yes/1 optional
-r      Save report of the performed annotation, value(s)=true/yes/1 optional
-s      Display the bytecode, value(s)=true/yes/1 optional
-v      Verify bytecode upon read and write, value(s)=true/yes/1 optional

Long options:
--annotate-abstract     Whether annotation are propagated to abstract methods, value(s)=true/yes/1 optional
--annotate-interface    Whether annotation are propagated to interfaces, value(s)=true/yes/1 optional
--backup-extension      Extension to use when creating a backup, value(s)=string optional
--file  Location of classes to analyse a jar or a classes directory, value(s)=valid path MANDATORY
--keep-original Whether the orignal classes are kept (see backup extension), value(s)=true/yes/1 optional
--older-java    Process pre java5 bytecode, value(s)=true/yes/1 optional
--quiet Suppress output to stdout, value(s)=true/yes/1 optional
--save-report   Save report of the performed annotation, value(s)=true/yes/1 optional
--show-bytecode Display the bytecode, value(s)=true/yes/1 optional
--simple-debug  Display some basic debugging info, value(s)=true/yes/1 optional
--verify-bytecode       Verify bytecode upon read and write, value(s)=true/yes/1 optional
----

Exception in thread "main" be.biggerbytes.jarnotator.exceptions.JarnotatorException: No input file or directory specified
        at be.biggerbytes.jarnotator.impl.JarnotatorImpl.process(JarnotatorImpl.java:71)
        at be.biggerbytes.jarnotator.run.Main.run(Main.java:38)
        at be.biggerbytes.jarnotator.run.Main.main(Main.java:269)

This last exception is due to missing input. No -f option was given so you get this error message