[TTALE-76] Maven Plugin

[jicken]

I started implementing a Maven reporting plugin as outlined in http://www.jit-consulting.de/java/jboss/maven-plugin-feat-jboss-tattletale.html to have a starting point for the discussion.

First of all I try to summarize what I did yesterday evening:

maven-tattletale-plugin is a reporting plugin bound to the site phase, so it's activated in the reporting section of the pom (see the test pom.xml in src/main/test).
You should be able to configure it within the configuration section of the plugin.
There are already some default values set (like output directory and classloader structure) which can be overridden within this configuration section.
The only thing which is required to be specified in the config section is the directory to be scanned (scanDir). blacklist is optional.

At the beginning I thought of generating XML and transform it with XSL to have the HTML pages generated (like junit does).
But with Doxia the HTML pages are automagically integrated in the generated maven site which is not if you are using an external report.
So I decided to do it all in one step using Doxia.

So far the plugin is able to generate a DependsOn report and only that. I copied&pasted some code from the Main.class. That's the point I am not happy with.
That should be refactored to use one codebase for ant and maven (like "move the Main.class code to a differently named class" or sth like that). The same applies to generating the HTML.
It's pretty much the same, but it's not equal :(. Using XML and XSLT would make it much more easier to use it in both worlds.

The next thing is implementing the different reports.
I would suggest using one Mojo per report. So we are able to configure which reports are generated as the reportname is identical to the goalname:

<reportSets>
 <reportSet>
 <configuration/>
 <reports>
 <report>dependsOn</report>
 <report>dependants</report>
 <report>...</report>
 </reports>
 </reportSet>
</reportSets>

have fun!

torben

[jesper.pedersen]

Thanks for looking into this.

Ant and Maven should be a small layer on top of the core framework exposing the configuration of Tattletale and of course provide the integration with the environment in question.

We need to define and implement APIs and output formats that will suite all use-cases of the tool. Having the output be XML would make it easier to transform into different target formats such as HTML and PDF.

The ability to specify which reports you would like to see should be a core functionality and not a property of only the Maven plugin. The Maven plugin should be able to override the setting in the main configuration file or configure the tool at run-time - just like Ant should be able to do.

Looking at your current code you are duplicating the work already done in other areas of the tool.

As stated we need to start with the design of the solution - so a good starting point would be the XML format if the Maven plugin would benefit from this.

Post your ideas on how core functionality and output formats would map nicely into the Maven world and we will work out where we should begin.

[jicken]

"jesper.pedersen" wrote:

Looking at your current code you are duplicating the work already done in other areas of the tool.

The main intention of yesterday's work was getting a rude reporting plugin up and running.
As already stated I am not happy with duplicating code. I am aware of the fact that the logic has to be available at the core and Maven is not more than a stupid wrapper. But duplicating it was the easiest way to cover the infrastructural part of a reporting plugin (building the plugin, usable by a pom.xml, ...).
Changing the implementation to use core functionality should not be a big deal if the core is exposing the necessary APIs and when I know that everything around works as expected.

mission accomplished - discussion started :)

I'll be back with the output stuff. need to get some sleep.

[jesper.pedersen]

Sure thing - I have committed TTALE-92, so now you can run

ant checkstyle

to verify the code style.

[jicken]

while looking at the code and thinking about some XML/HTML formatter (using JAXB and XSLT) I started some refactoring (making report.generate() a template method) to better understand what's going on. without a refactoring I don't see a chance to integrate some other output methods.
during this I started thinking about implementing some tests to verify the refactored sources and their results.

is there any progress on tests? what would be the preferred method of testing?
1. build jar files (like a.jar and b.jar where b.jar depends on a.jar)?
2. using mocks?

so I would say it's better to start with implementing some tests, then refactor, then talking about some alternatives regarding output generation and last but not least integrate that into maven.

what do you think about that?

I'll email you the diff when I adapted the codestyle according to your checkstyle commit so that you can see what I am talking about.

[jesper.pedersen]

is there any progress on tests? what would be the preferred method of testing?
1. build jar files (like a.jar and b.jar where b.jar depends on a.jar)?
2. using mocks?

There are currently no test suite integrated in the project. I think we should just build the archives files and verify the output against them.

A test suite against the XML output sounds like the best way forward as the HTML reports just will be a transformation in the end.

And yes, we need to define template methods in the report generation stage of the tool.

Breaking the patches up into multiple steps would be the best way to get them integrated quickly - e.g. 1) template methods 2) XML + transformation 3) test suite 4) Maven. Of course with discussions in all the steps about design and implementation.

[jicken]

"jesper.pedersen" wrote:

Breaking the patches up into multiple steps would be the best way to get them integrated quickly - e.g. 1) template methods 2) XML + transformation 3) test suite 4) Maven. Of course with discussions in all the steps about design and implementation.

step 1) done.

next steps:

2a) create XML schemata for the different outputs of the reports; some could be somewhat generic as they contain similar information (i. e. Archive&Dependants, Archive&Depends On)

2b) use JAXB's xjc compiler to create the XML dependent classes (integrated in the build process)

2c) add a toXML() method to the report classes - again template methods where applicable - using the JAXB generated classes to build the XML representation

2d) pass the output of toXML() to a formatter transforming this in the resulting output format (HTML for now) using XSLT.

[jesper.pedersen]

2a) create XML schemata for the different outputs of the reports; some could be somewhat generic as they contain similar information (i. e. Archive&Dependants, Archive&Depends On)

You'll have to argue why we need a separate XSD for each of the reports - currently having a single XSD that can handle all reports is enough IMHO. So, post your use-cases...

2b) use JAXB's xjc compiler to create the XML dependent classes (integrated in the build process)

Ok.

2c) add a toXML() method to the report classes - again template methods where applicable - using the JAXB generated classes to build the XML representation

No, each report should only have a single output method - so that'll be the XML one.

2d) pass the output of toXML() to a formatter transforming this in the resulting output format (HTML for now) using XSLT.

Lets discuss this in more detail when we are closer - I want to limit the number of dependencies for Tattletale, so we'll see what we can figure out.

[jicken]

"jesper.pedersen" wrote:

2a) create XML schemata for the different outputs of the reports; some could be somewhat generic as they contain similar information (i. e. Archive&Dependants, Archive&Depends On)

You'll have to argue why we need a separate XSD for each of the reports - currently having a single XSD that can handle all reports is enough IMHO. So, post your use-cases...

you're right. i am also very happy with one schema file.

"jesper.pedersen" wrote:

2c) add a toXML() method to the report classes - again template methods where applicable - using the JAXB generated classes to build the XML representation

No, each report should only have a single output method - so that'll be the XML one.

agreed.

[jicken]

a summary of yesterday's discussion on irc

switching to XML in 4 steps:
1) XSD + sample .XML
2) Build env + support classes
3) Convert all the reports to XML
4) Transformation XML -> HTML

where 3) and 4) have to go together


1) XSD TODOs:

* change the type of the info-tag attribute "type" to an enum
* sample .XML
* description-tag in the .XML where a description of the report can be placed
* keep the current status-tag for red, yellow and green as the status of report-tag and archive-tag
* another name for the info-tag element inside, ideas/suggestions?
** rename info-tag to detail-tag


2) build env TODOs:

* plug an Ivy based env in (keep maven pom, /me is maintaining it)


3) reports --> XML TODOs:

* integrate the XSD changes
* get rid of TypeComparable::equals() hack in Dependants report


4) nothing done yet, wait for 1) to 3)


not discussed:

* (Transitive) Depends On report: Classes which can't be found are listed in italic
** attribute "found" for "type" 'dependson'
** not a comma-separated list of entries, but single detail-tag element for each entry

[jesper.pedersen]

* change the type of the info-tag attribute "type" to an enum

It should stay as a xsd:token, as each report can add their own value, and we don't want to change the XSD each time.

* keep the current status-tag for red, yellow and green as the status of report-tag and archive-tag

Both report and archive should have status attribute where red, yellow and green is modelled. The current status element can be used for giving a summary for the report - and detail (xsd:string) would be a good name for each status line.

** attribute "found" for "type" 'dependson'
** not a comma-separated list of entries, but single detail-tag element for each entry

found should be an xsd:boolean with a default value of true - and located on IMHO.

The rest looks ok :)

[gastaldi]

What´s the status on this ? I want to help on with the development of this plugin.

[jicken]

if the schema and samples I sent to jesper are fine so far I (only) have to adjust all the reports to the new schema. that should be quite easy as most of the work is already done.

that would be a stage which could be shared:
1. schema ready
2. build env done (but without jesper's suggested ivy)
3. compilation successful

next step would be writing tests to verify the refactoring.

@jesper:
how about branching to share the code?

i thought of the following:
a) tag the existing code base
b) check in the refactoring to HEAD/trunk

if a hotfix is necessary create a branch on the newly created tag or leave out a) and create the branch instantly

or: if you plan to commit other jiras to trunk then let's check in the refactorings to a newly created refactoring branch and we can work on that then. later on we can merge that to trunk.

what do u think?

[jesper.pedersen]

Please, attach the latest code you have to https://jira.jboss.org/jira/browse/TTALE-76.

I'll commit the patches once we agree on the implementation.

[jesper.pedersen]

Torben, did you sync the patch against the latest SVN trunk ?

If you add a patch for the

javax.xml.transform

stuff too, it would be great. E.g. the mapping from the XML format to the HTML format.

TIA