output XML reports

[Mike Nereson]

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.

So 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.

Mykola, I added a friend of mine who is interested in maybe hoping onto this project at some point to the dev mailing list. His name is Adam. Just wanted to let you know that you may see him around here.

Thanks fellas.

~ Mike Nereson

[Mike Nereson]

Alright, 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>

== Explaination ==

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>
       

So, again, 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?

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 those users would be interested in developing this functionality. Unless anyone on this mailing list is interested in grabbing this task.

Please, I need input on this email and the previous post in this thread. Thanks fellas.

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

[Mike Nereson]

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?

~ Mike Nereson