It is an open source project. That means our mishaps are out there for everyone to see.  Read about our major release that contained a major problem. Hopefully you can learn from our mistake (and we get some of those users back).

2.1.0 Release not so Good

Architecture Rules 2.1.0 was released this past weekend. It was going great. The project was getting a lot of attention on dzone, freshmeat.net drove some good traffic, it made the front page of The Server Side’s news section. All of these sites brought in a huge 128 downloads over the weekend while the previous version was out for seven months and only claims 222 downloads (by the way, I hope there are many times more users using the maven repository, which we don’t yet track for downloads). So it was a good weekend. And then it was pointed out that wildcards don’t work…

What Happened?

We implemented wildcards a few weeks ago and released a 2.1.0-SNAPSHOT for users to test out. Unfortunately, we don’t have a huge number of early adopters who are pulling down snapshots. So It seemed worked well and we planned a release for the weekend of July 4th. On June 29th, I got a friendly email from Andrew Swan. He had graciously taken the time to review the 2.1.0 code before the release. He discovered that the JPackage equals method delegated the work to the JPackage matches method. This broke the contract of the Java equals method because, in his words, “if a.equals(b), then b.equals(a) should also be true.” We all know that he is absolutely 100% correct. He even pointed me to Effective Java. We were excited to have Andrew reviewing the code and of course wanted to fix this problem. So we modified each reference to JPackge.equals to use JPackage.matches, ran our tests, and got a green “tests pass 82 of 82″.

I quickly followed that up by creating the binaries, committing everything to SVN, updating the documentation, and promoting the 2.1.0 release. However, one reference to .equals remained in the AbstractRuleService. This is the service that itterates over each package defined in each rule and checks to see if a given package is dependent on a package that it is not allowed to depend on. So now, if a package is defined using wildcards, it tries to match “com.company.application.*”, the String, to fully qualified String such as “java.util”. Of course, no package is ever going to be named with an asterisk character, so now if a package is defined with a wildcard, its not looked at. So wildcards are busted.

What Now?

Now, we released 2.1.1 just to fix this bug and pray that the 128 (and hopefully many many more though the maven repository) java developers who are rightfully concerned with mitigating architectural risk take some time to come back and grab the 2.1.1 release.

We have fixed the problem and quickly put up 2.1.1. Please download it, or update your pom.xml, give us another try, and Assert your Architecture.

Architecture Rules announces today that version 2.1.0 is released.

This was a fun release for two reasons: the new features, and the timing of the release.

Features

This was a major release in that it finally allows the users to define packages with wildcards. We’ve had a handful of users asking for this functionality for a while. We thank them for sticking with us despite having to ask us for this feature a few times. Read about how we implemented wildcards, how to use them, and some open issues with them on our previous post Wildcard Support.

We added method chaining to the domain classes to improve the feel of programmatic configuration. We talk about this change when we introduced the development goals for 2.1.0 and we talked in depth about method chaining when we started researching weather we should support it or not in our post Configuration Method Chaining.

We also made some positive changes to the project’s exceptions. We have a lot of exceptions for reporting different issues with architecture rules configuration and with the project that the tool is inspecting. We added some references to the packages that cause the exception to be thrown, and we tied all of the exceptions together under one higher level exception, the ArchitectureRulesException.

Release Date

Architecture Rules 2.1.0 is officially released on Friday, July 4th, 2008. This is a great date for a milestone release not because it is an American national holiday, but because it is one year from the day that development started on the project just about to the day. The first release, 1.0, was made just a couple weeks after development started, on July 17th, 2007. So happy anniversary Architecture Rules. With wildcards, a new domain name, and the upcoming maven 2 plugin, this next year is going to be bigger than the last.

Upcoming Releases

There will be a 3.0.0 release soon. Today, the maven 2 plugin that has been in development and the architecture rules project have different package names. One com.seventytwomiles and one info.manandbytes because I developed most of the core project as 72miles.com and Mykola developed the plugin under his domain mandandbytes.info. Before I can see developers using the plugin, we need to normalize the domain names. We’ll purchase ArchitectureRules.org any day now, update the site, update the documentation, and update the packages. This will be a major change to the users, warranting the 3.0.0 release. If you can afford a couple bucks to help get the domain, we would really appreciate the monetary support.

Once the packages are straightened out, we can push out the plugin. We need to write the documentation for the maven 2 architecture rules plugin. Mykola has been working hard on the plugin for months now. Its actually been ready for public consumption for a while, we just haven’t had the time to document it for the public. I will make this my next task and get the plugin out for everyone to start using. It makes Architecture Rules even easier to use by allowing the user to skip writing a silly little Test class and lets you move Architecture Rules right into your everyday build process. Awesome.

2.1.0

For a complete list of the changes, check out the 2.1.0 release/download page. You can get the update by downloading the new jar, or by updating your pom.xml to version 2.1.0.

Architecture Rules is proud to announce that it now support wild cards.

Benefits of Wildcards

Wildcards bring the ability to match multiple packages with one Rule entry. This falls inline with the original goal of the project, which was to simplify the usage of jDepend and to define rules in a way that is very readable, understandable, and modifiable.

With wildcards, users can now define a package or violation in one line with the ability to match many packages. This means you won’t need to update your Rules each time you add a new package and your XML configuration file will be much shorter.

Wildcard Patterns

We identified a few different Wildcard Patterns. Some we don’t support and don’t plan on supporting, others we do support, and there are still a couple that we want to add.

Here is a description of what we now support:

Example

Now creating a rule to assert that the web layer does not interact with the DAO (or integration) layer is as easy as:

<rule id="web-layer">
<comment>web and dao mix like oil and water</comment>
<packages>
<package>com.company.app.web..*</package>
</packages>
<violations>
<violation>com.company.app.dao..*</violation>
</violations>
</rule>

Prior to wildcards, you might have needed to define ..web.controllers, ..web.filters, ..web.views, ..web.forms, ..web.tags as the packages, and then you would have had to defined every ..dao package as a violation. Now its easy!

Implementation

Architecture Rules uses Regular Expressions to compare the packages with wildcards against the inspected packages. The regular expression needed to be able to handle exact packages, one package deep, and one or more packages deep. We accomplished this by modifying the given package with wildcards (such as com.company.project.*) to apply regular expression characters.

Thank you to Ryan Stewart for helping us hash out this expression. This is what we came up with:

final String regex = this.path
// foo.bar exactly foo.bar
.replaceAll("\\.", "\\\\.")
// foo.bar.1 or foo.bar.1.2 and so on...
.replaceAll("\\\\.\\\\.\\\\*", "\\\\.\\[A-Za-z_0-9.]")
// packages only
.replaceAll("\\.\\*", "\\.[A-Za-z_0-9]*");

The break down is this: The third line of code looks for ..* combination and replaces it with the regular expression to allow for any string with any number of periods.

The fourth line of code looks for the remaining .* combinations and replaces it the an expression to match package name but no more periods.

If you consider yourself a regular expression wizard, please consider taking a moment to review this and offer any feedback or suggestions that you might come up with. Thank you.

Outstanding Issues

One usability issue that we have uncovered is the matching of the package prior to the wildcard. For example, some users think that com.company.project.* should match com.company.project in addition to the packages under project. Others aren’t sure it should match ..project. As of right now ..project is not included as a match. We are open to comments on this and welcome feedback from the early adopters.

Roll Out

Wildcard support has been slated for the 2.1.0 release which should happen any day now. We are just waiting for a couple of our early adopters to test the wildcards with the 2.1.0-SNAPSHOT that is currently in the maven repository.

If you’ve been waiting and can’t wait to try it out, or if you can help out with testing, just grab the jar, or add our repository and dependency to your maven pom.xml.

Thanks

Finally. Thanks you to Andrew Swan for hounding us to get this feature implemented and for sticking with us while we worked on it. Also thank you for testing it for us. Thank you, again, to Ryan Stewart for helping out with the regular expression. And as always, thank you to Mykola Nickishov for working diligently on the Maven 2 plugin that will be released with the 2.1.0 release of Architecture Rules.

And thank you to you for reading this far. Now go get Architecture Rules and start Asserting Your Architecture!