com.davisor.graphics.chart
Class ChartData

java.lang.Object
  com.davisor.data.VoidData
      com.davisor.data.stream.StreamDataSource
          com.davisor.graphics.chart.ChartData

All Implemented Interfaces:

Data, DataBuffer, DataSource

public class ChartData

extends StreamDataSource

Chart data.

ChartData represents a shared chart data source that contains tuple elements for chart factories to draw chart images from. ChartData is one of the three major classes that control chart generation. The two other major components are:

• ChartAttributes
• ChartFactory

This documentation gives a summary description of chart data buffers, channels, attributes and types. The details about the advanced data and type framework that chart data objects use to access, store and manipulate chart data are not, however, described herein. More information about them can be found in the reference documentation describing the corresponding Data and Type classes.

Overview

Chart data is stored in a data buffer, which in many ways resembles a SQL result set. The buffer contains TupleData tuples, which contain one or more data elements, much like a SQL result set row contains row elements. Within a tuple, the elements have an explicit order, identity, data type, name and value, again much like the information described in the SQL result set meta data.

There are, however, also significant differences between chart data buffers and result sets. A data buffer, for example, may be read more than once, and the rows within the buffer can be accessed in any order. A typical data buffer implementation also holds the entire buffer in memory, thus gaining speed, but also consuming more resources. Data buffers are also by default not persistent.

A significant difference between data buffer and SQL result set rows is also that data buffer rows are tuple objects, which may recursively contain another tuple. In particular, tuples share the same basic data manipulation interface that simpler DataValue objects do, allowing a group of values to be treated and accessed like a single value. A basic example would be a (X,Y) coordinate pair's tuple data value that defines the coordinates of one data point in a two-dimensional coordinate system.

The chart data buffer's tuple data objects are implemented and accessed through TupleData and TupleType objects. They offer comprehensive data manipulation and access methods, better described in their respective reference documents.

Channels

All tuples in a chart data buffer have an identical structure, defined by the chart data buffer TupleType. Corresponding tuple elements in the buffer form data channels, much like corresponding SQL table elements form table columns. For each channel, the tuple type defines the following base attributes:

• data type - the type of data in this channel
• unique identifier - the key to access this channel by a textual id
• order index - the index key to access this channel by a numerical id
• meaning - the meaning of the data in this channel

The channel data type, identifier and index are hopefully self-explanatory attributes. More information about them and related element access methods can be found in the TupleData and TupleType documentation.

The channel meaning tells for what purpose the channel data has been provided for. In particular, by setting the meaning to one of the special keywords that chart factories recognize, the factories can select what to do with that particular channel. Different chart factories expect and support different channel meanings, but some typical and frequently supported keywords are:

• value - data to be rendered by the chart
• label - strings to label data points with
• color - colors to draw data points with
• paint - paints to fill data areas with
• font - font to render data point related text with
• stroke - line width and style to draw lines with
• shape - point shapes to draw data points with
• url - annotation addresses to associate data points with
• alt - annotation descriptions to associate data points with
• explode - pie slice explosion percentages
• position - positions for data values in 'category' axis (shared x-coord)
• time - alias for 'position' (usually used with time series)

More than one channel may be given the same meaning. In particular, if more than one value channel is specified, then each one will contribute with one data set in the resulting chart, as and if appropriate to the nature of the target chart factory. An equivalent number of attribute channels will typically be accepted to control the appearance of each corresponding data set.

Channel Attributes

While data in attribute channels grant fine-grained control over the data point appearance, channel attributes define more general information that affect all the data values in the corresponding channel. These settings are controlled by ChannelAttributes objects, which define the following attributes:

• id - identifies the channel that these attributes are to be applied to
• render - channel default rendering attributes
• name - series name, if any
• cumulative - indicator if channel values are to be cumulatively added to the values of other channels
• hidden - indicator if channel values are not to be displayed

Channel attributes are associated to the data channel with a matching identity. Channel render attributes give default rendering attributes for the channel data values.

The series name, if any, may be used by the legend factory as a description to the corresponding data series.

The cumulative indicator tells if channel values are to be cumulatively added to the values of the previous channel. The hidden indicator tells if channel values should be taken into account, but not be displayed directly. The interpretation of these values heavily depends on the target chart factory.

Channel attributes may later be overridden by chart specific channel attributes, specified inside the ChartAttributes. This allows the same chart data buffer to be the source for several different charts, without enforcing the charts to use the same channel attributes. Overriding channel attributes, if any, will affect channels with identities matching their own, just like the original attributes.

Implicit Channels

Chart data objects also provide some implicit data channels that contain simple data value analysis information for label and annotation value formatters. If possible, chart factories typically make at least the following implicit value channels available:

• .min - minimum value
• .max - maximum value
• .sum - sum value
• .abs - absolute sum value
• .value - element value
• .label - element label (may be shared by several elements)
• .percent - element absolute percent value

.min, .max, .sum, and .abs channels, if available, provide total minimum, maximum, sum, and absolute sum values over all value channels.

Value channels, like all other explicit channels, may be referenced in formats by channel identities. The formats themselves are not, however, channel specific, so a frequent need is to be able to refer to the current channel that the label is being formatted for. The implicit .value channel provides this information.

The actual number and names of available implicit channels depend on the chart factory type, but when defined, implicit channels behave just like real, explicit channels. The only difference is that implicit data channel identities always begin with a dot character (.), something which normal channel identities never do.

Since:

JDK1.1

See Also:

getLimits(int,Type,boolean,boolean), getLimits(int[],Type,boolean[],boolean[]), ChannelAttributes, Chart, ChartAttributes, ChartFactory, NumberValue, TupleData, TupleType, ChartFactory.createSummary(com.davisor.graphics.chart.ChartData, com.davisor.graphics.chart.ChartAttributes, com.davisor.graphics.chart.ChartAxes, com.davisor.graphics.chart.PlotRenderAttributes, com.davisor.data.EnumType, int[], boolean, int[])

Field Summary

static int	ABS Absolute sum value array index.
static java.lang.String	ABSVALUE Absolut sum value key for additional values map ("abs").
static java.lang.String	ALT Channel key for additional values map ("alt").
static java.lang.String	CHANNEL Channel key for additional values map ("channel").
static java.lang.String	COLOR Channel key for additional values map ("color").
static java.lang.String	EXPLODE Channel key for additional values map ("explode").
static java.lang.String	LABEL Channel key for additional values map ("label").
static int	MAX Maximum value array index.
static java.lang.String	MAXVALUE Maximum value key for additional values map ("max").
static int	MIN Minimum value array index.
static java.lang.String	MINVALUE Minimum value key for additional values map ("min").
static java.lang.String	OBJECT Channel key for additional values map ("object").
static java.lang.String	PAINT Channel key for additional values map ("paint").
static java.lang.String	PERCENTVALUE Percent value key for additional values map ("percent").
static java.lang.String	POSITION Channel key for additional values map ("position").
static java.lang.String	SHAPE Channel key for additional values map ("shape").
static java.lang.String	SIZE Channel key for additional values map ("size").
static java.lang.String	STROKE Channel key for additional values map ("stroke").
static int	SUM Sum value array index.
static java.lang.String	SUMVALUE Sum value key for additional values map ("sum").
static java.lang.String	TIME Channel key for additional values map ("time").
static java.lang.String	URL Channel key for additional values map ("url").
static java.lang.String	VALUE Channel key for additional values map ("value").

Fields inherited from class com.davisor.data.stream.StreamDataSource

M_buffer, M_stream

Fields inherited from class com.davisor.data.VoidData

M_type

Constructor Summary

ChartData(ChartData cd)
Shallow copy constructor.

ChartData(DataStream stream)
Creates a chart data source out of the given stream.

ChartData(JoinedDataBuffer buffer)
Creates a chart data stream source out of the given buffer.

Method Summary

java.lang.String	getID(int channel) Gets the index of the channel with the given (unique) channel identifier.
int	getIndex(java.lang.String id) Gets the index of the channel with the given (unique) channel identifier.
DataValue[][]	getLimits(int[] channels, Type type, boolean[] absolute, boolean[] zeroDefault) Gets the channel minimum and maximum values for the given set of channels.
DataValue[]	getLimits(int channel, Type type, boolean absolute, boolean zeroDefault) Gets the given channel minimum and maximum values.
java.awt.geom.Rectangle2D	getTextBounds(int channel, java.awt.Font font) Measures the maximum text bounds of multirow text elements rendered in the default font render context with the given font.
java.awt.geom.Rectangle2D	getTextBounds(Type format, java.awt.Font font) Measures the maximum text bounds of multirow formatted text elements rendered in the default font render context with the given font.
Type	getType(int channel) Gets the type of a channel.
Type	getType(java.lang.String channelID) Gets the type of the channel with the given (unique) channel identifier.
int	getTypeIndex(java.lang.String typeName) Gets the index of the first tuple member that belongs to the default data group and that has a type name that matches the given name.
int	getTypeIndex(java.lang.String typeName, java.lang.String dataGroup) Gets the index of the first tuple member that belongs to the given data group and that has a type name that matches the given name.
int	getTypeIndex(java.lang.String typeName, java.lang.String dataGroup, java.util.Map channelAttributeMap) Gets the index of the first tuple member that belongs to the given data group and that has a type name that matches the given name.
int[]	getTypeIndexes(java.lang.String typeName) Gets all the indexes of the tuple members that belong to the default data group and that have a type name that matches the given name.
int[]	getTypeIndexes(java.lang.String typeName, java.lang.String dataGroup) Gets all the indexes of the tuple members that belong to the given data group and that have a type name that matches the given type name.
int[]	getTypeIndexes(java.lang.String typeName, java.lang.String dataGroup, java.util.Map channelAttributesMap) Gets all the indexes of the tuple members that belong to the given data group and that have a type name that matches the given type name.
java.lang.Number[]	getValues(int channel, Type type) Gets the given channel sum and the minimum and maximum values.
boolean	isGroup(int channel) Tests if a channel is a group channel.
boolean	isGroup(java.lang.String id) Tests if a channel is a group channel.
java.lang.String	toString() Gets chart data XML representation.

Methods inherited from class com.davisor.data.stream.StreamDataSource

close, getBuffer, getBuffer, getData, getSize, getStream, getStream, isBuffered, setBuffer, setStream, toString

Methods inherited from class com.davisor.data.VoidData

equals, getDataValue, getType, hashCode, setType

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.davisor.data.Data

getType

Field Detail

ABSVALUE

public static final java.lang.String ABSVALUE

Absolut sum value key for additional values map ("abs").

See Also:

Constant Field Values

MINVALUE

public static final java.lang.String MINVALUE

Minimum value key for additional values map ("min").

See Also:

Constant Field Values

MAXVALUE

public static final java.lang.String MAXVALUE

Maximum value key for additional values map ("max").

See Also:

Constant Field Values

SUMVALUE

public static final java.lang.String SUMVALUE

Sum value key for additional values map ("sum").

See Also:

Constant Field Values

PERCENTVALUE

public static final java.lang.String PERCENTVALUE

Percent value key for additional values map ("percent").

See Also:

Constant Field Values

ALT

public static final java.lang.String ALT

Channel key for additional values map ("alt").

See Also:

Constant Field Values

CHANNEL

public static final java.lang.String CHANNEL

Channel key for additional values map ("channel").

See Also:

Constant Field Values

COLOR

public static final java.lang.String COLOR

Channel key for additional values map ("color").

See Also:

Constant Field Values

LABEL

public static final java.lang.String LABEL

Channel key for additional values map ("label").

See Also:

Constant Field Values

PAINT

public static final java.lang.String PAINT

Channel key for additional values map ("paint").

See Also:

Constant Field Values

SIZE

public static final java.lang.String SIZE

Channel key for additional values map ("size").

See Also:

Constant Field Values

SHAPE

public static final java.lang.String SHAPE

Channel key for additional values map ("shape").

See Also:

Constant Field Values

STROKE

public static final java.lang.String STROKE

Channel key for additional values map ("stroke").

See Also:

Constant Field Values

URL

public static final java.lang.String URL

Channel key for additional values map ("url").

See Also:

Constant Field Values

VALUE

public static final java.lang.String VALUE

Channel key for additional values map ("value").

See Also:

Constant Field Values

EXPLODE

public static final java.lang.String EXPLODE

Channel key for additional values map ("explode").

See Also:

Constant Field Values

POSITION

public static final java.lang.String POSITION

Channel key for additional values map ("position").

See Also:

Constant Field Values

TIME

public static final java.lang.String TIME

Channel key for additional values map ("time").

See Also:

Constant Field Values

OBJECT

public static final java.lang.String OBJECT

Channel key for additional values map ("object").

See Also:

Constant Field Values

MIN

public static final int MIN

Minimum value array index.

See Also:

Constant Field Values

MAX

public static final int MAX

Maximum value array index.

See Also:

Constant Field Values

SUM

public static final int SUM

Sum value array index.

See Also:

Constant Field Values

ABS

public static final int ABS

Absolute sum value array index.

See Also:

Constant Field Values

Constructor Detail

ChartData

public ChartData(ChartData cd)
          throws InvalidDataException

Shallow copy constructor. The new object will share the data buffer and channel attribute objects with the original object. However, the array that holds the attributes is not shared. Channel attribute associations may therefore be modified later, without affecting the original object, while any modifications to the attribute objects will reflect back to it.

This constructor is useful when a single chart data source is to be shared between several chart factory invokations. The channel attributes in the shallow copy that this constructor creates can, in particular, be safely re-arranged and re-assigned without affecting the original chart data object.

Parameters:

cd - chart data object to be shallow copied

Throws:

InvalidDataException - if the stream contains invalid data

ChartData

public ChartData(DataStream stream)
          throws InvalidDataException

Creates a chart data source out of the given stream. The stream is consumed immediately, and the data that it contained is buffered for later reference. The stream can either be a tuple data stream with the appropriate data channels, or a simple non-tuple stream.

If the stream is a non-tuple stream, it will be internally converted to a single-element tuple before buffering. The stream type name will become the identity of the resulting single channel.

Throws:

InvalidDataException - if the stream contains invalid data

See Also:

JoinedDataBuffer, ListDataBuffer

ChartData

public ChartData(JoinedDataBuffer buffer)
          throws InvalidDataException

Creates a chart data stream source out of the given buffer. The buffer is expected to be a tuple data buffer with the appropriate data channels.

Throws:

InvalidDataException - if the stream contains invalid data

Method Detail

toString

public java.lang.String toString()

Gets chart data XML representation.

 ChartData is a
   DataBuffer which contains a
     ChartXMLDataBuffer which is a
       JoinedDataBuffer which contains
         ListChartDataBuffer buffers which contain chart data.

       JoinedDataBuffer creates a
         DataStream which is a
           JoinedDataStream which contains
             DataStream objects which are
               IteratorDataStream objects.

         ListChartDataBuffer buffers.
 

Overrides:

toString in class StreamDataSource

See Also:

ChartXMLDataBuffer

getID

public java.lang.String getID(int channel)

Gets the index of the channel with the given (unique) channel identifier. If the channel is not found, null is returned.

See Also:

getIndex(java.lang.String), TupleType.getType(String)

getIndex

public int getIndex(java.lang.String id)
             throws NoSuchTypeException

Gets the index of the channel with the given (unique) channel identifier.

Throws:

NoSuchTypeException - if the given id does not match any member

See Also:

getID(int), getType(String)

getLimits

public DataValue[] getLimits(int channel,
                             Type type,
                             boolean absolute,
                             boolean zeroDefault)
                      throws InvalidDataException

Gets the given channel minimum and maximum values. If a type has been given, the channel elements are converted to that type before the comparison takes place. The target elements must be DataValue objects.

Elements missing from the target channel are either ignored or treated as zero values, as controlled by the zero argument.

The found minimum and maximum values may be found equal. Later computation must be prepared to resolve such cases, too.

The resulting minimum and maximum value objects are guaranteed to be new data value instances, instead of being null or references to some original data values in the given channel. Modifying the returned objects, or their types, will therefore be always possible, and it will not cause any unexpected side-effects in the original data buffer.

Parameters:

channel - index of the channel to be inspected

type - the data type that the elements are to be converted to (may be null)

absolute - use absolute data values or not

zeroDefault - use zero default value for missing values

Returns:

[min,max] array, where the elements are never null

Throws:

java.lang.ClassCastException - if the elements are not DataValue

InvalidDataException - if the data buffer contains invalid data

See Also:

getLimits(int[],Type,boolean[],boolean[]), AxisFactory.resolveLimits(com.davisor.graphics.chart.ChartDataSummary), ChartAxis.computeValues(com.davisor.data.DataValue[]), DataValue.unit(com.davisor.data.DataValue, double), Type.zero()

getLimits

public DataValue[][] getLimits(int[] channels,
                               Type type,
                               boolean[] absolute,
                               boolean[] zeroDefault)
                        throws InvalidDataException

Gets the channel minimum and maximum values for the given set of channels. If a type has been given, the channel elements are converted to that type before the comparison takes place. The target elements must be DataValue objects.

Parameters:

channels - indexes of the channels to be inspected

type - the data type that the elements are to be converted to (may be null)

absolute - use absolute data values or not (may be null, defaults to false)

zeroDefault - use zero value for missing values (may be null, defaults to false)

Throws:

java.lang.ClassCastException - if the elements are not DataValue

InvalidDataException - if the data buffer contains invalid data

See Also:

getLimits(int,Type,boolean,boolean)

getTextBounds

public java.awt.geom.Rectangle2D getTextBounds(int channel,
                                               java.awt.Font font)

Measures the maximum text bounds of multirow text elements rendered in the default font render context with the given font. Any single failed element is ignored. Any other more serious error will silently terminate the operation and cause the maximum bounds so far found to be returned. If no elements succeed, null bounds are returned.

Parameters:

channel - data channel to scan

font - the font to render the text in elements with

Returns:

text bounds (may be null)

See Also:

getTextBounds(Type,Font), LabelRenderer.getTextBounds(String,Font,FontRenderContext,int, Rectangle2D)

getTextBounds

public java.awt.geom.Rectangle2D getTextBounds(Type format,
                                               java.awt.Font font)

Measures the maximum text bounds of multirow formatted text elements rendered in the default font render context with the given font. null format results zero bounds. Any single failed element is ignored. Any other more serious error will silently terminate the operation and cause the maximum bounds so far found to be returned. If no elements succeed, null bounds are returned.

Parameters:

format - text formatter (may be null)

font - the font to render the text in elements with

Returns:

text bounds (may be null)

See Also:

getTextBounds(int,Font), LabelRenderer.getTextBounds(String,Font,FontRenderContext,int, Rectangle2D)

getType

public Type getType(int channel)
             throws InvalidDataException

Gets the type of a channel.

Parameters:

channel - channel number

Throws:

InvalidDataException

See Also:

getType(String), TupleType.getType(int)

getType

public Type getType(java.lang.String channelID)
             throws NoSuchTypeException,
                    InvalidDataException

Gets the type of the channel with the given (unique) channel identifier.

Parameters:

channelID - channel identifier

Throws:

NoSuchTypeException - if the given id does not match any member

InvalidDataException

See Also:

getType(int), TupleType.getType(String)

getTypeIndex

public int getTypeIndex(java.lang.String typeName)

Gets the index of the first tuple member that belongs to the default data group and that has a type name that matches the given name.

This method just calls getTypeIndex(String,String,Map) with default null data group and with null channel attribute map.

Parameters:

typeName - target type name

Returns:

matching type index, or -1 if not found

See Also:

getTypeIndex(String,String,Map), getTypeIndexes(String), TupleType.getTypeIndex(String)

getTypeIndex

public int getTypeIndex(java.lang.String typeName,
                        java.lang.String dataGroup)

Gets the index of the first tuple member that belongs to the given data group and that has a type name that matches the given name. null target data group value indicates the default data group, other values select a spesific data group. This method just calls getTypeIndex(String,String,Map), with a null channel attribute map.

Parameters:

typeName - target type name

dataGroup - target data group (may be null)

Returns:

matching type index, or -1 if not found

See Also:

getTypeIndex(String), getTypeIndex(String,String,Map), getTypeIndexes(String,String,Map), TupleType.getTypeIndex(String)

getTypeIndex

public int getTypeIndex(java.lang.String typeName,
                        java.lang.String dataGroup,
                        java.util.Map channelAttributeMap)

Gets the index of the first tuple member that belongs to the given data group and that has a type name that matches the given name. null target data group value indicates the default data group, other values select a spesific data group.

If an explicit target data group produces no match, the default null data group is searched, and the index of the first default data group member with matching type name is returned.

If a map of channel attributes is given, the tuple members are selected according to the data group specified in the channel attributes for tuple members. If a channel attribute for a tuple member is not found, the group of the tuple member is used for searching. The matching of tuple members and channel attributes is done by the ids.

This method just calls getTypeIndexes(String,String,Map), and returns the first match, if any.

Parameters:

typeName - target type name

dataGroup - target data group (may be null)

channelAttributeMap - map of channel attributes (may be null)

Returns:

matching type index, or -1 if not found

See Also:

getTypeIndex(String), getTypeIndexes(String,String,Map), TupleType.getTypeIndex(String)

getTypeIndexes

public int[] getTypeIndexes(java.lang.String typeName)
                     throws InvalidDataException

Gets all the indexes of the tuple members that belong to the default data group and that have a type name that matches the given name.

This method just calls getTypeIndexes(String,String,Map) with default null data group and with null channel attributes map.

Parameters:

typeName - target type name

Throws:

InvalidDataException

See Also:

getTypeIndex(String), getTypeIndexes(String,String,Map), TupleType.getTypeIndexes(String)

getTypeIndexes

public int[] getTypeIndexes(java.lang.String typeName,
                            java.lang.String dataGroup)

Gets all the indexes of the tuple members that belong to the given data group and that have a type name that matches the given type name. null target data group value indicates the default data group, other values select a spesific data group.

This method just calls getTypeIndexes(String,String,Map) with null channel attributes map.

Parameters:

typeName - target type name

dataGroup - target data group (may be null, indicates default group)

See Also:

getTypeIndex(String,String), getTypeIndexes(String,String,Map), TupleType.getTypeIndexes(String)

getTypeIndexes

public int[] getTypeIndexes(java.lang.String typeName,
                            java.lang.String dataGroup,
                            java.util.Map channelAttributesMap)
                     throws InvalidDataException

Gets all the indexes of the tuple members that belong to the given data group and that have a type name that matches the given type name. null target data group value indicates the default data group, other values select a spesific data group.

If an explicit target data group produces no matches, the default null data group is searched, and the indexes of all default data group members with matching type name are returned.

Type comparisons are made against type names (which need not be unique) and not the type identities (which are unique). null type names do not match, but null data group identities do.

If a map of channel attributes is given, the tuple members are selected according to the data group specified in the channel attributes for tuple members. If a channel attribute for a tuple member is not found, the group of the tuple member is used for searching. The matching of tuple members and channel attributes is done by the ids.

Parameters:

typeName - target type name

dataGroup - target data group (may be null, indicates default group)

channelAttributesMap - map of channel attributes (may be null)

Throws:

InvalidDataException

See Also:

getTypeIndex(String,String), getTypeIndexes(String), TupleType.getTypeIndexes(String)

getValues

public java.lang.Number[] getValues(int channel,
                                    Type type)
                             throws InvalidDataException

Gets the given channel sum and the minimum and maximum values. If a type has been given, the channel elements are converted to that type before the comparison takes place. The target elements must be Number objects.

(The limitation to use number objects only is severe, and it will be lifted in future releases, most propably by integrating this functionality with the more general chart data summary mechanism. The interface of this method will, however, also change at that time.)

Parameters:

channel - index of the channel to be inspected

type - the data type that the elements are to be converted to (may be null)

Returns:

channel minimum, maximum, sum and absolute sum values (use MIN,MAX,SUM and ABS to access the values)

Throws:

java.lang.ClassCastException - if the elements are not Number

InvalidDataException - if the data buffer contains invalid data

isGroup

public boolean isGroup(java.lang.String id)

Tests if a channel is a group channel. A channel is a group channel if it contains tuple data values.

Parameters:

id - channel identity

See Also:

isGroup(int)

isGroup

public boolean isGroup(int channel)

Tests if a channel is a group channel. A channel is a group channel if it contains tuple data values.

Parameters:

channel - channel index

See Also:

getType(int), isGroup(String)