Data Sources Overview

Data sources are the primary method for transferring data in and out of the Comparator. A data source indicates its capabilities by implementing a subclass of the IDataSource interface. Data sources that provide information implement a subclass of the IReadableDataSource interface. Data sources that store information implement a subclass of the IWriteableDataSource interface. The methods provided by these interfaces provide information about the data source in both programmatic and human-readable formats.

There are five types of data sources included in the Comparator core classes.

Files: RawFileDataSource, XMLFileDataSource
Clipboards: ClipboardDataSource
Printers: SystemPrinterDataSource, PDFPrinterDataSource
Plotters: JPlotBridge, PTPlotBridge
Generators: EditableDataGenerator, transforms, objective functions

Configuring Data Sources

Data sources are configured progamatically and by users. Calling the configure method allows the data source to prompt the user for needed information. This method returns whether the data source was successfully configured. Data sources are configured programatically using the setOption and getOption methods. New options can be added to a data source by calling the addOption method and specifying whether the option is safe for copying or persistence. Options must be uniquely named, and a Comparator convention is to prefix the option name with the name of the class it is defined in. Subclasses of DataSource can add new options by calling setOptionType directly instead of using addOption.

Controlling data source state has changed considerably in the Comparator. At one point there was five ways to save state for data sources: options, attributes, transient attributes, customization attributes, and local variables. Local variables are undesirable because implementations must manually handle them when copying or persisting the data source. All use of local variables have been eliminated outside of data generators, which have very few remaining, in favor of options.

Attributes, transient attributes, and customization attributes were used previously in data generators. Transient attributes and customization attributes are exactly the same as options with the Option type set to TYPE_COPYONLY. They have now been completely replaced by options and are no longer used. Attributes are exactly the same as options with the Option type set to TYPE_SAFE. An attribute is always a String. Attributes are still used in data generators but are now implemented internally using options.

Files

A FileDataSource reads and writes objects to a file. XMLFileDataSource uses the Java Beans XML Persistence library to encode objects in the file. For direct access to file streams, use the RawFileDataSource which does not define an encoding. Calling the configure method displays a file chooser. Multiple objects can be written to and read from a FileDataSource. Successive calls to read or write work sequentially. To indicate that all of the objects have been processed, use the finish method. The read and write methods try as hard as possible to complete. An exception will be thrown only if the operation was fatally terminated. To receive notification of non-fatal exceptions, use the setExceptionListenerOption method. During processing, this listener will be called for each non-fatal exception that occurs.

Clipboards

A ClipboardDataSource reads and writes objects from the system and Java clipboards. Multiple objects can be written to and read from a ClipboardDataSource only if the underlying clipboard supports this. Applications should not assume that multiple objects can be used. All data passing through the clipboard must implement the Transferable interface. Since this is not always convenient, a transfer proxy can be set using the setTransferClassOption method. The proxy will be given any clipboard data that does not implement the Transferable interface so that it can be suitably wrapped.

Printers

A PrinterDataSource writes data to a printer. There are two printer sources provided. The standard printer service is SystemPrinterDataSource. Calling the configure method displays the operating system printer selection dialog. The SystemPrinterDataSource class accepts plain text to print and can also render and print HTML text. The level of HTML that the SystemPrinterDataSource class can handle is limited by the support in the Swing HTML editor kit. Printing large documents with the SystemPrinterDataSource class isn't advised because automatic pagination can produce bad layouts.

The second printer service is PDFPrinterDataSource. Calling the configure method displays a file chooser dialog to select where to write the PDF file. The PDFPrinterDataSource class only accepts table data.

Plotters

Plotters also appear in the Comparator as data sources. A plotter implements the IPlotter interface. Applications must create their own instance of a plotter as support is provided by external applications. Data is written to the plotter as a series of data elements. Use the plot method to send the data to the plotter.

Generators

Data generators wrap a packet of data, a data element, along with meta-data about the element. The IDataGenerator interface provides read access to the data and meta-data. A subinterface IEditableDataGenerator provides the corresponding write access. The data element is set by the setElement method and read by the getElement method. Some implementations of IDataGenerator generate the data element dynamically when getElement is called. Availability of the data element can be checked ahead of time by calling the isCached method.

Transforms and objective functions are specialized types of data generators used in the Comparator. A transform implements the ITransform interface and an objective function implements the IObjective interface.