Andy@Gigantiq

Gigantiq has a number of exciting opportunities we are exploring at the moment. We are looking for smart Java developers to join the Melbourne team.

If you think that you can fit into a team of skilled, passionate Software Developers then drop us a line and tell us about yourself.
We are happy to engage the right people on a contract or permanent basis.

jobs@gigantiq.com
www.gigantiq.com

Macker is my prefered tool for java package dependency enforment. It is a free tool licenced under GPL.

While Macker is not as simple as Japan to configure, it is not difficult and is considerably more powerful. Like Japan, Macker is configured via XML and is designed to be integrated into an ant build.

Here is a sample macker configuration file.

<?xml version="1.0"?>
<macker>
<ruleset name="Module dependency checking rules">
<var name="base" value="com.gigantiq.bedrock"/>

<pattern name=”root”>
<include class=”${base}.**”/>
</pattern>

<pattern name=”model”>
<include class=”${base}.model.**”/>
</pattern>

<pattern name=”ui”>
<include class=”${base}.ui.**”/>
</pattern>

<pattern name=”util”>
<include class=”${base}.util.**”/>
</pattern>

<!– Dependency rules –>
<access-rule>
<message>model package class ${from} cannot use class ${to}</message>
<deny><from pattern=”model”/><to pattern=”root”/></deny>
<allow><to pattern=”model”/></allow>
<allow><to pattern=”ui”/></allow>
</access-rule>

<access-rule>
<message>ui package class ${from} cannot use class ${to}</message>
<deny><from pattern=”ui”/><to pattern=”root”/></deny>
<allow><to pattern=”ui”/></allow>
</access-rule>

<access-rule>
<message>util package class ${from} cannot use class ${to}</message>
<deny><from pattern=”util”/><to pattern=”root”/></deny>
<allow><to pattern=”util”/></allow>
<allow><to pattern=”model”/></allow>
<allow><to pattern=”ui”/></allow>
</access-rule>
</ruleset>
</macker>
The pattern element allows us to define patterns that can be re-used in the macker rules that we define. In this example I have used the pattern elements to define the packages that will be referred to in the macker rules.

We can now define our package dependencies using the access-rule element. For example:

<access-rule>
<message>model package class ${from} cannot use class ${to}</message>
<deny><from pattern="model"/><to pattern="root"/></deny>
<allow><to pattern="model"/></allow>
<allow><to pattern="ui"/></allow>
</access-rule>


In this fragment I define that the model and ui packages are the only packages that can depend on the model package. I have also used the ${from} and ${to} in the message element to ensure that a readible message is produced on an access rule voilation. The message produced will contain the names of the classes responsible for the voilation.

The macker site contains plenty of examples that illustrate some of the capabilities of macker.

Like Japan, Macker includes a built in ant target that makes integration with an ant build very simple. The added time introduced to your build by adding macker should be minimal even on a large code base (less than 10 seconds).

Something I considered trying at one stage was to use XSLT to produce a GraphML file from the macker configuration file so that the defined package dependencies could be viewed in graphical manner using tools such as yEd. I have not had an opportunity to try this yet to see if it would work. If I do, I will post the results on this blog.

Japan is another open source tool that can be used for enforcing package dependencies. It comes with an IntelliJ plugin as well as an ant task. The ant task makes it trivial to incorporate into an ant build.

The real beauty of Japan is how simple it’s configuration is despite being a dreaded XML file.

<japan-config base-package="com.gigantiq.bedrock" ignore-indicator="// JAPAN:IGNORE">
<dependency-set name="module" package-depth="4" transitive="true">
<dependency from="model" to="ui"/>
<dependency from="ui" to="model,ui"/>
<dependency from="util" to=""/>
</dependency-set>
</japan-config>


The document element, japan-config, defines an attribute called base-package. This allows the base package of the project to be defined. In this case the base-package is com.gigantiq.bedrock.

The dependency-set defines the allowed dependencies at specified depth. It is here that Japan exhibits it’s biggest limitation. Japan assumes that the dependencies you wish to enforce are all at the same level within the package hierarchy.

In the above example, since the dependencies we are enforcing are all below the package com.gigantiq.bedrock, we state that the package-depth for this dependency-set is 4. This can become problematic if you are retrofitting Japan to an existing project whose package structure is not very uniform. Japan’s work-around for this is that it allows multiple dependency-set elements to be defined all with different values for the package-depth attribute. Too many dependency-set elements though, lead to an overly complicated configuration file.

Since Japan comes with a Ant task it can be added to your existing ant build very easily.

<taskdef classname="net.sourceforge.japan.ant.JapanTask" name="japan" classpath="build/lib/ant/japan-0.1.jar:build/lib/ant/jdom.jar"/>
<target name="dependency-check" >
<japan sourcePath="source/java.main;" japanConfigFile="japan-config.xml" />
</target>

The error reporting that results from the ant task is very easy to interpret. Both ends of a violation are clearly highlighted.

So what are the biggest problems with Japan? There two main issues I have with Japan one of which I have already mentioned.

First is the flexibility that is lost with a dependency-set only allowing dependencies to be defined at a single level with in a package. The second is the absence of any tools for analysing an applications package dependencies.

The biggest thing that Japan has going for it, is that it is incredibly simple to use and trivial to include in my build.

JDepend is probably the best known of the package dependency tools. It has certainly been around for quite a while.

JDepend allows you to analyse java package metrics, dependencies, and cycles and allows you to visualise the analysis in a graphical UI, textual UI, and XML UI. I won’t go into detail on how to do this since it would largely require me to regurgitate what is already documented at the JDepend web site. My real interest is how can I integrate this into my build and have my build break when certain dependencies break.

JDepend allows you to right JUnit tests that codify the dependency constraints you wish to enforce. If any of these dependency constraints are broken, the unit test will fail. An example of such a unit test can be seen below.


package com.gigantiq;

import jdepend.framework.DependencyConstraint;
import jdepend.framework.JDepend;
import jdepend.framework.JavaPackage;
import jdepend.framework.PackageFilter;
import static junit.framework.Assert.assertEquals;
import org.junit.Test;

import java.io.IOException;

/**
* Copyright Gigantiq Pty Ltd
*/
public class EnforcePackageDependenciesTest
{
@Test
public void testMatch() throws IOException
{
PackageFilter filter = new PackageFilter();
filter.addPackage(”java.*”);
filter.addPackage(”javax.*”);
JDepend jdepend = new JDepend(filter);

jdepend.addDirectory(”/Path/To/Classes/”);

DependencyConstraint constraint = new DependencyConstraint();
JavaPackage model = constraint.addPackage(”com.gigantiq.bedrock.model”);
JavaPackage ui = constraint.addPackage(”com.gigantiq.bedrock.ui”);
JavaPackage util = constraint.addPackage(”com.gigantiq.bedrock.util”);

ui.dependsUpon(model);
ui.dependsUpon(util);

model.dependsUpon(util);

jdepend.analyze();

assertEquals(”Dependency mismatch”, true, jdepend.dependencyMatch(constraint));
}
}
To implement such a unit test, the first step is to create an instance of JDepend. In our exmpale we inject the JDepend instance with a package filter to ensure the java.* and javax.* packages are ignored during the analysis.


PackageFilter filter = new PackageFilter();
filter.addPackage("java.*");
filter.addPackage("javax.*");
JDepend jdepend = new JDepend(filter);


Our dependencies are then coded into the unit test by setting up a DependencyConstraint defining the allowed dependencies between packages.


DependencyConstraint constraint = new DependencyConstraint();
JavaPackage model = constraint.addPackage("com.gigantiq.bedrock.model");
JavaPackage ui = constraint.addPackage("com.gigantiq.bedrock.ui");
JavaPackage util = constraint.addPackage("com.gigantiq.bedrock.util");

ui.dependsUpon(model);
ui.dependsUpon(util);
Once our dependencies are coded up into such a unit test, it is a simple manner to include the execution of this test into our build since it can be treated like any other JUnit test in our system. Adding any new code that violates the defined constraints will result in a failing unit test.

There a number of issues with this approach of enforcing package dependencies that I really do not like.

1. Enforcing the package dependencies is important enough that it should be treated as a seperate target with in the build. The danger of treating it as “just” another unit test is that we lose the sense of importance it should retain. Defining a seperate target in the build that just runs the JDepend unit tests would go a long way towards addressing this issue.
2. One of my driving forces behind enforcing package dependency, is that I can better understand the applications structure and thus be able to improve my ability to understand the impact that a code change is going to have on the rest of the system. I do not find JDepend’s approach of defining dependencies particularly easy to ready. A JDepend test for a complex applicaion with a lot of dependencies defined can become very difficult to read.
3. Error reporting is really poor. If my unit test fails, I get a message printed to the console that looks something like this… junit.framework.AssertionFailedError: Dependency mismatch expected:<true> but was:<false>. What dependency has been breached? I could structure my test in such a way that makes determining the cause of such errors much easier, but I would prefer a tool that just offered better reporting with out much effort.

So while JDepend will give me an approach for enforcing package dependencies with in my application, it is far from being ideal.

While a code base remains small with only a few smart individuals responsible for changes, it can be relatively easy to maintain the architectural qualities. A project does not need to grow by much before the maintainability, flexibility, and modularity of the system can become hard to retain.

The cohesive aspects of an application’s architecture tend to be reflected in its package structure. Analyzing and enforcing package dependencies can be a very useful technique to assist in maintaining the architectural traits. Understanding the package dependencies also assists with understanding the impact of code changes as they occur.

I am a big advocate for automating everything I possibly can. Ensuring code quality is no exception. Over the next few blog entries, I plan to discuss a number of approaches I have encountered for automating the enforcement package dependencies.

JDepend, Japan, and Macker are all tools that can be incorporated into an ant build and be used for enforcing package dependencies. Each of these tools have their pros and cons that I will discuss in detail over the next few postings.

Recently I was wanting to monitor some system statistics on my MacBook and came across a very cool widget called the iStat Pro widget by iSlayer.com. Over the last week or so I have had a number of people ask me about it and so figured I should share the details on my blog for those Mac users who are not already aware of it.

As the screen shot shows, it captures a lot of goodies such as CPU, Memory, uptime, temperature … etc.

Gigantiq are now hiring. We are looking for smart developers who live in Melbourne, Australia. If you are interested in being an integral member of the gigantiq team, check out our web site for further information (www.gigantiq.com).

Recently we spent a bit of time developing the Gigantiq web site. We plan that the content will change frequently and decided that we really need a reasonable Content Management System. Since our hosting company already had built-in support for Joomla which seemed to offer most of the features that we were looking for, it was the logical choice.

As far as a feature set goes, it has lived up to our expectations. In fact it can do a lot more than we actually need. Using an application that has more features than you are ever going to use is not normally a problem unless it means that the simple, common tasks become more difficult as a consequence. Joomla is a classic example of how some simple features in an application can become quite difficult to use as an application grows to be a generic “all things to everyone”.

It is a true art to be able to develop software that keeps the simple things simple and makes complex tasks simple. In most cases the simple things become complex and the complex tasks stay complex. This has certainly been my experience with Joomla.

I think that much of this complexity stems from the “you can do everything from our interface” mentality that many applications seem to adopt. More applications should offer alternative user interfaces to target different types of users. A better approach is to have a simple user interface that targets the 80% of users who will only use the most common features, but the ability to turn on a more advanced user interface to access the more esoteric features of an application. It would be better to offer wizards that make the more complex common tasks simpler.

Perhaps if Joomla had followed some of these ideas then it would not have taken me an hour or more to add my first menu item to the site.

Don’t get me wrong, I’m thankful that I have Joomla as a free CMS, I only wish it offered a simple approach to performing simple tasks. Feel free to bag us at Gigantiq if we forget this simple rule in our own software.

Gigantiq has finally arrived. After many months of hard work and speculation, and years of dreaming we are now in full operation.

The Gigantiq web site is now live and I would like to thank the efforts of Steinbach Oliver for developing a wonderful company logo. In the coming weeks and months the content of the site should grow grow rapidly as we expect Gigantiq to evolve quite quickly.

I know that for me personally begining Gigantiq is the start of something great. It fills me with a great amount of confidence that we will be successful when I mention my plans to my closest friends and collegues and the overwhelming response is one of surprise. Not because I am starting my own IT business, but because it took me so long to actually do it.

Andy.