architecture rules xml output

[Mike Nereson]

Hi user list. I sent this to the dev list, but there are only a couple of us on it, and I got no response. I'd like your inputs on this:


I just created a new issue for this, but I think if there is going to be any discussion, it should take place in the mailing list.. here are the contents of the issue..

Vladimir had these comments:

>> I was thinking that ArchitectureRules was more like PMD or
>> FindBugs in the sense that it scans the code base and
>> outputs an XML report.  And since JDepends primarily
>> works like that (the JUnit tests are just one more
>> feature of JDepend, but not the primarily one) I was
>> presuming that you could also do the same.
>>
>> IMO writing tests is a bit tidious for a typical high
>> level tool (architecture validation).  Moreover I'm not
>> of the opinion that your tests should fail if you *had*
>> to introduce a dependency a day before a release.  Of
>> course it's not nice, but you can easily correct the
>> problem a few days after a release

They are good comments that open the door for a couple of changes to the tool.

First, each execution of architecture rules could output (an) XML file(s) - one per package? one per rule? one total? At a later date, when we develop the maven 2 report, we will use these files.

The output of the XML will allow a developer to accept broken rules or cyclic dependencies in order to meet a deadline and then come back later to clean up these issues. This is how PMD, checkstyle, findbugs, and all those other tools work. It seems to be what users expect.

So for now, I'd like to see us output some XML files. There should be a default output destination that is overridable by configuration. The files should be output by default, but should be overridable by configuration.

A couple of things. The XML output, and the configuration of this option.

== Output ==

The output will be XML, but the question is, one XML file, one XML file per package, or one XML file per rule?

The output is to be determined. I am looking for input here. Even complete examples. I'd also like a discussion on one vs many files.

== Configuration ==

Configuration will allow the users to turn off the output, and to change the destination of the files.

 <configuration>
 
    ... <sources></sources>
    ... <cyclicalDependency></cyclicalDependency>

    <reporting>
       <enabled>true</enabled>
       <destination>/target/architecture-rules</destination>
    </reporting>

 </configuration>
 
Default values are true, and /target/architecture-rules

Another question I have: if we are ouputting to files, and people want to deal with the issues later, should we still throw the exceptions? Or just a summary report that is output to the console? Also, when a rule is broken the rest of the project should still be checked, so that we find all the broken rules. I think right now, it stops and throws an exception as soon as a rule is found to be broken.

I have a prototype of the XML output.

== Example output ==

<architecture>
  <rules>
    <rule>
    
      <id>dao_layer_rule</id>
    
      <comment>blah blah blah integration</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>
    
      <matches>
      
        <match>
          <package>com.company.project.dao</package>
          <dependencies>
            <dependency>com.company.project.model<dependency>
          </dependencies>
          <violations/>
        </match>
      
        <match>
          <package>com.company.project.dao.hibernate</package>
          <dependencies>
            <dependency>com.company.project.model<dependency>
            <dependency>com.company.project.service.user<dependency>
          </dependencies>
          <violations>
            <violation>com.company.project.service.user</violation>
          <violations>
        </match>
      
        <match>
          <package>com.company.project.dao.jdbc</package>
          <dependencies>
            <dependency>com.company.project.model<dependency>
          </dependencies>
          <violations/>
        </match>
      
      <matches>

    </rule>
  <rules>
</architecture>

== Explanation ==

First, we define the rule that is being investigated

<rules>
    <rule>
    
      <id>dao_layer_rule</id>
    
      <comment>blah blah blah integration</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>

This is just a straight up copy from the configuration.

Next, we show each package that matched the given packages, all of the dependencies that they have including the violations, and then the specific violations.


Here is an example that has a violation.

      <matches>

        <match>
          <package>com.company.project.dao.hibernate</package>
          <dependencies>
            <dependency>com.company.project.model<dependency>
            <dependency>com.company.project.service.user<dependency>
          </dependencies>
          <violations>
            <violation>com.company.project.service.user</violation>
          <violations>
        </match>

And an example that does not have a violation.

            <match>
          <package>com.company.project.dao</package>
          <dependencies>
            <dependency>com.company.project.model<dependency>
          </dependencies>
          <violations/>
        </match>
      

I suspect this XML output can be used in generating an HTML report with the maven site goal. I think the more information we put in here now, the more information we have available to us in the report to be designed later.

One concern is that eventually we are going to figure out how to report the exact class that is breaking the rule. That will need to get into this report at some point. Where does it fit in. Is it something that we can add, or will we need to redo this output to fit it in? So, do we need to figure out the outputting of the class breaking the rule before we can work on this report?

Another possible requirement for this output is that we don't litter the current code. Is there someway this can be created in a pluggable way? Any thoughts on this?

Finally, once we agree on this design, I'd like to try to find someone to work on it. Someone new. Someone other than Mykola or myself. I think if I sent it out to the user list with a clear requirements specification/document that one of the users would be interested in developing this functionality.

~ Mike Nereson
~ http://blog.72miles.com

[Oliver Gierke]

Quick answer: to me the ability to run the checks via an JUnit Test is
THE key feature of architecture rules. I (and developers working in my
architecture chains) just want to get a quick information, if the code
still corresponds to the rules. So a green bar gives the information I
need. All the competitors require more sophisticated setup, execution
a.s.o. The simplicity of architecture rules is why we decided to use
it.

For more detailled reports we use XRadar, that gives a lot more
information than a little architecture check. I guess an XML report
could be a step to build something more sophisticated on it. I
personally do not see the need for that right now.

Regards,
Ollie

> *==* *Output ==*

>
> The output will be XML, but the question is, one XML file, one XML file per
> package, or one XML file per rule?
>
> The output is to be determined. I am looking for input here. Even complete
> examples. I'd also like a discussion on one vs many files.
>

> *==* *Configuration ==*

>
> Configuration will allow the users to turn off the output, and to change the
> destination of the files.
>
> <configuration>
>
> ... <sources></sources>
> ... <cyclicalDependency></cyclicalDependency>
>
> <reporting>
> <enabled>true</enabled>
> <destination>/target/architecture-rules</destination>
> </reporting>
>
> </configuration>
>
> Default values are true, and /target/architecture-rules
>
> Another question I have: if we are ouputting to files, and people want to
> deal with the issues later, should we still throw the exceptions? Or just a
> summary report that is output to the console? Also, when a rule is broken
> the rest of the project should still be checked, so that we find all the
> broken rules. I think right now, it stops and throws an exception as soon as
> a rule is found to be broken.
>
> I have a prototype of the XML output.
>

> == *Example output *==

> == *Explanation *==

[Mike Nereson]

Ollie, thanks for the input.

All the competitors require more sophisticated setup, execution
a.s.o. The simplicity of architecture rules is why we decided to use
it.

I started the project after I tried to use jdpened. It was so hard to see the rules though the code which made it hard to maintain and get a quick overview of. So I agree, the competition can be harder to use. I really want to keep architecture rules simple, but I also want to fill the needs of the users and grow the user base. Mitigating architectural risks is important.

 

I (and developers working in my
architecture chains) just want to get a quick information, if the code
still corresponds to the rules. So a green bar gives the information I
need.

The architecture rules tagline is "assert your architecture" and when I started it I thought one of the competitive advantages that the project had was that it allowed you to use your continuous integration server to detect broken rules. So implementing something like this would void that ability - unless the default functionality stayed the same, and you had to enable the 'passive' checks that only report the issues but do not throw exceptions when those issues exit.

I guess an XML report
could be a step to build something more sophisticated on it. I
personally do not see the need for that right now.

Also the xml output will be a step towards generating the maven 2 site page.

Regards,
Ollie

Thanks again, Ollie. I enjoy hearing from you guys and really enjoy hearing that you have found the tool to be simpler compared to the competition.

~ Mike Nereson