1 What is joodi?
joodi is an open source tool that analyses the design of a java program. It is intended to find and report on problems with the design in order to help the developers of the system keep it cohesive and consistent even as it is rapidly growing. joodi does not attempt to replace tools like checkstyle that focus on issues at the class level. joodi focuses on the relatively bigger picture of package and component design issues such as layering, coupling and abstraction.
joodi is intended to form part of a test-driven development strategy in which each time the system is built it is tested against the design constraints understood by joodi. joodi comes pre-loaded with some well-understood design guidelines already implemented and is completely customisable by the user through declarative rules that define the acceptable design constraints for the system.
2 How does it work?
joodi needs the compiled byte code of the application to be analysed. For example, you can simply ask joodi to analyse your (or someone else's) jar file or set of jar files. joodi then makes its own model of the system and analyses it using design guidelines expressed as formal business rules.
joodi uses drools as its rule engine. We won't go into the whole topic of how business rule engines work here, but you will need to appreciate that joodi's feature set and performance is in great part affected by the underlying approach. joodi is essentialy a thought experiment to see if good object-oriented design principles can be practically expressed in formal business rules. The jury is still out, but so far so good.
3 Features
joodi is in the very early stages of development, so features are not numerous at the moment. A key aspect of what joodi does is to provide traceability on the warnings and errors provided. You'll see the benefits of this when you see a joodi report and need to understand what it's telling you.
3.1 Cyclic Package Dependency Detection
joodi detects cycles in java package dependencies. Similar to what jdepend does, but very different in how it is achieved, this is an important design issue to keep an eye on when developing your software. We'll leave the discussion of why this is something to avoid to other sources for now.
As mentioned above, one of the nice things about joodi is that you get traceability to the cause of the design issue. For example, below is a snippet of a joodi report that detected a cyclic package (joodi calls them namespaces) dependency when run against the java runtime library (rt.jar):
Figure 1: Cyclic Dependency in rt.jar
This shows a chain of packages that form a cycle of dependencies. Imagine you were starting with the source code for just one of these packages and trying to get it to compile. You would find it impossible to compile any single one of them on its own. This is one way to understand why this is a poor design choice.
3.2 Parent-Child Package Dependency Detection
Just like in life, it's generally considered appropriate for children to be dependent on their parents, but not the other way around. In the world of package design, it is normal for a sub-package to use classes and interfaces defined in its parent package. For example, a common idiom is to define interfaces and factories in one package, and push the implementations down to a sub-package.
On the assumption that you've accepted the idea above that cyclic package dependence is bad, and that child packages are appropriately dependent on their parents, we can logically infer that to avoid cyclic dependence, we have to veto parent packages depending on their children. joodi can detect this kind of incestuous relationship in your design and alert you to it. Whether you think it's a good thing is, of course, a matter of taste.
Check out the joodi report on Ant below (in Sample Reports) for some examples of this common design issue.
3.3 Parent-Child Type Dependency Detection
Much like with packages as described above, design issues can arise in class/interface hierarchies as well. It is not usually a good idea to give a superclass explicit knowledge of its own subclasses, since this limits the ability of others to repurpose the classes in ways not foreseen by the creator of the code. It is also often a sign of too many responsibilities being placed on a class. For example, having a superclass instantiate a known subclass in a factory method is placing both abstraction and factory responsibilities on the superclass.
joodi will detect such usages for you, but as with all the notifications, you can ignore them. See Customising joodi for details on getting joodi to produce only the notifications you need.
4 Getting Started
4.1 Downloading
You can get the software from the joodi web site. joodi comes packaged in a single .zip or .tar.gz file with everything you need included. All dependent jar files needed to run the software are part of the distribution.
4.2 Building from Source
If you prefer, you can build the software yourself by following the instructions below.
4.2.1 Getting the Source
Anonymous CVS access is provided to enable you to get the source code. On the assumption you know what you're doing when it comes to CVS, all you need to know is the repository path, which is :pserver:anonymous@cvs.sf.net:/cvsroot/joodi and the module name which is simply joodi.
So a cvs command like:cvs -d :pserver:anonymous@cvs.sf.net:/cvsroot/joodi checkout joodi will do the trick.
4.2.2 Building with Ant
You will need Ant installed and configured on your system. If you do not have Ant, you are probably better off using the binary distribution available from the joodi web site.
Open the command shell of your choice in the joodi/src directory. Then just type ant to do a complete build of the software. If you get issues with creating a task for JUnit, drop the junit.jar file in your %ANT_HOME%/lib directory and try again.
After a successful build of the system, you will find the distribution archive in the joodi/build directory. This is the same file that you download if you choose to get the sofware from the joodi web site
4.3 Installing
To install joodi, simply extract the contents of the distribution archive into a directory of your choice and open a command shell in the extracted directory. You will know you are in the right place if the joodi jar file is there.
4.4 Running
You will need a Java Runtime Environment version 1.4 or later to run joodi.
4.4.1 Getting usage instructions
To get usage instructions, simply launch the joodi jar file with no arguments as follows: java -jar joodi.jar
Note that the joodi jar filename will be different from that shown here as it will include a version number in its name.
4.4.2 Analysing a single jar
To analyse an application packaged in foo.jar and produce a html report named joodi-foo.html, use the following command: java -jar joodi.jar --out joodi-foo.html foo.jar
You will see output as joodi loads each class file into the rule engine, then executes the rules, and finally finishes processing. Each line of output produced by joodi has the elapsed time in milliseconds displayed at the start of the line. The following figure shows the (edited) output produced when analysing rt.jar.
Java-based Object-Oriented Design Inferometer 0.1 - http://www.sf.net/projects/joodi Copyright (c) 2003-04 RedHill Consulting, Pty. Ltd. All rights reserved. (0 ) Starting (null: 24, 57): cvc-elt.1: Cannot find the declaration of element 'rule-set'. (2093 ) Loading classes from c:/j2sdk1.4.2_03/jre/lib/rt.jar... (2123 ) Loading zip: c:/j2sdk1.4.2_03/jre/lib/rt.jar (2183 ) Loading class: com/sun/accessibility/internal/resources/accessibility.class (2523 ) Loading class: com/sun/accessibility/internal/resources/accessibility_de.class (2613 ) Loading class: com/sun/accessibility/internal/resources/accessibility_en.class (2693 ) Loading class: com/sun/accessibility/internal/resources/accessibility_es.class (2754 ) Loading class: com/sun/accessibility/internal/resources/accessibility_fr.class (2834 ) Loading class: com/sun/accessibility/internal/resources/accessibility_it.class (2904 ) Loading class: com/sun/accessibility/internal/resources/accessibility_ja.class (2914 ) Loading class: com/sun/accessibility/internal/resources/accessibility_ko.class (2924 ) Loading class: com/sun/accessibility/internal/resources/accessibility_sv.class (2934 ) Loading class: com/sun/accessibility/internal/resources/accessibility_zh_CN.class (3034 ) Loading class: com/sun/accessibility/internal/resources/accessibility_zh_TW.class (3144 ) Loading class: com/sun/corba/se/ActivationIDL/Activator.class (3154 ) Loading class: com/sun/corba/se/ActivationIDL/ActivatorHelper.class ... ... (108776) Loading class: com/sun/java/swing/plaf/gtk/SynthTreeUI$TreeSelectionHandler.class (108786) Loading class: com/sun/java/swing/plaf/gtk/SynthTreeUI$TreeTransferHandler.class (108786) Loading class: com/sun/java/swing/plaf/gtk/SynthTreeUI.class (109197) Loading class: com/sun/java/swing/plaf/gtk/SynthUI.class (109197) Loading class: com/sun/java/swing/plaf/gtk/SynthViewportUI.class (109217) Loading class: com/sun/java/swing/plaf/gtk/TabContext.class (109217) Loading class: com/sun/java/swing/plaf/gtk/XColors$XColor.class (109217) Loading class: com/sun/java/swing/plaf/gtk/XColors.class (109367) Loading setup facts... (111059) Executing rules... (111720) Running report... (113633) Finished with 346 violations
4.4.3 Analysing a set of jars
The easiest way to analyse multiple jars or directories is to pass them as trailing arguments to joodi:java -jar joodi.jar --out joodi-foo.html foo.jar bar.jar mybuild/classes
To more easily analyse a large set of jars in the directory myjars and produce a html report named joodi-myapp.html, use the following command (you will need cygwin under Microsoft Windows):find myjars -name '*.jar'|xargs java -jar joodi.jar --out joodi-myapp.html
Either method will analyse all the class files in all the jars as if they were in a single jar.
4.4.4 Running from an Ant build
The joodi distribution includes an Ant task that you can use to run joodi from your build. Below is an example demonstrating how to use the task:
<taskdef name="joodi" classname="net.sf.joodi.plugins.ant.JoodiTask">
<classpath>
<fileset dir="${joodi.install.dir}" includes="**/*.jar"/>
</classpath>
</taskdef>
<joodi report="build/joodi-report.html">
<path location="build/my-application.jar"/>
<path location="build/classes"/>
</joodi>
Before you can use the joodi task in your build, you should define the task using <taskdef>. Note that you should include all the jars from the distribution in the classpath used to define the task (see the example above).
The task takes a report attribute, which specifies where the report should be written to. The task also take one or more nested <path> elements, which specify the jars and directores that contain the classes to inspect.
5 Understanding the joodi report
The report produced by joodi can be fairly long if the codebase being analysed is large. There is currently no mechanism for sorting the notifications contained in the report so that those you consider most important are at the top, but feel free to give us some feedback on how the report can be made easier to understand.
The joodi report is simply a list of notifications that alert you to violations of the design principles that joodi understands. Each notification is designed to have complete traceability back to the code, allowing you to go and fix the problem if you agree it is one!
Below are a few sample joodi reports run over well-known codebases to give you an idea of the design issues lurking inside that would otherwise be extremely difficult to pin down, especially if you are not deeply familiar with the code.
5.1 Sample Reports
6 F.A.Q.
TBD
7 Customising joodi
TBD
8 Roadmap
TBD
9 References
joodi web site, http://sf.net/projects/joodiAnt java build tool, http://ant.apache.org
Checkstyle coding standards checker, http://checkstyle.sourceforge.net/
cygwin Unix shell for Windows, http://www.cygwin.com
drools open source business rule engine, http://drools.org/
Java Runtime Environment, http://java.sun.com/j2se/
JDepend dependency analyser, http://www.clarkware.com/software/JDepend.html
JUnit, http://www.junit.org
joodi report on rt.jar, samples/joodi-report-rt-jar.html
joodi report on Ant 1.6.2, samples/joodi-report-ant-1.6.2.html
10 List of Figures
Figure 1: Cyclic Dependency in rt.jar