Main Page
From xradar
MediaWiki has been successfully installed.
Consult the User's Guide for information on using the wiki software.
Contents |
XRadar Wiki
Configuration and troubleshooting information
Roadmap
1.2 (August 2009 ?)
- Using a new Java API to access XRadar result, to ease integration inside tools such as Hudson or Sonar:
- hopefully, some more bugfixes, including this two olds bugss:
Integrate more tools ?
- [[1]] (which results could probably be simply agregated to PMD results)
- [[2]] (probably the same here)
- BCEL used to be a part of XRadar but it's been broken for while (as Ckjm moved to bcel-5.2, it may be fixed now)
- Classcycle could be a nice alternative to jdepend
- [[3]] could also be integrated
- and there is still [others tools] to checkout...
Restore XRadar Backup
- Add a way to let user give in input the dynamic folder in order to keep historical audit.
- document it on web site or wiki.
Developer information
Project directory layout
The XRadar directory layout follow, as much as possible, the [Standard Directory Layout].
Stylesheets package layout
The XSL stylesheets, which is in essence, XRadar are organised this way:
code /radar : The XRadar source. This is where the basic system resides. /api : api-generating templates. Used among others to generate the ide-api. /dynamics : Specific XRadar dynamics-report stylesheets. /process : Dynamics specific processing and merging stylesheets. /report : Dynamics report stylesheets. /graph : Common XRadar graph stylesheets. /process : Common XRadar process stylesheets. /statics : Specific XRadar statics-report stylesheets. /graph : Statics specific processing and merging stylesheets. /process : Statics specific processing and merging stylesheets. /report : Statics specific report stylesheets.
/system : System specific configuration codeholdes in cases where one has extended the XRadar with specific reports for the system. The name of the sub-packages speaks for themselves.
/util : Generic utility libraries code
XSLT Tricks
There are a few pages that are recommended resources for xslt nerds like myself. For any developer of the XRadar, the following links will be a great help:
- [Schools] is a great source for all technologies used in the XRadar: xsl, XPath, HTML, CSS. It was used heavily in the beginning of XRadar.
- [Family of specifications] is also a good resource when in doubt of specifics in the XSL/XPath jungle.
- [XSLT pages] has several tutorial, tips on patterns on good xslt-design as well as some algorithm's that are in use in the XRadar today.
XRadar Architecture
The main running platform for the XRadar used to be ant, but since 1.0, xradar has become a java based software. The purpose of this new plafform are :
- Better way to logging, trace and debug xradar transformation
- Ease the integration of xradar in other platform (java command line tool,ant, maven, maven2, Eclipse,...) and especially maven2,as a maven2 plugin is the our main target at this moment.
- Integration into Hudson/Sonar is probably the middle term target now.
- Ease packaging: XRadar will now be released as a simple jars.
This architecture has been very successful for tools such as checkstyle or PMD, it is probably the way to go with XRadar !
XRadar protocol
To package all the resources of xradar ( stylesheets, img, properties...) in one jar, we designed a URL resolver that handle a xradar specific protocol. This resolver is able to resolve url such as this one: code xradar://stylesheets/radar/static/graph/style.xsl code In this example, the resolver will look for the file /radar/static/graph/style.xsl in the classpath. Most likely, this file will be found in the xradar-1.0.jar (however, note that you can add your own entry in classpath to override specific part of xradar; a "nice to have" feature). If this fails, meaning, the resources is NOT in the classpath, it uses the same part of the url to look, relativly in the file system ( so in this case, it will look for './radar/static/graph/style.xsl' on the file-system).
Note the first word 'stylesheets' is the host on a generic URL semantic. Here, it serves no purpose. So i just use it as a classifier for the file that addresses the url:
- 'stylesheets' is used obviously when you load an xsl file.</li>
- 'resources' is used for static resources such as jpg files or xml file.</li>
This semantic is NOT mandatory, sometime the xslt engine retrieve de default context and may load an xml file with the 'stylesheets' host. However, you should stick to this convention when add manually url to the files.
XRadar Statics Design
The XRadar architecture is based on pipeline processing. In the following sections, we will describe the design of each process in the Statics pipeline.
__Statics The Analysis Process__
The analysis process is simply calls to the various ant-tasks corresponding to the sources. In some cases the java class is called directly, to override default behavior or if a ant task does not exist for the source. The common denominator of all the analysis sources is that they take produce XML files. Typically the source or the class paths of the system to be analysed are used as the basis for the analysis-library's produced XML-result. All files from the analysis process are put into the docs/xml directory. The files are now ready to be used by the next step in the process - merge.
__The Merging Process__
The merge process in statics uses merging stylesheets to merge each analysis into a common xml after one after the other. This is the process that puts all the pieces togather. JDepend is - due to historical reasons - the first step in the process and is used to lay out the xml. Thereafter, it is not that important which other merges comes in what order. In the end, you have one big (and a little ugly xml), that is build up into a hierarchy from package down to method and field. All metrics are populated under the right place in the hierarchy.
There is no magic to each merge step. There is a master-merge.xsl that most of the specific merge stylesheets inherit from. Each merge is run from the ant script as a style task. The task takes in the master-xml that is to be updated with the particular analysis, as well as a path to the analysis xml-document. The analysis xml is then merged into the master-xml. The means in which the merge is done is highly dependent on the structure of the xml-document.
The result from the merge process are put into docs/xml-folder. We are now ready for cleaning, classifying and nomalizing the resulting xml. The merge-post-process can begin.
__The Merging Post-Processing Process__
After all merging is done, the post-process begins. 3 concrete tasks are done one after the other:
- Post process . The data is first summed and extra meta information is added - such as modularization - from the radar-config.xml
- Normalization . The ugly xml is normalized to a simpler more consistant structure. The dynamics process uses only this xml. Some of the results in statics relies on this normalized xml as well, but most of the report relies on the Ugly Duckling. One day in the future, the team must have a goal to go to the Swan for all the reports.
- System Quality Generation. The system quality definition resides in the readar-config.xml. This last process is used to use that definition to calculate the values for this specific system.
With the post-processing done, we are ready for the big show: Producing the XRadar report itself!
__The Reporting Process__
The report itself is generated by one call to one stylesheet: master-report-detail-frames.xsl. This stylesheet call about 20 or so other stylesheets to build up the whole report. There are many files in the report, and the way in which these are produced is through the xalan-extension Redirect, that is used in many of the sub-stylesheets. A call to Redirect makes a totally new page. The statics report process does not use the noramalized xml to produce the reports. This should probably be fixed in a future release.
Documenting the whole report structure here would be strange, since the report structure is evolving and continually simplified and extended. Hence, we recommend that the best way to explore the XRadar Statics Report is it start with master-report-detail-frames.xsl and go into each of the included stylesheets.
__The Graphing Process__
In statics, the SVG's were originally transformed to images before shown in the XRadar. This took time and wasted space. At one internal release before the system went public, I decided to embed the svg's directly into the system instead. Unfortunately, the old legacy is still there. The svg's in statics are still produced in a separate process to the report. For dynamics, both svgs and html are produced together in the same process. This is especially good for development speed and readability - but unfortunately not available in statics. The statics graphing process uses both the initial and the normalized xml to produce the graphs.
XRadar Dynamics Design
The Dynamics Design is very similar to the Statics Design as can be seen in the XRadar architecture . In the following sections, the design of the dynamics processes will be described in turn. References to the statics processes will be used where applicable.
__The Merging Process__
The statics merging process takes the normalized xml from statics and merges each into a common xml. The same stylesheet - merge-normalized-report-to-dynamics-master.xsl - is used for all the merges. In principle the output has the same structure as the normalized xml, except that for each metric there is a "value" element for each version of the system. The simplest way to understand this is to take a look at the output structure from the testproject.
__The Post-Processing Process__
The dynamics post-processing process adds adds some extra info to the xml so that everything is ready for the final step: The report itself.
__The Reporting and Graphing Process__
The dynamics graphing process is very similar to the statics process except one major detail - all graphs are produced directly from within the report structure. Otherwise the strucure is similar in that there is one style-sheet as input dynamics-report-master-frames.xsl and that this stylesheet is responsible for delegating all creation of the report pages. One very convenient part of the statics design is that system, module, and package all use the same templates for reports in each ares.
My experience with development in dynamics is that it is very quick and fun to add new reports. For every change I have also refactored a lot so the design has steadily become more simple. I believe that if there was a xslt analysis version of the XRadar, the dynamics module would get far better ratings than the statics module!
Integrating new tools reports to XRadar
Making a plug in for a new data source consists of a couple of steps. If we assume that you have an analysis system that you want integrated in the X-Radar framework, the only prerequisite is that the system produces XML and that the library in some way can be initiated from ant. The following steps must be taken:
- To run the analysis you need to add one more target to the system specific analysis task. You can have both a library that analyses the source or
simply a process that gets XML from a loosely coupled external source.
- To merge the analysis you need to add one more target to the system specific merging task. This should call your own developed XSL merging template.
The report is now merged with the common Statics XML analysis database.
- To view the data in Statics you need to edit one of the system specific XSL report templates in the Radar. These are explicitly separated out in the Radar.
They are as a default empty, and can be edited. Here you are free to so whatever you need for your report.
- To view the data in Dynamics, you only need to edit one of the available system specific templates for the Dynamics report. The reason why you most probably
do not need any merge is that if the data is included in the XML database in the proper way, they are automatically included in the Radar.
Tools supported by XRadar
The XRadar is currently bundled as one package with a set of open source sources for the measurements. The common denominator of these is that they all produce XML in some form so that they easily may be integrated into the Radar. These produces the measurements as mentioned in the subsection above:
- [[4]] : Measures package dependecies and calculates relevant metrics.
- [[5]] : Finds standard source code metrics such as source statements, method cyclomatic complexity and javadoc length.
- [[6]] : Finds code violations in the source. This is a rule based system where you can define your own rules in addition to the ones that come with the library.
- [[7]] : Finds code style errors, but also includes some features similar to PMD
- [[8]] : The program ckjm calculates Chidamber and Kemerer object-oriented metrics by processing the bytecode of compiled Java files.
- [[9]] : Standard unit test framework for Java.
- [[10]] : Unit test code coverage tool for Java.
- [[11]] : Unit test code coverage tool for Java.
- [[12]] : Uses static analysis to look for bugs in Java code.
- [[13]] : cloc counts blank lines, comment lines, and physical lines of source code.
FAQ
Where can i find those file path
We tried to externalize almost everything ( all the filename of the xslt for instance) in the org.sourceforge.xradar.statics.defaultValues.properties files. This file can also be overriden using the same classpath tricks. So if you want to modify some xslt to correct a bug or try something, you can simply override anything by adding in the classpath, before the xradar.jar.
I want to change an xslt and try the modification, how can i do it ?
Well, the simple way is to use mvn2 to package a new version. Just run : code $ mvn clean site package code
Run the testproject and see what you get !
I have trouble, i want more info about what's going on inside xradar
XRadar java uses the java logging api provided by the java. To have verbose logging, use the provided logging file in the src/main/resources: code export ANT_OPTS="-Djava.util.logging.config.file=../src/main/resources/logging.properties" code
This is logging already a lot of stuff, but if you want, please had more logs in the java source code !
I want to help, but what can I do ?
- Check if you can fix the bugs declared on the bug tracker !
- Look to the TODO or FIXME tags inside the source code and see what you can do about it, or simply try to write any missing javadoc. If you can't write the javadoc, it means that this piece of code is not clear enough ! (Add a FIXME)
- A lot of testing never hurts, you can simply run the XRadar testproject on your plateform and make a report to us.
- And finally, you can try to add more tools to XRadar !
How to use this Wiki
Project Logo
Click on the following image to upload a new version of the PNG logo image for your project:
