pentaho report

Norman Walsh's Saxon Extensions Package for Saxon 6.*

This package implements Saxon extensions for XSLT.

Copyright (C) 2000 Norman Walsh

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Except as contained in this notice, the names of individuals credited with contribution to this software shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the individuals in question.

Anything derived from this Software that is publically distributed will be identified with a different name and the version strings in any derived Software will be changed so that no possibility of confusion between the derived package and this Software will exist.

Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Norman Walsh's Xalan Extensions Package for Xalan2

This package implements Xalan extensions for XSLT.

Copyright (C) 2000 Norman Walsh

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Except as contained in this notice, the names of individuals credited with contribution to this software shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the individuals in question.

Anything derived from this Software that is publically distributed will be identified with a different name and the version strings in any derived Software will be changed so that no possibility of confusion between the derived package and this Software will exist.

Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Some rules when working with the report definition objects:

• Functions cannot be added to the report once the report generation has started.
• Do not modify the report structure after the report generation is started, unless you know exactly what you are doing.
• It is safe to modify the report definition before the report is started.
• Once the report processing has started, the report from the report processor must not be reused for other purposes.

Groups

A group is a set of database rows, where the contents of the group fields are equal for all rows.

Lets look at the following table:

Car	Color	Price
Toyota	blue	10.000
Toyota	blue	20.000
Toyota	red	15.000
Lexus	blue	25.000
Lexus	yellow	15.000
BMW	yellow	40.000
BMW	blue	35.000
BMW	green	5.000

Groups are always defined on sorted tables. A group is defined by selecting one or more rows, which should form the group. A group instance will contain all rows from the beginning of the group until one of the group fields changes.

Lets select the row car for our group:

Selecting that row as group argument will result in 3 group instances. The first group instance will contain the first 3 rows (as the contents of these rows are equal).

The next instance will contain all rows of the "Lexus" car and the last group contains all rows from the "BMW" rows.

If a group is defined by more than one field, then the group will end, if one of the group member fields changes.

Lets define a group which consists of "Car" and "Color".

The first instance of the group will contain the first 2 rows (Toyota,blue). Then the value in the column "Color" changes, so a new group instance is started. This new group contains a single row, as the column "Car" in the next row will contain a different value.

The next two group instances are "Lexus, blue" and "Lexus, yellow", both group instances contain 1 row, as the color changes after 1 row.

The next row starts a new group, as the column "Car" contains a different value (BWM instead of Lexus). It doesn't matter, that the color is still equal, to end a group instance, it is sufficient that one column value changed.

The typical event sequence for a report

• PageStarted
• ReportStarted
• GroupStarted*
• ItemsStarted
• ItemsAdvanced*
• ItemsFinished
• GroupFinished
• ReportFinished
• PageFinished

Basic flow of data in JFreeReport

DataSource

DataTarget

DataFilter

FormatFilter and FormatParser

A FormatFilter implementation will try to create a string representation of an object using the parse method of its assigned java.text.Format object. It is guaranteed that a FormatFilter will return a default not null String in case that getValue() returns invalid values. This default string is defined by setNullString (String).

A FormatParser implementation will try to parse a String read from its DataSource into an object. The actual work of parsing is delegated to the java.text.Formats parse method. If the string was null or invalid, and parsing was unable to create an object, a predefined value can be returned instead of null.

Common use cases of Filters

• label

  The label prints predefined text in the report and is mostly used to name fields and columns

  The label uses a StaticDataSource to contain its datavalue. This DataSource is contained in the default StringFilter of org.jfree.report.TextElement. The TextElements StringFilter will convert the static value into a string before it gets printed in the report.

• number-field

  The number field reads its value from the reports datasource and formats the value using a decimal format, before the string representation is printed.

  The number-field uses a ReportDataSource to obtain values from the reports datamodel. These values are fed into a NumberFormatFilter, where they get formated using the java.text.DecimalFormat, resulting in a string. The TextElement will check the returned value, as this is a string, nothing is done and the string is printed.
  In case the NumberFormat failed to format the value read from the source, it would return a null value to the TextElement to be printed. Now the TextElement's StringFilter will check the value, and return the predefined NullValue-String instead of null.

• date-function

  The date function field queries the results of a function, and formats the function's return value into a string. The contents of this string can be defined using a format pattern as defined in java.text.SimpleDateFormat.

  The date-function uses a FunctionDataSource to obtain values from the reports function collection. These values are fed into a SimpleDateFormatFilter, where they get formated using the java.text.SimpleDateFormat, resulting in a string. The TextElement will check the returned value, as this is a string, nothing is done and the string is printed.
  In case the DateFormat failed to format the value read from the source, it would return a null value to the TextElement to be printed. Now the TextElement's StringFilter will check the value, and return the predefined NullValue-String instead of null.

These examples should give an idea what can be done with the filters. As filters can contain other filters, you are free to create any combination and put them into the elements.

DataRowConnectable

Elements are connected to the Report's DataSources using a DataRow as connector. The DataRow unifies the access to functions, expressions and the tablemodel. DataSources that need to access one of these sources should use the DataRowDataSource as primary datasource. The specialized sources for accessing Functions and the Reports TableModel should not be used.

The template implementation provide a simple, bean like blackbox interface to the used DataSources and DataFilters and their properties.

The following lines apply to both functions and expressions.

JFreeReport supports 2 kinds of userdefined calculations: Functions are statefull calculations, when the report proceedes they change their state, they sum up, calculate averages, count etc. Statefull means in that case, given you feed the same event multiple times into the function,you are not guaranteed to get the same result.

Expressions in contrast do not maintain a state, they calculate a value or change the report-elements depending on the current Event feed to them. If you feed the same Event into the Expression multiple times, you will always get the same result.

Common to both variants is: Data is fed into the function/expression by using a DataRow object. This object provides the (among others) these methods

• Object get(String name);
• Object get(int columnName);

Expressions are simple and easily explained: Expression have the method

Object getValue() which is called when the expression is queried. All expression have to override this method to perform the calculation and to return the value.

Functions are more complex:
Functions have several notification methods, where the system informs the function that a new event is processed.

• public void pageStarted (ReportEvent event);
• public void reportStarted (ReportEvent event);
• public void groupStarted (ReportEvent event);
• public void itemsStarted (ReportEvent event);
• public void itemsAdvanced (ReportEvent event);
• public void itemsFinished (ReportEvent event);
• public void groupFinished (ReportEvent event);
• public void reportFinished (ReportEvent event);
• public void pageFinished (ReportEvent event);

Functions live in an own environment, separated from the outside world. Changing the original JFreeReport object does not affect the inner JFreeReport-Object. You are also unable to add new Functions or expressions to the report from inside, so all functions and expression have to be set before the report processing has begun.

All Functions have to be cloneable. It is not guaranteed that the report is processed in an linear order, but it is guaranteed that a single instance of a function does pass a reportstate only once.

That means: When processing the report, the system clones the functions on certain save-points (for instance whenever a page is finished). This saved copy can later be used to restart the report processing on that saved point. The copy-state made will never return to a previous save point, but it can (and certainly will occur) that this copy is used to process the report from that saved point on.

So when saving a state after page 2, it will never happen, that this page-2-copy gets used to process page 2 a second time, but it could happen that copies of this page-2-state process the page 3 again and again.

The best way to avoid cloning problems is to use Unmodifiable objects or primitive datatypes when storing a state. Using java.lang.String, one of the java.lang.Number implementers or any other unmodifiable object type is always save. If you use complex objects, lists or hashtables and you get weird results, try to implement a deep-object-copy in the clone() method of the function for these objects.

Using the functions

The function implementation is loaded via its default constructor by the report parser, all function implementations which should be used from within the xml-definitions must define a public default constructor. The functions implementation is defined by specifiying the "class" attribute of the "function" tag and is loaded by using the default class loader. Your function implementation must be in the classloaders classpath.

As with every function, a single function can return one value, something mathematicans express like y = f(x) where x is the data from your report processing.

A function is called several times, for every state change (whenever the report advances) one of the ReportListener methods are called (reportStarted, groupStarted etc). Expressions do not receive events, they just perform their computations based on the current state.

The functions value is returned by the "getValue()" function. You can return any Object, but make sure, that this object does not get modified anymore after it was returned to the caller. (A simple way to obey to this rule is to create a new object whenever the computed object changes).

Functions may reuse results from other functions by using and querying the DataRow object supplied in the report state or the function.

The order of the functions and the order for receiving events is undefined for functions of the same dependency level. So if you define a function which reads values from an other function, it is wise to define the dependencies for these functions.

Defining dependencies is easy: A function with an higher dependency is called before any function with a lower dependency. By default all user functions have the dependency of "0", the lowest possible level. The dependency is defined by specifying the "deplevel" attribute of the function or expression tag.

When using the API, the dependency level is read by "getDependencyLevel()" and can be set with "setDependencyLevel(int)".

For the example above, the caller function would have the dependency level of '0' and the called function the level of '1' or higher.

BandLayoutManager should be defined for bands by using the StyleKey BandStyleSheet.LAYOUTMANAGER. The defined Layoutmanager are only usefull for PageableReportProcessors or similiar targets, where bands are mapped into a static coordinate space.

This module provides basic preview capabilities for JFreeReport. The preview components use worker threads to perform the pagination and exports.

The various export dialogs will register at this module an plug their functionality into the preview components.

The preview components should be closed when they are no longer used, by calling "close()" to shutdown the workerthreads and to free the used resources.

This module requires the Graphics2D output target to be present.

Configuration keys:

An CSV export module. The module registers itself during the module initialization in the preview frame.

The module contains support for raw and layouted csv exports. In the raw mode, the current data row will be written to the file, while the layouted mode tries to preserve the layout in the exported file.

As with all table style exports, this target does not support overlapping elements. If two elements request the same cell, the first element wins.

For best layouted results, you should use the excel export target.

An HTML export module. The module registers itself during the module initialization in the preview frame.

The module supports both HTML 4.01 and XHTML 1.0 output.

As with all table style exports, this target does not support overlapping elements. If two elements request the same cell, the first element wins.

This target supports three modes.

• Stream mode

  prints all content into a single stream. Generated images will be ignored and the stream contains an inlined stylesheet definition. External images loaded by an file or http url will be referenced in the stream, all other internally generated image content will be discarded.

• Directory export

  Writes the content and all external content into a directory. The report contents will be written into a single file, while any external content will be written into a separate data directory. This output mode will generate PNG files for all internal images; external images can be copied into the output directory.

• ZIP Directory export

  Provides the same features as the directory export, but will generate the contents within a ZIP file.

An PDF export module. The module registers itself during the module initialization in the preview frame.

The export is done by using iText; Image content will be recoded to PNG if necessary.

An plain text export module. The module registers itself during the module initialization in the preview frame.

This output target does not support any graphics. The font will be fixed size, the font size is defined by the output target, not the elements. All elements use the same font. Elements which are smaller than the used font size, will not be printed.

This is no general purpose export, and reports using this export should be carefully designed to suit this export target.

An AWT printing support module. The module registers itself during the module initialization in the preview frame.

An excel export module. The module registers itself during the module initialization in the preview frame.

The export is done using the Apache POI library. This library does not support images.

As with all table style exports, this target does not support overlapping elements. If two elements request the same cell, the first element wins.

The first column is the group index, the second column is the report event which created this line. All other columns contain the contents of the datarow.

-1, report-header, column1 , column2, ...
0, group-header, column1 , column2, ...
0, itemband, column1 , column2, ...
..
..
..
0, group-footer, column1 , column2, ...
-1, report-footer, column1 , column2, ...

Currently Graphics2D, PDF and PlainText output are supported by this implementation.

Depends on

• org.jfree.report.module.output.pageable.base.PageableBaseModule

iText uses a set of own font descriptions and does heavily depend on PDF specific features even in generic classes. This package encapsulates all tasks required to create iText fonts.

Common base classes for the table style output targets.

Limitations

The TableExports add several restrictions to the report layouts.

Report elements must not overlay each other. It is ok for bands, but the actual data must never overlap. Once a cell is occupied, it cannot be redefined to contain data from other elements. CellData cannot be combined.

Backgrounds can only be defined for the complete cell.

How does the table export work?

All table targets use a two step process to create the output. In the first step, the layout is computed and styles information is collected. The style information will later be reused to form cascading stylesheets or to fill the Excel style tables.

Cell backgrounds are computed during the pagination phase and are stored in the SheetLayout; The content itself is only stored during the content-generation phase and is held in the TableContentProducer. Once the page is completed the computed content and the sheet-layout instace are forwarded to the Output-processor implementations.

Supported Properties:

• Author
• Encoding
• Title
• GenerateXHTML
• StrictLayout
• BodyFragment

The cell height cannot be defined directly. The only way of influencing the height of a cell is by defining a font for the cell.

The current implementation is not suited for huge documents, as the whole document is held in memory until the complete table was created. This implementation will be fixed in the future.

If possible, use the HTML export to create reports that can be used in a word processor.

This target uses the POI library.

The target consists of 2 parts. The XMLProcessor is used to prepare the report and to initialize the XMLWriter.

The XMLProcessor

The XMLWriter

At the moment two report definition formats are supported, the simple profile is a simplified model of the report definition. Although it does not support all advanced features, its simple structure helps to understand the basic report process and makes it possible to easily write report definitions.

The second parser uses a more complex model, which describes the report is a very detailed way. Due to the low level orientation of the report definition format, writing report definition is more complicated and requires detailed knowledge of the object structures used in JFreeReport. Its more generalized structure allows to define every aspect of the report definition and makes it possible to use all implemented features of JFreeReport.

An extensible report definition parser. The parser uses a generic report definition syntax to fully describe the report. The parser heavily relies on factories to create elements and objects.

The used generic approach leads to a complex and very complex and technically detailed report definition, which can be confusing and difficult to use for human authors.

The DTD for the reportdefinition files can be found at http://jfreereport.sourceforge.net/extreport.dtd or in the distribution package.

The document type declaration for this definition type is

<!DOCTYPE report-definition
  PUBLIC "-//JFreeReport//DTD report definition//EN//extended"
         "http://jfreereport.sourceforge.net/extreport.dtd">

The template inheritance is implemented using various instances of the same template class with variing parameter fill level.

ParserHints used by this parser:

JFreeReport-objectext.parser.parser-config.objectfactoriesjava.util.ListA list containing the class names of all used object factories.JFreeReport-objectext.parser.parser-config.stylekeyfactoriesjava.util.ListA list containing the class names of all used stylekey factories.JFreeReport-objectext.parser.parser-config.templatefactoriesjava.util.ListA list containing the class names of all used template factories.JFreeReport-objectext.parser.parser-config.datasourcefactoriesjava.util.ListA list containing the class names of all used datasource factories.JFreeReport-objectext.parser.parser-config.elementfactoriesjava.util.ListA list containing the class names of all used element factories.JFreeReport-objectext.parser.template-definitionjava.util.ListA list containing all predefined templates.JFreeReport-objectparser.typejava.lang.StringA string marking the type of the parser that was used to create the report. The ext-parser uses "org.jfree.report.modules.parser.ext" and the simple parser uses "org.jfree.report.modules.parser.simple".Element, TemplateDescriptionext.parser.template-referencejava.lang.StringContains the name of the referenced template.JFreeReport-objectext.parser.template-definitionjava.util.ListContains the defined template descriptions.

Bound to	HintName	HintType	Description

The DataSourceFactory is used to describe and create @link org.jfree.report.filter.DataSource} implementations. The DataSource description is provided as ObjectDescription; as all DataSources have Getter and Setter methods defined to access their properties, generic BeanDescriptions are used to descripe the data sources.

The Element factory is used to create Elements based on their content type.

The {@link org.jfree.xml.factory.objects.ClassFactory} and the {@link org.jfree.xml.factory.objects.ObjectDescription} are used to descripe, generate and serialize objects in a generalized way.

ObjectDescriptions are used to descripe the properties of an object. The properties can either be an primitive object (String, Long, Integer, Short, Byte, Character, Boolean) or an compound object. Compound objects may have other primitive or compound objects defined as properties.

You may use the ObjectReferenceGenerator to create the Reference-Documentation for all known Object-Description implementations.

The StyleKeyFactory is used to create StyleKeys in a generic way.

You may use the StyleKeyReferenceGenerator to create the Reference-Documentation for all known StyleKey-Description implementations.

Templates are Facade implementations for the low level DataSources. Templates implement the common use-cases for DataSources.

The ReportConverter can either be used in command line mode (class org.jfree.report.modules.parser.extwriter.ReportConverter) or with a simple GUI implementation (class org.jfree.report.modules.gui.converter.ReportConverterGUI).

The DTD for the reportdefinition files can be found at http://jfreereport.sourceforge.net/report.dtd or in the distribution package.

The document type declaration for this definition type is

<!DOCTYPE report-definition
  PUBLIC "-//JFreeReport//DTD report definition//EN//simple"
         "http://jfreereport.sourceforge.net/report.dtd">

General report processing

All reports are processed by advancing from one report state to another state. Reporting always starts with a start state and ends with a finish state. Whenever a state advances, the internal state of the state-object should change. If the internal state does not change, the process is caught in an infinite loop and must be interrupted. State-advances are tested by using the ReportState.isProceeding method.

Some report states fire events when they advance into another state. These events are used to inform the report-functions that a certain report processing level has been reached. The only valid receiver of ReportEvents are Expressions and Functions.

Start-State	The start state is the first state of the report processing process and the only state that can be created without having a previous state. Events fired: During the advance process, a ReportEvent is fired to inform the state-clients that the report processing has started. ReportListener.reportStarted (ReportEvent) is called for all registered listeners. Advances to: This state advances into the PreGroupHeader state.
PreGroupHeader-State	The PreGroupHeader marks the beginning of a new group. When this state advances, the group is activated and the groupheader of this group should be processed. The system will activate all defined groups before starting to process the items. Events fired: During the advance process, a ReportEvent is fired to inform the state-clients that a new group has started. ReportListener.groupStarted (ReportEvent) is called for all registered listeners. The currently active group can be queried by using ReportState.getCurrentGroupIndex(). Advances to: This state advances into the PostGroupHeader state.
PostGroupHeader-State	If there are more groups to activate for the current report, the PostGroupHeader will activate those groups by advancing into a new PreGroupHeader state. If all groups are activated, the PostGroupHeader-state will start the ItemProcessing by advancing into a PreItemGroup state. Events fired:none Advances to:Either PreGroupHeader or PreItemGroup state.
PreItemGroup-State	This state is used to inform every listener that the ItemProcessing is about to start. At this moment, all groups have been activated. On advance, the ItemStarted event is fired. If there is at least one row to print, this state advances into InItemGroup-state, else this state continues at the PostItemGroup state. The direct advancement into PostItemGroup should only happen if the given TableModel does not contain any rows. Events fired:ItemStarted Advances to:Either InItemGroup or PostItemGroup state.
InItemGroup-State	The report engine is now processing the group items. When advancing, a ItemsAdvanced event is fired. Then state advances into a InItemGroup state as long as the current group is valid and the end of the report has not been reached. A group is valid as long as the contents of the fields assigned to the group do not change. As long as the group is valid, this state advances to InItemGroup-state and increases the current row of the DataRow. If the group is no longer valid, this state advances into a PostItemGroup state. Events fired:ItemsAdvanced. The datarow is automaticly adjusted to reflect the new row. The current row number can be queried by using ReportState.getCurrentRow(). Advances to:Either PostItemGroup or InItemGroup state.
PostItemGroup-State	This state is used to inform every listener that the ItemProcessing is now finished. The advancing will fire the ItemsFinished event and then proceed to PreGroupFooter. Events fired:ItemsFinished Advances to:PreGroupFooter
PreGroupFooter-State	The current group is now finished. The GroupFooter should be printed. This state fires the GroupFinished event and then advances to PostGroupFooter. Events fired:GroupFinished Advances to:PostGroupFooter
PostGroupFooter-State	This state closes the current group. After that group is closed, the report engine checks if there are more open groups, which are invalid and should be closed. A group is valid as long as the contents of the fields assigned to the group do not change. In this case, the state advances to PreGroupFooter for the to be closed group. If there is no group that should be closed and there are more rows to process, the next sub-group is opened and the state advances into PreGroupHeader for the new group. If there are no more groups active and there are no rows to process, then the report processing is almost finished and the state advances to PreReportFooter. Events fired:none Advances to:PreGroupHeader, PreGroupFooter or PreReportFooter.
PreReportFooter-State	Now the report is almost finished. The last task to be done is the processing of the ReportFooter. On advance the ReportFinished event is fired and then the state advances into the FinishState. Events fired:ReportFinished Advances to:FinishState
Finish-State	This state does not advance and fires an ReportProcessingException when it should advance. Events fired:none Advances to:none