Package org.progeeks.jfreechart

This package provides useful extensions for the JFreeChart charting package.

See:
Description

Interface Summary

ChartDataTransform	Interface for classes which can transform a data source into a List of objects that can be fed into a MetaDatasetProducer.
ChartFocusHandler	Interface for objects that perform various drawing operations to indicate where the focus of a chart is.
EnhancedItemRenderer	Renderer improvement that allows getting/setting of attributes for individual items.

Class Summary

CategoryDatasetProducer	DatasetProducer which can be used to generate a DefaultCategoryDataset for use in vertical or horizontal bar charts.
ChartContext	Context which allows rendering of a List of data objects in a chart using the JFreeChart package.
ChartContextPanel	Swing panel that contains a jfreechart ChartPanel and configures it using a ChartContext.
ChartUtils	Some useful static routines.
DefaultChartDataTransform
DefaultFocusHandler	Base class that contains common handling routines for focusing but does not actually do any drawing.
EnhancedStackedXYBarRenderer	Handles some additional drawing for StackedXYBarCharts.
EnhancedStackedXYBarRenderer.TableIndexTuple	Class for representing a cell coordinate for a sparsely populated and/or dynamically sized table of objects.
ItemFocusHandler	This focus handler Most useful with bar charts Requires that the charts renderer implement EnhancedItemRenderer.
LinkedTsDataItem	Data item that can store a reference to the item that provided the data to create it.
MetaDatasetProducer	Abstract class for creating jfreechart Datasets from different types of input data without having to create new DatasetProducers for each class of input data that you want to render.
SeriesFocusHandler	Hilights the whole series of the focus object.
TimeSeriesCrosshairsFocusHandler	FocusHandler which more accurately draws the crosshairs for TimeSeriesDataItems.
TimeSeriesDatasetProducer	A MetaDatasetProducer for TimeSeries collections.
TimeSeriesTable	TimeSeriesCollection which also implements the TableXYDataset interface.
XYCrosshairsFocusHandler	Draws the crosshairs at the data point representing the passed in focus object.
XYDatasetProducer	Baseclass for other DSPs.

Package org.progeeks.jfreechart Description

This package provides useful extensions for the JFreeChart charting package.

Purpose

It has three primary purposes:

1. Provide a way to easily transform data into chart Datasets without writing repetitive code for each type of object for which you want to display in a chart. For example, if you want to produce a TimeSeries chart with the number of hits on your web site per day, another with the hits per month, and a third with your average CPU load per hour, you can produce them all with different instances of TimeSeriesDatasetProducer specified via XML. This functionality was originally designed for the cewolf tablib extension to JFreeChart. It implements the de.laures.cewolf.DatasetProducer interface for this purpose. This is why the cewolf.jar file is required for the package. Currently, the main cewolf project has not been updated to the jfreechart-1.0.0 APIs, so a mini-jar with just the required classes has been included with the example project.
2. Provide a way to specify chart configurations in XML, and thus avoid writing repetitive code over and over for different charts in your application(s). I would roughly guess that 85% of the primary configuration options for JFreeChart (different renderers, colors, axes, etc) can be configured via XML. The can even set multiple axes and (as soon as final jfreechart-1.0.0 comes out) renderers.
3. Provide some visual enhancements for interacting with charts (i.e. show the focus of the chart). Included focus handlers can
   • Highlight a whole series (useful with StandardXYItemRenderer)
   • Draw crosshairs at a single point (also useful with StandardXYItemRenderer )
   • Highlight a single section within a StackedXYBarRenderer (using a custom subclass).
   Focusing can also occur from outside the chart. For example, if you display a table of data and a chart of the data in a split pane, if the user clicks on a row in the table, you may want to highlight the corresponding item/series/timeframe in the chart.

Required Software

The package is currently setup to compile against jfreechart-1.0.0-rc1.jar (and the jcommon.jar that comes with it) or later. The project also implements the cewolf tag library's DatasetProducer interface. As noted above, cewolf has not been updated to build against the jfreechart-1.0.0 APIs, so a mini jar with just the files you need is include in the examples download.

Pieces

There are 4 separate pieces which provide the guts of the above functionality: ChartDataTransforms, MetaDatasetProducers, ChartFocusHandlers, and chart configs (along with Plot configs and optional ChartPanel configs). These, in turn, are bound together into a ChartContext. You do not have to use a fullChartContext (and corresponding ChartContextPanel) if you don't want to. You can use any subset of the individual parts that you like. All of the above pieces designed to be configured via XML using the XML object reading and parsing capabilities of Meta-JB. You don't have to master how the XML loading works if you don't want to. The ChartDemo application provides a simple look at this that you can copy from.

ChartDataTransform

A ChartDataTransform takes whatever Object you want to use to put data into a chart and turns it into a list of simple objects to pass to a DatasetProducer. If you already have code that produces a list of data objects, then you don't have to use a ChartDataTransform, or you can use the DefaultChartDataTransform which simply takes a list and passes it back out. You may want to move your code that creates your list of data objects (for example, code that iterates over a JDBC result set and creates a list of JavaBeans or MetaClass) into a new ChartDataTransform because transforms can also watch their data Object for changes and send those updates to its enclosing ChartContext to automatically update the chart.

MetaDatasetProducer

A MetaDatasetProducer takes a list of data objects and creates a Dataset object (or adds to an existing one). You configure a MetaDatasetProducer by telling it what class (real or meta) it will operate on, and what properties of that class it should extract the various data coordinates from (series, X, Y, Z, category, etc, depending on the type of chart you are creating). The java docs for each of the sample MetaDatasetProducers give more detailed examples of how to use them.

You can configure a ChartContext to have more than one DatasetProducer if you want to have different displays of your data or map it against different axes or with different renderers.

Chart, Plot, and ChartPanel Configs

These aren't new classes or interfaces so much as the most useful pieces of the ChartContext- ChartContextPanel pair. The ChartContext can be entirely configured in XML, and these elements are the largest part of that configuration. The best way to get a handle on how to do this is to look at the ChartDemo application and its associated configuration files in the Examples directory. If you are wondering why the plot config is outside of the chart config (after all, the chart contains the plot, right?), it is because a JFreeChart object must be passed its Plot object as part of its constructor. So the configuration for the Plot is first read in and the Plot created, and then the configuration for the chart itself is read in and passed the Plot. If you study the sample config file provided with ChartDemo, you will see some tags that don't correspond to true objects. These are normally of the format <chart.XXXX>. These are custom tags that the ChartObjectHandler in the org.progeeks.jfreechart.xml package knows how to read and turn into the proper object for the field to be set by them.

ChartFocusHandler

ChartFocusHandlers do as described above under Purpose. They are most helpful when used along with a ChartContext-ChartContextPanel pair since these classes handle tracking mouse clicks and invoking the focus handlers.

ChartDemo

ChartDemo is pretty straightforward. The one thing to keep in mind is that you do not have to use MetaObjects as your data source. You could just as easily use regular Java objects that have bean-like getters and setters. The provided MetaDatasetProducers can handle both MetaObjects and regular objects.

TO DO

• Implement support for Plots that don't have default constructors. Hopefully, the JFreeChart folks will just add the default constructors and make my life easier. Otherwise I have to switch back to storing BeanConfigurators for plots and only instantiate the plot when I have generated the dataset.
• Implement improved handling for legends/titles with multiple Datasets. Right now, don't think there is an easy way to customize how the legend looks (especially what series it displays).
• Implement better support for mapping Datasets to axes/renderers.
• Implement a CombinedFocusHandler so that multiple focus effects could be done easily.
• Implement support for weighting the sub-plots in Combined charts. Easiest way is to use a map for the list of plots and weights, but I need to be able to maintain the order of the map. I could do it with the commons-collections package, but don't want to introduce that requirement just yet.
• Have the chart demo contain a split pane with a table and the chart to demonstrate getting focus events from outside of the chart (and sending from the chart to another view).