smartics-properties-report 0.3.1-SNAPSHOT API

A report library to create reports on properties.

See:
Description

Packages

de.smartics.properties.report	Provides classes to parse project source code and generate reports.
de.smartics.properties.report.app	Provides classes on the domain level.
de.smartics.properties.report.data	Provides classes that represent report data.
de.smartics.properties.report.qdox	Helper package to implement QDox interfaces.
de.smartics.properties.reports	Provides report implementations to generate reports in different formats.
de.smartics.properties.utils	Provides utilities for the report generation process.

A report library to create reports on properties. This library is part of smartics properties.

Domain Objects

This library provides classes to extract property report information from a source tree. It scans the tree for all interfaces that are annotated with the de.smartics.properties.annotations.PropertySet annotation.

The main domain objects are the data containers for

• PropertyReport - the bracket around all sets and properties.
• PropertyReportSet - a set of properties.
• PropertyReportItem - a single property.

They are all part of the de.smartics.properties.report.data package.

Creating a Report

The following code snippets shows how to create a properties report.

First of all you have to create an instance of ReportConfiguration and add all relevant information to specify where the sources are, what encoding to use, etc.

   
   

    
    
final ReportConfiguration configuration = myHelper.createReportConfiguration();

   
   

Usually you will provide a class that maps the information of your environment (e.g. a Maven project) to this configuration.

Now we can create the report, using the configuration from above, like this:

   
   

    
    
final OutputStream out = ...;

  try
  {
    final PropertiesPropertyReport report = new PropertiesPropertyReport(out);
    final ReportBuilder reportBuilder = ReportBuilder.create(configuration);
    reportBuilder.reportTo(report);

    myHelper.reportProblems(report);

    report.flush();
  }
  finally
  {
    IOUtils.closeQuietly(out);
  }

   
   

The PropertiesPropertyReport, as an implementation of the PropertyReport interface, will manage all information encountered during the scan of the project's sources. This report generates a simple Properties file with all properties initialized with their default values.

Note:

The PropertiesPropertyReport generates a simple Properties file with all properties initialized with their default values. Please refer to Standard Reports to find information about other report implementations provided by this library.

The ReportBuilder is responsible to start the processing.

The flush on the report enables any cleanup work to be done. The report may or may not create internal structures (such as indices) and flushing the report will create the current indices. The reason for this is that the report does not know if further property items are present or not.

Note that the report will also collect problems encountered during the report generation. In the above example the helper interfaces with the environment to report any problems. The implementation of the reportProblems method could look like this:

   
   

    
    
void reportProblems(final PropertyReport report) throws MyFailureException
{
  if (report.hasProblems())
  {
    final StringBuilder buffer = new StringBuilder(1024);
    buffer.append("The following problems have been reported:");
    for (final ReportProblem problem : report.getProblems())
    {
      buffer.append("\n - ").append(problem);
    }

    final String message = buffer.toString();
    throw new MyFailureException(message);
  }
}

   
   

Standard Reports

This library provides implementations of the PropertyReport interface in the de.smartics.properties.reports package.

Report	Description
XmlPropertyReport	Creates an XML report.
PropertiesPropertyReport	Creates a Java properties file.
InMemoryPropertyReport	Reads all information into an in-memory structure.

If you are interested in creating your own report, please consider to extend the abstract class AbstractPropertyReport.