While adding support for YAML configuration files I introduced a cyclic dependency (shame on me) in our code base. If this means nothing to you there are some reasons why introducing cycles considered as a bad practice.

How to catch problems like this one?

Your project’s build system must be ready for this. Integrate tools like Architecture Rules or any other alternative tool into your Maven, Ant or whatever build system of your choice.

Build your projects and run tests against them continuously, with Hudson, CruiseControl or TeamCity

Sounds obviously for you? For sure.

As the problem popped up as soon as it was introduced, fixing it was a trivial task. I absolutely agree with a statement that every piece of code becomes “legacy” few hours after it’s written. Distributed development teams make such things even worse. `Individuals and interactions over processes and tools’ don’t work.

How did I discovered this? First of all, this post is about eating your own dog food, right? One of the purposes of Architecture Rules is to report on cyclic dependencies among your project’s packages and classes. And my build system was ready to catch this with just running mvn test.

How this looks like? As a plain old unit test’s failure:

Results :

Tests in error:
    testArchitecture(org.architecturerules.SimpleArchitectureTest)

Tests run: 99, Failures: 0, Errors: 1, Skipped: 0

In my case more details are in the target/surefire-reports

org.architecturerules.SimpleArchitectureTest.txt:

-------------------------------------------------------------------------------
Test set: org.architecturerules.SimpleArchitectureTest
-------------------------------------------------------------------------------
Tests run: 1, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 0.54 sec <<< FAILURE!
testArchitecture(org.architecturerules.SimpleArchitectureTest)  Time elapsed: 0.532 sec  <<< ERROR!
org.architecturerules.exceptions.CyclicRedundancyException: 2 cyclic dependencies found:

	-- org.architecturerules.configuration.xml depends on
	|  |
	|  |-- org.architecturerules.configuration
	|	 |-- @ org.architecturerules.configuration.xml.DigesterConfigurationFactory
	|	    \ while
	|	     |-- org.architecturerules.configuration.DefaultConfigurationFactory
	|	       \ depends on org.architecturerules.configuration.xml
	|
	-- org.architecturerules.configuration depends on
	|  |
	|  |-- org.architecturerules.configuration.xml
	|	 |-- @ org.architecturerules.configuration.DefaultConfigurationFactory
	|	    \ while
	|	     |-- org.architecturerules.configuration.xml.DigesterConfigurationFactory
	|	       \ depends on org.architecturerules.configuration
	|

	at org.architecturerules.services.CyclicRedundancyServiceImpl.buildCyclicRedundancyException(CyclicRedundancyServiceImpl.java:162)
	at org.architecturerules.services.CyclicRedundancyServiceImpl.performCyclicRedundancyCheck(CyclicRedundancyServiceImpl.java:117)
	at org.architecturerules.AbstractArchitectureRulesConfigurationTest.doTests(AbstractArchitectureRulesConfigurationTest.java:143)
	at org.architecturerules.SimpleArchitectureTest.testArchitecture(SimpleArchitectureTest.java:51)

Thanks to our Maven 2 plugin your build will fail too as soon as you introduce cycles in a dependency graph. Even if your project uses Apache Ant (sorry, it’s not my favorite tool) as a build system, you can download and use our Ant task to get the same result.

How-to setup Ant task? Sorry, it’s still not available and I have any clue. In a response to this post Mike provided this great how-to install and configure guide. Thank you, Mike!

Related Posts

• Hudson

© MykolaNikishov for Architecture Rules - Blog, 2009. | Permalink | No comment | Add to del.icio.us
Post tags: continuous integration, cyclic dependency, maven

Feed enhanced by Better Feed from Ozh

Have a look, then I will identify each section of it and mention why its been designed the way it was.

The XML

<architecture>
  <rules>
    <rule id="dao_layer_rule">
      <comment>dao layer may not access service or web layers</comment>
      <packages>
        <package>com.company.project.dao</package>
        <package>com.company.project.dao..*</package>
      <packages>
      <violations>
        <package>com.company.project.service</package>
        <package>com.company.project.service..*</package>
        <package>com.company.project.web</package>
        <package>com.company.project.web..*</package>
      </violations>
    </rule>
  </rules>
  <analysis>
    <packages>
      <package package="com.company.project.dao.hibernate.person">
        <matches>
          <rule>dao_layer_rule</rule>
        </matches>
        <dependencies>
          <package>com.company.project.dao</package>
          <package>com.company.project.dao.hibernate</package>
          <package>com.company.project.service</package>
        </dependencies>
        <violations>
          <violation violates="dao_layer_rule">com.company.project.service</violation>
        </violations>
        <cycles>
          <cycle>com.company.project.service</cycle>
        </cycles>
        <classes>
          <class class="HibernatePersonDAOImpl">
            <dependencies>
              <package package="com.company.project.dao">
                <classes>
                  <class>PersonDAO</class>
                </classes>
              </package>
              <package package="com.company.project.dao.hibernate.person">
              	<classes>
                  <class>AbstractHibernateDAO</class>
                </classes>
              </package>
              <package package="com.company.project.service">
                <classes>
                  <class>PersonService</class>
                </classes>
              </package>
            </dependencies>
            <violations>
              <package package="com.company.project.service">
                <classes>
                  <class>PersonService</class>
                </classes>
              </package>
            </violations>
            <cycles>
              <package package="com.company.project.service">
                <classes>
                  <class>PersonService</class>
                </classes>
              </package>
            </cycles>
          </class>
        </classes>
      </package>
    </packages>
  </analysis>
</architecture>

Explanation

There are two major parts to the report. The first is the rules elements. The second is the analysis elements.

The rules elements simply regurgitate the user’s rules as the user defined them. Architecture Rules is hopefully going to provide so much useful information someday that users would potentially not even define any rules and just use Architecture Rules to detect cyclic dependencies, get reports on their architecture including class and package dependencies, and someday Design Structure Matrix analysis. But for now I believe most of our users utilize rules, since that is what this project is currently designed to do.

The second element is the analysis element. This is were we will put everything that we discover about every package and class in the analyzed code base. Lets look at each element under the analysis element individually.

<analysis> Elements

For each package in the project that we analyze, we will output:

Rules

Each rule that was matched. This indicates which rules were matched based on the exact package names and wildcarded package names that you have defined in your architecture-rules.xml

Dependencies

Lists every package that the package under investigation depends on, including packages that are defined as a violation and packages that are involved in a cyclical dependency.

Violations

Lists packages that are defined as violations.

Cycles

The packages that are involved in a cyclical dependency with the package under investigation.

Classes

Now that we have listed dependencies at the package level, we are going to have an in depth look at each class within that package.  So the package level analysis is a sort of summary of the information found at the class level.

For each and every class in the package under investigation we’ll output the class’s dependencies, the violations (as determined by the matched rules and that rule’s violations as described in architecture-rules.xml) and each class that is involved in a cyclical dependency with the class under investigation.

We would appreciate any feedback that you might have on this output. It might take a while to read and really digest all of the information that this report contains within it, but the sooner we get this prototype reviewed the sooner we can implement it, and the better the review is, the better the chances that we get it right the first time.

Look for a subset of this report in the 3.0 release. We won’t be able to output this entire report until we replace JDepend with a new analysis tool, or write our own.

Related Posts

• Sonar

© MikeNereson for Architecture Rules - Blog, 2009. | Permalink | No comment | Add to del.icio.us
Post tags: integration, report, xml

Feed enhanced by Better Feed from Ozh

Here are some links:

Architecture Rules on Hudson
http://ci.sonar.codehaus.org/job/Architecture rules/

Build Status RSS
http://ci.sonar.codehaus.org/job/Architecture rules/rssAll

Modules
http://ci.sonar.codehaus.org/job/Architecture rules/modules

Related Posts

• Architecture Rules eats his own Dog Food
• Sonar

© MikeNereson for Architecture Rules - Blog, 2009. | Permalink | No comment | Add to del.icio.us
Post tags: continuous integration, hudson, sonar

Feed enhanced by Better Feed from Ozh

While investigating back links to our websites, I discovered an issue in Sonar’s issue tracker where they were discussing finding a tool that could analyze architecture so that they can add additional reporting to Sonar. This issue brought me to the source of the issue. I added my input to that issue. It turns out that they would prefer to utilize a project like ours more than the alternatives because our project is the most active. The alternatives have not been updated in years. Sonar also really wants to add DSM analysis reporting to their product, so they are looking for an architecture analysis tool to handle this.

We are discussing with the Sonar project team how we might fill this role.

Related Posts

• XML Report Prototype
• Hudson

© MikeNereson for Architecture Rules - Blog, 2009. | Permalink | No comment | Add to del.icio.us
Post tags: integration, sonar

Feed enhanced by Better Feed from Ozh

org.architecturerules

First. The big change is the groupId which is finally going to be moved to org.architecturerules for the core project and the maven plugin. I don’t have the domain yet. I have a fund raiser page where I was hoping to get about $30 to secure the domain for 3 years. So far no contributions : \ Maybe if any of your work for a company that uses the project, and the company has donated money in the past, you could ask your boss for a small $30 contribution to this project. Regardless, we’ll get it eventually and the project needs to get off of com.* and the maven plugin needs to be the same groupId.

architecture-rules-ant

We are going to refactor the ..architecturerules.ant package to its own jar so that:

• User’s who want to use the ant interface can include this jar.
• By including the jar, you get the Ant jars and dependencies. If you don’t use Ant, you don’t need the jar or the ant libraries.
• As we add new functionality to architecture rules someone else could take on the task of keeping the ant task up to date on their own schedule.
• This module also acts as an example of how to extend the core – add your own functionality!
• Allows us to develop new ant features and fix ant issues without doing a major release of the core. There are a couple of open ant-related issues in the issue list.

The downsides is that the API is broken, but we are willing to accept this given that this release the packages are all changing to org.architecturerules so the API will be broken anyway.

Issue 59: DependencyConstraintException should report the violating class

This is sort of a tough issue. We utilize jDepend which only looks at packages. However, Mykola brought Classycle to my attention (which I included on the alternatives page) which looks at class dependencies rather than package dependencies. We could move off of jDepend and switch over to using Classclye to find dependencies, or we could continue to use jDpend, and when a rule is broken, we can jump over to Classycle to figure out which class is breaking the rule. Another benefit to Classclye is that it is able to detect static dependencies which jDpend is not. I actually got an email from SonarJ, a commercial competitor listed on the alternatives page who congratulated us on developing a good open source architecture risk mitigating project but pointed out that jDepend could not detect static dependencies. I think in the long term we need to support detecting static dependencies so this Classycle might have been an important find.

Looking to get involved? We’re looking for contributors for this task. Welcome to the team, Raja.

Issue 60: XML reports

The only other current issue that I would like to tackle somehow is the output of the XML reports. I sent out a pretty detailed email on this to the user and dev mailing list. I got little response. I put a copy of the email in the issue which includes a prototype for the XML output. The premise would be that the execution of architecture rules results in the output of an XML file that describes all of the rules, the packages that were investigated because of that rule, the dependencies of each package that match that rule, and a list of each violation. One major change would be that instead of throwing an exception when a rule is broken, the rest of the packages would be investigated first and then the XML output is written, and then an exception could be thrown describing all of the rules that were broken – not just the first rule.

The reason for this XML output is two-fold: first, it provides output for other developers to start processing and developing new tools for which could be good for this project. second: it provides a data source for our maven 2 plugin to use to generate a site report for. Or this could be a new project: maven-architecture-rules-report-plugin. Either way, this is a good stepping stone to new functionality and growth for this project.

Looking to get involved? We’re looking for contributors for this task. Welcome to the team, Chris.

FindBugs

We added the FindBugs report recently to the maven-generated site. We should be able to clear this list for all of our code.

Remove 3rd party org packages

I had created an Issue to remove unnecessary dependencies to cut down on the number of libraries that we depended on. But I think this was implemented poorly to the point where it caused a reported bug. Also, we have a pseudo maven repository so that makes this issue almost moot.

This list encompasses most of the open issues in the issue tracker that I want to see implemented. There are a couple of issues that I am going to leave on hold (such as inverting the project to expect the user to define the accepted packages rather than the exceptional packages) and some that I can not fix with out money (continuous integration server).

All of these tasks are up for discussion. And most any of them are open to user contributions. If you are interested in taking on one of these tasks, just reply to this email, tell us what you want to work on, what questions you have, and maybe describe how you plan on implementing it. If its a small task, you can submit a patch, if its bigger, we can make you a contributor (for a short term or longer term depending on circumstances)

UPDATE: Issue 68: Listener Support

Adding support for event listeners gives us a few different things that we either need or that would benefit us in the future. This will hopefully invite other developers to begin extending the project. For example someone someday might make a GUI tool or an IDE plugin and want to provide real-time feedback to the GUI as packages are investigated. This also enables us to develop the XML report in a very modular fashion, without littering the services with code that is not related to performing the service that the class is named for. Listeners provide a great point for adding new functionality from too.

UPDATE: Introduce API Package

Interfaces will be moved to a new org.architecturerules.api package so that developers who wish to extend the project have someplace to start from. This will break backwards compatibility. But so will migrating to org.architecturerules, so if this is going to be done, it should be done now. Sorry everyone.

UPDATE: Issue 64: default-architecture-rules.xml

The initial state of the Configuration entity will be created by reading default-architecture-rules.xml. This essentially just allows us to define the default values via XML rather than defining them with java constants which is what we are doing now. This XML file is easier for the user to read to figure out the default values, is easy to add new default values to as we develop new features, and may be used to demonstrate a sample XML configuration or how features are configured.

UPDATE: Issue 67: Configuration Properties

The listeners require some configuration. Some other tools that have yet to be written may also require configuration. We’ll be adding support for arbitrary properties. These allow you to define a set of keys and a values that can be handed off to the Listeners and to other features that may be created in the future. This provides a pretty robust mechanism for providing configuration values for classes that extend the project.

Related Posts

• Configuration Method Chaining
• Squash those Cycles
• Wildcard Support

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | No comment | Add to del.icio.us
Post tags: 3.0, roadmap

Feed enhanced by Better Feed from Ozh

I read one description which concerned me. Chris suggested in his description that architecture rules as “way to ‘test architecture’, although it seems to be limited to detecting cyclic package dependencies”. Whoa, hold on. That’s not what we are about. Detecting cyclical dependencies is something that we can do, because we wrap JDepend, but the whole point of the project is to assert that the Rules that you have defined are not violated.

So, I tracked down Chris’s email address, which I found in his resume, which I found on his site. I emailed him.

I started by apologizing for the unsolicited email. Next I explained that I found his comment delicious, I reiterated his comment to him, then briefly explained and showed (with XML) how architecture rules was about asserting architecture through the definition of rules. I sent off the email assuming that Chris probably wouldn’t read it, and certainly wouldn’t respond favorably. Fortunately, I underestimated Chris.

Chris wrote back to me and thanked me for taking the time to write to him. He also pointed out that it is “always a good sign to me when an open-source project is interested in what people are saying about it.”

I just wanted to share this experience. I have no great analysis of it yet. I hope that it might encourage you to think about reaching out to your user base weather they be paying customers or users of your open source tool. After all, that’s why we write the code, right? To satisfy the end users, to make their jobs easier, or to change the way that people do business.

Related Posts

• Architecture-Rules 2.1.0 on the Horizon
• Architecture Rules eats his own Dog Food
• XML Report Prototype

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | 2 comments | Add to del.icio.us
Post tags: buzz, del.icio.us

Feed enhanced by Better Feed from Ozh

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.

Related Posts

• Architecture-Rules 2.1.0 on the Horizon
• Architecture-Rules 2.1.0 Release
• Wildcard Support

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | No comment | Add to del.icio.us
Post tags: 2.1.1, release, retrospective

Feed enhanced by Better Feed from Ozh

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.

Related Posts

• Architecture-Rules 2.1.1 Release
• Architecture-Rules 2.1.0 on the Horizon
• Architecture-Rules 2.0.3

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | No comment | Add to del.icio.us
Post tags: 2.1.0, release

Feed enhanced by Better Feed from Ozh

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!

Related Posts

• Architecture-Rules 2.1.1 Release
• Architecture-Rules 2.1.0 on the Horizon

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | No comment | Add to del.icio.us
Post tags: 2.1.1, feature, wildcard

Feed enhanced by Better Feed from Ozh

The first part, Architecture Rules 101 went over a short, sweet, and simple configuration.

Reminder

So remember, the basics of Architecture Rules is that it is

• Java.
• Open Source.
• Asserts architectural rules via unit tests.
• You write your rules in XML.
• Your run your tests with junit, ant, or a continuous integration server.

Source Locations

In this second installment of introductions to Architecture Rules, we’re going to go over source locations which enables the tool to support multi-module projects, and allows you to define when a particular source must exist, or may be optional.

By allowing a source to be optional, you can have different developers with different modules of code. So while one developer may have all eight modules of a project, another developer may only need to work on two or three of the modules.

Configuration

Here is an example that uses all of the current features supported by Architecture Rules 2.0.3.

<configuration>

<sources no-packages="exception">
<source not-found="exception">coretargetclasses</source>
<source not-found="ignore">webtargetclasses</source>
<source not-found="ignore">wstargetclasses</source>
</sources>

</configuration>

The first property that we see is the sources no-packages="exception". This tells Architecture Rule that, after reading all of the defined source directories, if no classes are found, then throw an Exception, more specifically, a NoPackagesFoundException. Here are the configuration options for no-packages:

The next interesting thing that we come across is <source not-found="ignore"> This configuration causes a SourceNotFoundException when the given path can not be found on the file system. This allows you to ensure that specific modules are present in the test. Alternatively, if you don’t particularly care if some source path is present, you can use the ignore value, which happens to be the default value. In the example above, the core module must be present for the tests to continue. The web and web services (ws) modules are optional.

So, after showing the simplistic configuration in Architecture Rules 101, we have now shown how you can customize your configuration to fit your needs with little work.

In the next Architecture Rules lesson, we’ll demonstrate how to get the Configuration and show how easy it is to provide programmatic configuration instead of or in addition to the XML configuration. Also coming up right after that, we’ll finally introduce the Maven 2 Architecture Rules plugin that Mykola has been working on for the past couple of months.

Related Posts

• Architecture Rules Tutorial: 101

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | One comment | Add to del.icio.us
Post tags: tutorial

Feed enhanced by Better Feed from Ozh

Core data

Exceptions are comprised of some sort of primary data, for example, the name or type of Exception, and maybe the exception’s message. Take, for example, a ConnectionTimeoutException.

You, as a developer, have a pretty good idea as to what is going on when you see this at the top of the stack trace. You may be able to read the message, if the developer provided one, and get a little more information about the exception.

/**
* Signals that a timeout occurred while opening the socket.
*/
public class ConnectionTimeoutException extends IOException {

/** Create an instance */
public ConnectionTimeoutException(String message) {
super(message);
}

}

Default Metadata

If you read a stack trace or hack the exception’s API, you can even get some more information about the it. Such as the Class that threw the Exception, or the line number where the Exception occurred. You might be able to review the hierarchy of the class to garner some information. For example, this ConnectionTimeoutException extends from IOException. That tells you something.

The Problem

The problem with this type of Exception is that someone, like a developer, needs to review this information in order to track down the cause of the issue. That means locating the stack trace, and determining the parameters and other configurations that were present at the time of the Exception.

Java, however, and most any other language, provide a means for supplying pertinent metadata when an Exception occurs. They are called properties, getters and setters, or mutators. You, as the designer, just need to include those properties when you design the class.

Example

Consider the ConnectionTimeoutException. Wouldn’t it be nice to know the source and destination URIs of the connection? And what the timeout value was?

/**
* Signals that a timeout occurred while opening the socket.
*/
public class ConnectionTimeoutException extends IOException {

private long timeout;
private String source;
private String destination;

/** Create an instance */
public ConnectionTimeoutException(long timeout, String source, String destination) {

super("failed to connect to " + destination + " within alloted " + timeout + "ms");

this.timeout = timeout;
this.source = source;
this.destination = destination;
}

public long getTimeout();
public String getSource();
public String getDestination();
}

Would you agree that the Exception that knows the timeout value and destination URI is more valuable to you, the developer, than some Exception with an arbitrary message that the designer may or may not have populated with relevant information?

Benefits

The resulting Exception implementation provides a constructor requiring specific values. The developer who consumes this Exception no longer needs to come up with some arbitrary message. He or she just needs to provide the requested parameters, which is known or can be read from some HttpClient implementation.

The developer who is catching and dealing with this ConnectionTimeoutException now has a few more options. Perhaps an error message will be displayed. The developer can write a custom message and use the timeout property to notify the end user what the timeout was. The developer doesn’t need to parse it from a String message property.

If the code throwing the ConnectionTimeoutException is a framework to be used by other developers, the developer has a lot more options to handle this Exception. Perhaps they are writing a GUI for your tool and can now provide their end users with more information.

Metadata in the Real World

I decided to write about this topic after a user of our Architecture Rules (Assert your Architecture!) open source software asked us to enhance our Exception APIs.

Our CyclicRedundancyException simply contained a message that described a package by its name, and then listed all of the packages involved in a cyclic dependency with said package.

...architecturerules.exceptions.CyclicRedundancyException:
cyclic dependencies found:

-- test.com.seventytwomiles.services
|  |
|  |-- test.com.seventytwomiles.model
|  |
|  |-- test.com.seventytwomiles.dao.hibernate
|
|
-- test.com.seventytwomiles.model
|  |
|  |-- test.com.seventytwomiles.services
|
|
-- test.com.seventytwomiles.dao.hibernate
|
|-- test.com.seventytwomiles.services

steven.devijver asked that we provide an API to retrieve a List of the packages involved in the cycle. This way Steven can construct his own message, or wrap the data in his own domain Exception, or whatever else he had in mind. We accommodated him by providing a Map containing a key (package name) and value (List of package names involved in a cyclic dependency) pair. This should be useful when we go to write the Maven 2 plugin report for this tool.

As another example, we inherited a DataFinderException in another project we’re working on. The only constructor for this Exception was a String named message. We introduced a new constructor and two properties — name and value — and getters for each. Now, the code that constructs DataFinderExceptions no longer needs to build some complex message with a StringBuffer before throwing the Exception.

StringBuffer message = new StringBuffer();
message.append("Could not find entity with");
message.append("userId");
message.append(" = ");
message.append(userId);

throw new DataFinderException(message.toString());

became

throw new DataFinderException("userId", userId);

A cleaner execution, fewer lines of code, and useful metadata that can be passed on to the end user, logged, or handled eloquently.

How do you design your Exceptions to provide useful metadata? Can you think of any Exception in the JDK that provide such metadata?

Related Posts

• Wildcard Support
• On del.icio.us
• Hudson

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | One comment | Add to del.icio.us
Post tags: exceptions

Feed enhanced by Better Feed from Ozh

Cyclic dependencies hurt a software system’s goals:

• Understandability Understandable software is critical in managing complex systems. Software that is easily understood acts like a bridge between the problem and its solution.
• Flexibility
• Modularity An approach to developing software that breaks projects into smaller units designed so that they can work with other sections of the program. Modifying the way that modules work will have no adverse affects on the other components of a program

• Modifiability Modifiability is controlled change to the system in which some parts are altered without increasing the complexity or obscuring the logic of the original structure.
• Reliability Reliability is the extent to which a software yields consistent, stable, and uniform without any human intervention and is crucial for any software system that must operate for long periods.
• Maintainability The ease with which a software system can be modified to change or add capabilities, improve performance, or correct defects.

• Testability The degree to which a system or component facilitates the establishment of test criteria and the performance of tests to determine whether those criteria have been met.
• Reusability
• Clarity

By using Architecture Rules to Assert your Architecture, you are taking the first step in developing a strong architecture by actively managing package relationships.

Aside from the adverse affects on the software development goals, cyclic dependencies create these negative consequences for the system:

• Diminish the ability to determine a package’s purpose.
• Changes impact seemingly unrelated components of the architecture.
• Separation of layers.
• Packages cooperating in a cycle must be released as an atomic unit.

Determine a Package’s Purpose

When future developers come along to maintain the software the presence of cycles can diminish the ability for that developer to determine a package’s purpose. This hurts the software’s clarity and understandability. The end result will be the introduction of bugs, or an increase in the amount of time required to modify the software.

Changes Impact Unrelated Components

When a class involved in a cycle is modified, it could change the bahavior of the other class involved in the cycle. This makes it difficult to accurately assess and manage the impact of changes to the system. This directly hinders the modifiability of your software. Reliability is also attacked since changing the behavior of an unrelated class could introduce a bug.

Affecting other components also introduces a maintenance and testing issue, since you can’t do anything to either class without possibly affecting the other. A situation exists where class A needs to compile against class B, but class B needs to compile against class A.

Separation of Layers

Most architectural approaches recognize the advantages of layered architectures. For example, if you develop a presentation layer, a business or logic layer, and a database access layer, you are able to swap out one implementation of a layer for another. Such as replacing a JDBC data access layer with one that utilizes Hibernate, or a JSP presentation layer for a Flash or PHP presentation layer.

Cyclic dependencies across layers couple the layers, defeating the purpose of layering. If a cycle exists between the service layer and the data access layer, then those two layers are no longer interchangeable. Thus, modifiability of the software is lowered. The layers are no longer encapsulated.

Packages Must be Released as an Atomic Unit

The Spring Framework is inspiring when it comes to its modular design. The Spring Framework can be considered as a collection of smaller frameworks. Most of these frameworks are designed to work independently of each other yet provide better functionalitys when used together.

This modularity by design, allows the Spring Framework to released as a full framework (spring.jar) or modularly, so that the users can use the features that they are interested, and nothing more (spring-core, spring-ldap, spring-orm, spring-aop, spring-beans, spring-mock, and on and on…). See all of the modules here.

When cyclic dependencies exist, your ability to make and release independent modules is removed. Packages that may not be related must be released as a single jar, or module.

ArchitectureRules wraps JDepend, a java library which is able to identify these cyclic dependencies. Upon detecting a cyclic dependency, a CyclicDependencyException is thrown, a RuntimeException whose message notifies you of which packages are involved in a cyclic dependency:

...architecturerules.exceptions.CyclicRedundancyException:

cyclic dependencies found:
-- test.com.seventytwomiles.services
| |
| |-- test.com.seventytwomiles.dao.hibernate
|
-- test.com.seventytwomiles.dao.hibernate
|
|-- test.com.seventytwomiles.services

When are Cycles Acceptable

Generally speaking, cycles are most always accepted when in the same package. For example two domain objects in the same package, such as User and Account. A User has Accounts, and an Account has a User. Since these two classes are in the same package, the package remains encapsulated.

Related Posts

• Wildcard Support
• 3.0 Roadmap
• Hudson

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | 2 comments | Add to del.icio.us
Post tags:

Feed enhanced by Better Feed from Ozh

Now, the whole reason for these artifacts is to draw those two pass by my desk into a conversation – this offers a break in the day and a chance to get to know the people around me better.

The fish tank has been very popular, a lot of people can relate, or have a story, or just like to look at the fish. Gumby is a lot of fun. Its fun to see those who recognizes him, and those who don’t even know who Gumby is. I wanna order a couple of Blockhead figures to go along side him.

So the new one is the Architecture Rules mug that I designed and put up on CafePress. This has been a great way for me to get the people around me to talk about software, and specifically, about software architecture. I highly recommend that, if you use Architecture Rules, you pick up one of these mugs, put it on your desk, and start telling the world that you are actively mitigating architecture risk everyday. Hey, that’s something you, your coworkers, your customers, and your bosses can get behind.

Or, if you’re just looking for a new trinket to put on your desk, this mug is a lot cheaper and easier to maintain than a fish tank is. I have personally tested the mug and had successfully results with coffee, water, various teas, apple cider, and soup.

I have to be honest, the price that CafePress charges, of $13.99, is rather steep for a mug, but it is a tall mug with a capacity of 15 oz., and a buck or so goes to supporting Architecture Rules. Right now we are trying to raise funds to snag the domain architecturerules.com. Your purchase would go a long way in helping to secure that domain.

Here you can check out the upclose graphic. And if you can’t afford the mug, but you wanna help us get the domain or help us towards our current fund raising goal, you might be able to donate some change to the project.

So, what toys do you keep on your desk? What are the best conversation starters? Do you keep any trinkets branded with a tool or technology (my pen branded with Sun Java)?

Related Posts

• Configuration Method Chaining
• Architecture Rules Tutorial: 101
• Architecture Rules eats his own Dog Food

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | No comment | Add to del.icio.us
Post tags:

Feed enhanced by Better Feed from Ozh

What is it

Method chaining is a programming technique that is supported by many public interfaces. It allows the programmer to call one method from – directly after – another. For example, in Java:

Event event = new Event()
.setDescription("")
.setStartDate(start)
.setEndDate(end)
.setPrivate(true);

Event event = new Event();
event.setDescription("");
event.setStartDate(start);
event.setEndDate(end);
event.setPrivate(true);

Configuration configuration = new Configuration()
.addClass(org.hibernate.Item.class)
.addClass(org.hibernate.Bid.class)
.setProperty("...dialect", "...MySQLInnoDBDialect")
.setProperty("...connection.datasource", "java:jdbc/test")
.setProperty("...order_updates", "true");

class Event {

public Event setDescription(String description) {
this.description = description;
return this;
}

public Event create() {
... something complicated ...
return this;
}
}

Event event = new Event()
.setDescription("").setStartDate(start).setEndDate(end);

int eventId = new Event()
.setDescription("")
.setStartDate(start)
.setEndDate(end)
.setPrivate(true)
.insert()
.getId();

List cats = session.createCriteria(Cat.class)
.add( Restrictions.like("name", "Fritz%") )
.add( Restrictions.between("age", minAge, maxAge) )
.list();

boolean valid = validator(value)
.isGreaterThan(0)
.isLessThan(10)
.isCurrancy();

Related Posts

• Architecture Rules Tutorial: 101
• XML Report Prototype
• Hudson

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | 2 comments | Add to del.icio.us
Post tags: configuration

Feed enhanced by Better Feed from Ozh

The Basics

• Java.
• Open Source.
• Asserts architectural rules via unit tests.
• Write your rules in XML.
• Run your tests with junit, ant, or a continuous integration server.

Your Rules

You define your rules. For example, if you are developing n-tiered software, you probably have three layers. A DAO/integration layer, a service/business layer, and a presentation layer. Generally, the presentation layer does not interact directly with the integration layer. You could describe this rule as: com.company.project.presentation can not depend on the com.company.project.integration package. Its that easy.

The XML

The XML is in architecture-rules.xml and contains two section: <configuration> and <rules>. Configuration describes where your files are, and the rules simply describe a package, and one or more packages that it can not depend on.

<architecture>

<configuration>
<sources>
<source>targetclasses</source>
</sources>
</configuration>

<rules>

<rule id="dao">
<packages>
<package>
com.company.project.presentation
</package>
</packages>
<violations>
<violation>
com.company.project.integration
</violation>
</violations>
</rule>

</rules>

</architecture>

Thats it. You have a simple architecture-rules.xml.

The Unit Test

Just extend and run your tests.

public class SimpleArchitectureTest
extends AbstractArchitectureRulesConfigurationTest {

public String getConfigurationFileName() {
return "architecture-rules.xml";
}

public void testArchitecture() {
assertTrue(doTests());
}
}

More Features

In Architecture Rules 201, we’ll show you how to check for cycles (cyclic dependencies), write more action-packed rules, and describe how to handle source paths that can’t be found. We can also take a gander at the various Exceptions that can be thrown when rules are broken.

Go Get It

The next thing to do, is to go get it and try it out. Download, svn checkout, or put it in your pom.xml. Just add this repository:

<repository>
<id>architect-rules-repo</id>
<name>
architecture-rules hosted by code.google.com
</name>
<layout>default</layout>
<url>

http://architecturerules.googlecode.com/svn/maven2/

</url>
<releases>
<checksumPolicy>ignore</checksumPolicy>
</releases>
<snapshots>
<checksumPolicy>ignore</checksumPolicy>
</snapshots>
</repository>

And this dependency:

<dependency>
<groupId>com.seventytwomiles</groupId>
<artifactId>architecture-rules</artifactId>
<version>2.0.3</version>
</dependency>

Related Posts

• Architecture Rules Tutorial: 102

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | 2 comments | Add to del.icio.us
Post tags: tutorial

Feed enhanced by Better Feed from Ozh

Maven Plugin

Mykola has been working hard on the maven-architecture-rules-plugin. With it, you will no longer even need to write a unit test. Just write your architecture-rules.xml, and attach the appropriate goal to Maven’s test phase. He has been tackling multi project projects recently. This is sure to make asserting your architecture even easier for Maven users.

Maven repository

Speaking of Maven users, development of Architecture Rules relies on Maven. Today, to use Architecture Rules, you’d have to download the Architecture Rules jar and put it on your own repository, or your lib directory. This is too much work and we shouldn’t expect you to have to do that. We are going to get the jars and sources up into a Google Code hosted repository so you can just declare the dependency and repository in your pom.xml and get started even faster. In fact, we already have it up, its just not documented yet. Here is the first public mention of it.

Just add this repository:

<repository>
<id>architect-rules-repo</id>
<name>architecture-rules repository</name>
<layout>default</layout>
<url>http://architecturerules.googlecode.com/svn/maven2</url>
<releases>
<checksumPolicy>ignore</checksumPolicy>
</releases>
<snapshots>
<checksumPolicy>ignore</checksumPolicy>
</snapshots>
</repository>

And this dependency:

<groupId>com.seventytwomiles</groupId>
<artifactId>architecture-rules</artifactId>
<version>2.0.3</version>

Java 5

We think its pretty safe to assume our users are up to Java 5 now, so we are going to update the code base to Java 5. This also makes it easier for us to integrate the maven-architecture-rules-plugin. If you are not up to Java 5, the greatest version you will be able to use is 2.0.3, which is a good release and should do the trick for you.

Configuration Chaining

Finally, rather trivial in the whole scheme of things, but if you opted to use the programmatic configuration over the recommended XML configuration, then we’re going to slightly modify the Configuration class to allow for chaining. So instead of:

Configuration configuration = new Configuration();
configuration.addRule(rule1);
configuration.addRule(rule2);
configuration.addRule(rule3);

You can use:

Configuration configuration = new Configuration()
.addRule(rule1)
.addRule(rule2)
.addRule(rule3);

This is going to be great once you see an example where you add all of your rules, add all the package locations, and set up the other options.

So thats what we have been working on at Architecture Rules

Related Posts

• Architecture-Rules 2.1.1 Release
• Architecture-Rules 2.1.0 Release
• Wildcard Support

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | No comment | Add to del.icio.us
Post tags: 2.1.1, release

Feed enhanced by Better Feed from Ozh

Changes

• issue-23 determine which dependencies are optional usability
• issue-24 slashes in unix and windows are different, paths can not be read usability
• issue-25 cycles test not run with XML configuration usability
• release notes

We have already fixed a couple of issue for the next release, and completed a handful of tasks that have made improvements to the library. We have been getting a lot of help from mykola.nickishov. Since he was submitting so many quality patches, we invited him to join the project as a committer. He he accepted. Thanks Mykola.

We’ll make a release soon which will describe how to setup your pom.xml to pull down Architecture-Rules automatically, and enhance the CyclicReduendencyException message to point out the exact classes that are involved in the cycles, rather that just reporting on the package. If you can’t wait until the next release for these features, the subversion trunk has historically been stable, so you can checkout the project from source.

Architecture-Rules

Related Posts

• Architecture-Rules 2.1.1 Release
• Architecture-Rules 2.1.0 Release
• Architecture-Rules 2.1.0 on the Horizon

© MikeNereson for Architecture Rules - Blog, 2008. | Permalink | No comment | Add to del.icio.us
Post tags: 2.0.3, release

Feed enhanced by Better Feed from Ozh