...

In this article, the Pentaho ChartBeans ¹ project is introduced. Pentaho ChartBeans is a wrapper around existing "chart engines" (such as JFreeChart and Open Flash Chart). Wrapping these chart engines creates a single way of expressing charts.

History

Several designs were considered for Pentaho ChartBeans.

ChartModel API

The first design was based on JavaBeans and is the source from which the term "beans" derives. The proposal was for classes for each of the structural components of a chart (such as the plot, series, and title). We'll refer to this design as the ChartModel API.

ChartDocument API

The second design was based on a Document Object Model (DOM). A chart DOM is an object model that consists of elements which can have attributes and child elements. Elements have an associated namespace. Core chart elements, like title and plot would go into the Pentaho ChartBeans namespace. Other, chart engine-specific elements would go into their own namespaces. For example, Open Flash Chart-specific properties would go into a "openflashchart" namespace, while JFreeChart-specific properties would go into a "jfreechart" namespace. We'll refer to this design as the ChartDocument API.

Tale of Two APIs

Both designs have their advantages and disadvantages. The ChartModel API provides JavaBeans familiarity to Java developers (and code completion in IDEs) and the ChartDocument API is highly flexible and extensible. Currently, both approaches are available! You can build a chart by creating a tree of ChartElement objects (with the ChartDocument API) or you can call a series of setters for pieces of the chart's structure (with the ChartModel API).

Prerequisites

Charting Terminology

To eliminate confusion in documentation, the Pentaho ChartBeans project has documented its preferred charting terminology. In addition to standardizing on terms for the purpose of the Pentaho ChartBeans project, this terminology page provides an excellent introduction to charting in general. Please review this page before proceeding.

ChartBeans

Pentaho ChartBeans requires three inputs: the data to be charted, the structure of the chart, and the styling of the chart.

Chart Data: the Chart Table Model

The org.pentaho.chart.ChartData interface is the format for data that is passed to Pentaho ChartBeans. ChartData extends javax.swing.table.TableModel to add row, column, and cell metadata. For example, ChartData allows you to set row and column names. Row and column names are useful for giving meaningful names to series and categories. A single implementation, org.pentaho.chart.data.ChartTableModel, is provided.

Chart Structure: the Chart Document

The org.pentaho.chart.core.ChartDocument class is a Java representation of a Pentaho ChartBeans XML document. It is a tree of org.pentaho.chart.core.ChartElement instances. A chart document includes elements like title, series, and plot. Note that the chart document references (or inlines) style information; see next section.

Chart Styling: the Chart CSS

...

Prerequisites

Java

Pentaho ChartBeans is a Java-based project. As such, a familiarity with Java is recommended as Java classes, packages, and code samples are presented.

Charting Terminology

To eliminate confusion in documentation, the Pentaho ChartBeans project has documented its preferred charting terminology. In addition to standardizing on terms for the purpose of the Pentaho ChartBeans project, this terminology page provides an excellent introduction to charting in general. Please review this page before proceeding.

History

Several designs were considered for Pentaho ChartBeans.

ChartModel API

The first design was based on JavaBeans and is the source from which the term "beans" derives. The proposal was for classes for each of the structural components of a chart (such as the plot, series, and title). We'll refer to this design as the ChartModel API.

ChartDocument API

The second design was based on a Document Object Model (DOM). A chart DOM is an object model that consists of elements which can have attributes and child elements. Elements have an associated namespace. Core chart elements, like title and plot would go into the Pentaho ChartBeans namespace. Other, chart engine-specific elements would go into their own namespaces. For example, Open Flash Chart-specific properties would go into a "openflashchart" namespace, while JFreeChart-specific properties would go into a "jfreechart" namespace. We'll refer to this design as the ChartDocument API.

Tale of Two APIs

Both designs have their advantages and disadvantages. The ChartModel API provides the familiarity of JavaBeans to Java developers (and code completion in IDEs) and the ChartDocument API is highly flexible and extensible. Currently, both approaches are available! You can build a chart by creating a tree of ChartElement objects (with the ChartDocument API) or you can call a series of setters for pieces of the chart's structure (with the ChartModel API).

ChartBeans

Pentaho ChartBeans requires three inputs: the data to be charted, the structure of the chart, and the styling of the chart.

Chart Data: ChartTableModel

The org.pentaho.chart.ChartData interface is the format for data that is passed to Pentaho ChartBeans. ChartData extends javax.swing.table.TableModel to add row, column, and cell metadata. For example, ChartData allows you to set row and column names. Row and column names are useful for giving meaningful names to series and categories. A single implementation, org.pentaho.chart.data.ChartTableModel, is provided.

Persistent Representation

The data to be charted eventually ends up in a ChartTableModel; but how does it get there? Typically, you would execute an MQL query to get a resultset and that would be converted into a ChartTableModel.

Chart Structure: ChartDocument and ChartModel

The org.pentaho.chart.core.ChartDocument class is a Java representation of a Pentaho ChartBeans XML document. It is a tree of org.pentaho.chart.core.ChartElement instances. A chart document includes elements like title, series, and plot. Note that the chart document references (or inlines) style information; see next section.

The org.pentaho.chart.model.ChartModel class is a JavaBeans-style representation of a chart. It has getters and setters for structural components like title and plot. For now, ChartModel instances also contain styling information.

Persistent Representation

While the structure of the chart eventually ends up in a ChartDocument or ChartModel, on disk and over the network it is represented using Pentaho ChartBeans XML. This is the representation of a chart that end users will see. For an example of Pentaho ChartBeans XML, see Example from an End User Perspective.

Chart Styling

Style information is stored in ChartElement instances.

Persistent Representation

While style information eventually ends up in ChartElement instances, on disk and over the network it is represented using Pentaho ChartBeans Cascading Style Sheets (CSS). Pentaho ChartBeans CSS is not limited to the W3C's style attributes (although it attempts to use them where appropriate, for familiarity). By using CSS, Pentaho ChartBeans allows you to completely separate chart structure and styleFor an example of Pentaho ChartBeans CSS, see Example from an End User Perspective.

Examples

Example from a Java Developer Perspective

...

  private static ChartModel createChartModel() {

    List<Series> seriesList = new ArrayList<Series>();
    Series series1 = new Series();
    series1.setForegroundColor(0x2D00FF);
    seriesList.add(series1);
    Series series2 = new Series();
    series2.setForegroundColor(0x11FFE4);
    seriesList.add(series2);

    // lines omitted

    Series series21 = new Series();
    series21.setForegroundColor(0x0596FF);
    seriesList.add(series21);

    CategoricalBarPlot plot = new CategoricalBarPlot();
    plot.setSeries(seriesList);
    plot.setOrientation(Orientation.HORIZONTAL);

    ChartModel chartModel = new ChartModel();
    chartModel.setTitle("Bar Chart Using Pentaho ChartBeans");
    chartModel.setPlot(plot);
    return chartModel;
  }

Chart Styling

For now, styling is included in the Chart Structure when using the Java API.

...

Now let's pull all of the pieces together. First we have a main method that "boots" Pentaho ChartBeans. This reads various configuration files and otherwise readies the system for chart processing requests. Next we render one chart using the JFreeChart plugin for Pentaho ChartBeans and then we render another chart using the Open Flash Chart plugin for Pentaho ChartBeans. Note that both use the same chart document (and referenced stylesheet) as well as the same chart data ChartModel and ChartTableModel.

  public static void main(String[] args) throws Exception {
    // "boot" ChartBeans
    ChartBoot.getInstance().start();

    // remove any output from previous runs
    cleanOutput();

    // render chart using JFreeChart plugin for Pentaho ChartBeans
    renderUsingJFreeChartPlugin(createChartModel(), createChartTableModel(), "chartoutput/Bar.png");

    // render same chart using Open Flash Chart plugin for Pentaho ChartBeans
    renderUsingOpenFlashChartPlugin(createChartModel(), createChartTableModel(), "chartoutput/Bar.html");
  }

...

<chart xmlns="http://reporting.pentaho.org/namespaces/charting/1.0">

  <!-- external style sheet -->
  <stylesheet href="theme.css" />

  <!-- chart title -->
  <title>Bar Chart Using Pentaho ChartBeans</title>
      
  <!-- styling on individual series using style and class attributes -->
  <series style="-x-pentaho-chart-series-type: bar; -x-pentaho-chart-bar-style: bar;" class="series1" />
  <series class="series2" />
  <!-- lines omitted -->
  <series class="series18" />
  
  <!-- wrap colors because there are more series than colors in the theme -->
  <series class="series1" />
  <series class="series2" />
  <series class="series3" />

  <!-- styling on plot using style attribute -->
  <plot style="-x-pentaho-chart-orientation: horizontal"/>
</chart>

Chart Styling

Here is the external style sheet referenced above. Here we're using class selectors. Note the W3C standard color property as well as a custom Pentaho ChartBeans' -x-pentaho-chart-line-width property.

...