com.davisor.graphics.chart
Class ChannelAttributes

java.lang.Object
  com.davisor.graphics.chart.ChannelAttributes

All Implemented Interfaces:

com.davisor.core.Dupable, java.io.Serializable

public class ChannelAttributes

extends java.lang.Object

implements com.davisor.core.Dupable, java.io.Serializable

ChannelAttributes represents a set of chart channel attributes that describe the interpretation rules and default render attributes for channel and sub-channel data elements. In particular, channel attributes add chart -specific meta data to chart -neutral data streams. The actual assosiation between data and channel attributes is done by instances of ChartData.

Sub-channels

Data channels may have hierarcical structure where channels contain tuple elements that model groups of data sub-channels. These sub-channels may contain yet more sub-channels, and so on. The channel attributes of these sub-channels are stored in corresponding recursive arrays of channel attributes. In particular, if a channel contains tuple elements, the corresponding channel attributes object is expected to contain an array of sub-channel attributes where each sub-channel attribute array element matches corresponding tuple element. Any missing attributes are considered undefined.

It must be carefully noted, that even if there is an one-to-one correspondence between data channel and channel attributes hierarchies, these structures are completely separate, and they must be kept synchronized by external means. In particular, changing one hierarchy does not automatically change the other.

Channel attributes

Channel attributes are:

• cumulative - channel cumulativeness flag (may be null)
• group - the channel group the channel belongs to (may be null)
• hidden - channel visibility flag (may be null)
• idRef - channel identifier for data channel, unique within a group of channels
• name - common name for channel data (may be null)
• render - default point and line render attributes (may be null)

Channel cumulativeness

Channel cumulativeness controls if channel data element values should be summed with corresponding data elements in previous data channel.

Channels have explicit order within a data source, and therefore the concept of previous channel is always well defined: a channel is previous to another if the channel order index value is one less than the value of the other channel. The first channel within a data source has channel order index zero, and it has not previous channel. It can also never be cumulative even if it would have been marked so by channel cumulativeness attribute.

Channel elements have also an explicit order within a channel, and therefore the concept of corresponding data elements is also always well defined, too: elements with any channel and with equal element order index always corredpond to each other. If a channel has more elements than some other channel, the missing elements in the shorter channel are considered to have null values.

Element summing is an operation defined by DataValue.add(com.davisor.data.DataValue) method. Summing accross different data types may or may be possible, according to the implementation of the add method. In particular, cumulativeness across two elements is defined only if the add method succeeds and returns a DataValue instance.

The values of cumulative channels are a function of the cumulative and previous channel values. In particular, it is perfectly possible to base a cumulative channel on another cumulative channel. The value of each such cumulative channel is then the sum over all corresponding element values in previous cumulative channels, plus the first channel the first cumulative channel is based on.

Channel groups and channel selection process

Charts select their input channels by two chart specific criteria: channel type and group. Channel type is defined by channel data Type data name, accessible with Type.getDataName() and Type.setDataName(java.lang.String) methods. It should be noted, that type data name is generic chart -neural concept charts just happen to use as part of channel selection mechanism.

Channel group on the other hand is a chart -specific attribute, defined in ChartAxes and accessed by ChartAxes.getDataGroup() and ChartAxes.setDataGroup(java.lang.String) methods. Channels group makes it possible to group channels together by giving them mutually equal group identifiers. A null When a chart needs data channels for some purpose, it first uses the channel type to identify all suitable channel candidates, and then the group to select only those candidates meant for that chart. This is usefull in particular when more than one chart feeds from the same data source.

If a chart has no explicitly set group, it targets only channels belonging to the default null group. If a chart has been given a group, but none of the channel candidates chart found match that group, the chart will fall back to the default group. In all cases, it is possible that channel selection produces no matches, which means that that kind of channels the chart searched for are not availabel for it.

Channel visibility

Channel visibility flag hidden controls if the content of the channel should be displayed at all. If not, the data is still read and computed normally, but none of the results will be displayed in any way. However, any indirect effects the data has, like for example effects on cumulative channel values, remain, and they in turn may have visual effects. Indeed, hidden channels are particularly usefull when used together with cumulative channels.

Channel identity

In addition to channel type and group, channels may also have unique identifiers that may be used to directly refer a particular channel, and assosiate it with some external data source, like and in particular a database column. The identity is simply a string that is expected to be unique over all the data channels present. A missing identity just makes it impossible to refer to the channel with the mechanisms that rely on channel identities. A duplicate identity may or may not cause a run-time error, and it certainly will make the identity of the affected channels ambiguous.

Channel name

Channel name is optional information that is given to the data series created from the data channel. Different charts may react to data series in different ways, but in general, the channel name may be considered a label that applies to the all data elements in that particular channel.

Channel render attributes

A data channel may be also given default line and point render attributes, as defined by a DataRenderAttributes instance. This makes it possible to express desired visualization details already at the data source. Individual charts may later override these setting if explicitly told to do so, but otherwise the render attributes assosiated with a channel will stay in effect in all the charts that use that channel. The details of which attribute settings override which are further described in a separate xml reference document.

Since:

JDK1.2

See Also:

Chart, ChartData, ChartFactory, Serialized Form

Field Summary

protected java.lang.Boolean	M_cumulative Controls if channel data is cumulative (may be null).
protected Type	M_dataType Type of the data channel for this channel attributes.
protected ChannelAttributes	M_defaults Channel default values (may be null).
protected java.lang.String	M_group Channel group identity.
protected java.lang.Boolean	M_hidden Controls if channel data is to be hidden (may be null).
protected java.lang.String	M_idRef Channel identity.
protected java.lang.String	M_name Channel name (if not null, the channel forms a data series).
protected DataRenderAttributes	M_render Channel render attributes.
protected ChannelAttributes[]	M_subChannels Sub-channel specific attributes (may be null).

Constructor Summary

ChannelAttributes()
Default constructor.

ChannelAttributes(ChannelAttributes ca)
Deep copy constructor.

ChannelAttributes(ChannelAttributes ca, ChannelAttributes defaults)
Deep copy constructor, with explicitly given default values.

ChannelAttributes(java.lang.String idRef, java.lang.String group, java.lang.String name, DataRenderAttributes render, java.lang.Boolean cumulative, java.lang.Boolean hidden, ChannelAttributes[] subChannels, ChannelAttributes defaults, Type dataType)
Creates a new channel attributes set with default values.

Method Summary

com.davisor.core.Dupable	dup()
boolean	equals(java.lang.Object object) Test if these channel attributes equal to given channel attributes.
ChannelAttributes	getDefaults() Gets default attributes.
java.lang.String	getGroup() Gets the channel group identity.
java.lang.String	getID() Gets the channel identity.
java.lang.String	getName() Gets the channel name.
DataRenderAttributes	getRender() Gets the channel render attributes.
ChannelAttributes	getSubChannel(int index) Gets sub-channel attributes for given sub-channel.
ChannelAttributes	getSubChannel(java.lang.String id) Gets sub-channel attributes for given sub-channel.
ChannelAttributes[]	getSubChannels() Gets all sub-channel attributes.
Type	getType() Gets the channel data type.
boolean	hasID() Tests if the channel has an identity.
boolean	isArea() Tests the channel fill status.
java.lang.Boolean	isCumulative() Tests the channel cumulative status.
boolean	isCumulativeDefault() Gets the cumulativeness attribute with a non-null default value.
java.lang.Boolean	isHidden() Tests if the channel is to be hidden.
boolean	isHiddenDefault() Gets the hiddenness attribute with a non-null default value.
boolean	isSeries() Deprecated. Use ChartFactory#isMultiSeriesMode instead
void	setCumulative(boolean cumulative) Sets if the channel data is cumulative.
void	setCumulative(java.lang.Boolean cumulative) Sets if the channel data is cumulative.
void	setDefaults(ChannelAttributes defaults) Replaces the current defaults with new default attributes.
void	setGroup(java.lang.String group) Sets the channel group identity.
void	setHidden(boolean hidden) Sets if the channel is to be hidden.
void	setHidden(java.lang.Boolean hidden) Sets if the channel is to be hidden.
void	setID(java.lang.String idRef) Sets the channel identity.
void	setName(java.lang.String name) Sets the channel name.
void	setRender(DataRenderAttributes render) Sets the chart render attributes.
void	setSubChannel(int index, ChannelAttributes subChannel) Sets sub-channel attributes for given sub-channel.
void	setSubChannels(ChannelAttributes[] subChannels) Sets sub-channel attributes.
void	setType(Type dataType) Sets the data channel type.
java.lang.String	toString() Gets channel attributes XML representation.

Methods inherited from class java.lang.Object

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

Field Detail

M_cumulative

protected java.lang.Boolean M_cumulative

Controls if channel data is cumulative (may be null).

M_defaults

protected ChannelAttributes M_defaults

Channel default values (may be null).

M_group

protected java.lang.String M_group

Channel group identity.

M_hidden

protected java.lang.Boolean M_hidden

Controls if channel data is to be hidden (may be null).

M_idRef

protected java.lang.String M_idRef

Channel identity.

M_name

protected java.lang.String M_name

Channel name (if not null, the channel forms a data series).

M_render

protected DataRenderAttributes M_render

Channel render attributes.

M_subChannels

protected ChannelAttributes[] M_subChannels

Sub-channel specific attributes (may be null).

M_dataType

protected Type M_dataType

Type of the data channel for this channel attributes.

Constructor Detail

ChannelAttributes

public ChannelAttributes()

Default constructor.

ChannelAttributes

public ChannelAttributes(ChannelAttributes ca)

Deep copy constructor. The default attributes from the source attributes are, however, not dupped, but shared with the given channel attributes object.

Parameters:

ca - channel attributes to be copied (may be null)

See Also:

dup()

ChannelAttributes

public ChannelAttributes(ChannelAttributes ca,
                         ChannelAttributes defaults)

Deep copy constructor, with explicitly given default values.

Parameters:

ca - channel attributes to be copied (may be null)

defaults - default channel attributes (may be null)

See Also:

dup()

ChannelAttributes

public ChannelAttributes(java.lang.String idRef,
                         java.lang.String group,
                         java.lang.String name,
                         DataRenderAttributes render,
                         java.lang.Boolean cumulative,
                         java.lang.Boolean hidden,
                         ChannelAttributes[] subChannels,
                         ChannelAttributes defaults,
                         Type dataType)

Creates a new channel attributes set with default values. Unset channel and render attributes will now default to given default values.

In order to keep the supplied render attribute object unmodified, a new render attribute object is always created, and the values of the given render attributes are copied into it. Furthermore, the render attributes in the given default channel attributes object are made the default values for the new render attribute object.

In order to keep the supplied data type of the data channel into which these channel attributes point at, a new type with the values of the given type is created.

Parameters:

idRef - channel id, used with channel identification

group - channel group, used with channel grouping

name - channel name, used with channel labeling

render - channel render attributes (may be null)

cumulative - channel cumulativeness (may be null)

hidden - channel hidden status (may be null)

subChannels - sub-channel attributes (may be null)

defaults - default values for unset attributes (may be null)

dataType - channel data type (may be null)

Method Detail

dup

public com.davisor.core.Dupable dup()

Specified by:

dup in interface com.davisor.core.Dupable

equals

public boolean equals(java.lang.Object object)

Test if these channel attributes equal to given channel attributes.

toString

public java.lang.String toString()

Gets channel attributes XML representation.

See Also:

RenderAttributes.toString(int,String), Strings.toXML(String,Object)

getDefaults

public ChannelAttributes getDefaults()

Gets default attributes.

Returns:

default attributes, or null if the defaults have not been set

See Also:

setDefaults(com.davisor.graphics.chart.ChannelAttributes)

getGroup

public java.lang.String getGroup()

Gets the channel group identity. If the group has not been set, but the data type of the channel has been set, the group of the data type is returned. It may also be null.

The group is not inherited from default values.

Returns:

channel group, or null if the group has not been set

getID

public java.lang.String getID()

Gets the channel identity.

Channel identity is not inherited from default values.

Returns:

channel id, or null if the id has not been set

getName

public java.lang.String getName()

Gets the channel name. If the channel name has not been set, but the the data type of the channel has been set, the name of the data type is returned. It may also be null.

If local name is null, we pass getName() to M_defaults, if not null.

Returns:

channel name, or null if the name has not been set

getRender

public DataRenderAttributes getRender()

Gets the channel render attributes. If channel render attributes have not been set, but channel default attributes are available, default channel render attributes are searched for. If found, a new local render attribute set is created and returned.

The new render attribute set defaults to default channel render attributes. In particular, this makes all default channel render attributes visible, but any changes made to the new attribute set will be local, and not change the settings of the default channel.

Returns:

chart render attributes (may be null)

See Also:

getSubChannel(int)

getSubChannel

public ChannelAttributes getSubChannel(int index)

Gets sub-channel attributes for given sub-channel. If sub-channel attributes have not been set, but channel default attributes are available, default attributes sub-channel attributes are searched for. If found, new local sub-channel attributes are created and returned.

The new sub-channel attributes defaults to corresponding default channel sub-channel attributes. In particular, this makes all default channel sub-channel attributes visible, but any changes made to the new attributes will be local, and not change the settings of the default channel.

Parameters:

index - sub-channel index

Returns:

sub-channel attributes (may be null)

See Also:

getRender(), getSubChannel(String), getSubChannels(), setSubChannel(int,ChannelAttributes), setSubChannels(ChannelAttributes[])

getSubChannel

public ChannelAttributes getSubChannel(java.lang.String id)

Gets sub-channel attributes for given sub-channel. If there are multiple sub-channels with the same id, the first sub-channel with the given id is returned.

Parameters:

id - sub-channel id

Returns:

sub-channel attributes, or null if such sub-channel has not been set

See Also:

getSubChannel(int), getSubChannels(), setSubChannel(int,ChannelAttributes), setSubChannels(ChannelAttributes[])

getSubChannels

public ChannelAttributes[] getSubChannels()

Gets all sub-channel attributes.

Returns:

sub-channel attributes, or null if they have not been set

See Also:

getSubChannel(int), getSubChannel(String), setSubChannel(int,ChannelAttributes), setSubChannels(ChannelAttributes[])

getType

public Type getType()
             throws InvalidDataException

Gets the channel data type.

Returns:

data channel type for these channel attributes.

Throws:

InvalidDataException

hasID

public boolean hasID()

Tests if the channel has an identity. Either a true or defaulted identity will do. Channels with an identity can be referenced by it.

See Also:

getID(), setID(java.lang.String)

isArea

public boolean isArea()

Tests the channel fill status. If the channel has a line paint attribute defined, the channel is an area channel, otherwise it is not.

Returns:

channel fill status

See Also:

getRender()

isCumulative

public java.lang.Boolean isCumulative()

Tests the channel cumulative status. If the channel cumulative status has not been set, but channel default attributes are available, the default channel cumulative status is returned. It may also be null.

Returns:

channel cumulative status, or null if the status has not been set

isCumulativeDefault

public boolean isCumulativeDefault()

Gets the cumulativeness attribute with a non-null default value. If the cumulativeness value otherwise would be null, false is returned instead.

See Also:

isCumulative()

isHidden

public java.lang.Boolean isHidden()

Tests if the channel is to be hidden. Default cumulativeness is returned if the actual value has not been set. The default value may, however, also be null.

See Also:

setHidden(Boolean), setHidden(boolean)

isHiddenDefault

public boolean isHiddenDefault()

Gets the hiddenness attribute with a non-null default value. If the hiddenness value otherwise would be null, false is returned instead.

See Also:

isHidden()

isSeries

public boolean isSeries()

Deprecated. Use ChartFactory#isMultiSeriesMode instead

Tests if the channel is a series. A channel defines a data series if it has been given a name, either directly, or by default.

See Also:

getName()

setCumulative

public void setCumulative(java.lang.Boolean cumulative)

Sets if the channel data is cumulative.

See Also:

isCumulative()

setCumulative

public void setCumulative(boolean cumulative)

Sets if the channel data is cumulative.

See Also:

isCumulative()

setDefaults

public void setDefaults(ChannelAttributes defaults)

Replaces the current defaults with new default attributes. This also includes changing the current rendering attribute defaults.

If new render attribute defaults are provided, but there is currently no render attributes object, one is created now, and the new default render attributes are then attached to it.

If the new defaults do not define any render attribute defaults, then the current render defaults, if any, are removed. The current render attributes object is not however removed, even if it was automatically created by an earlier call to this method.

Sub-channel defaults are not directly modified, but they are assumed to use this channel attributes instance as the provider for their own default values. The new defalts will therefore affect the sub-channels indirectly because the new defaults of this object will also be the new defaults to the sub-channel defaults.

Parameters:

defaults - default attributes (may be null)

setGroup

public void setGroup(java.lang.String group)

Sets the channel group identity.

See Also:

getGroup()

setHidden

public void setHidden(java.lang.Boolean hidden)

Sets if the channel is to be hidden.

See Also:

isHidden()

setHidden

public void setHidden(boolean hidden)

Sets if the channel is to be hidden.

See Also:

isHidden()

setID

public void setID(java.lang.String idRef)

Sets the channel identity.

See Also:

getID()

setName

public void setName(java.lang.String name)

Sets the channel name.

See Also:

getName()

setSubChannel

public void setSubChannel(int index,
                          ChannelAttributes subChannel)

Sets sub-channel attributes for given sub-channel. The given sub-channel attributes are also set to take their default values from this instance.

Parameters:

index - sub-channel index

subChannel - sub-channel attributes (may be null)

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is out of bounds

See Also:

getSubChannel(int), getSubChannel(String), getSubChannels(), setDefaults(com.davisor.graphics.chart.ChannelAttributes), setSubChannels(ChannelAttributes[])

setSubChannels

public void setSubChannels(ChannelAttributes[] subChannels)

Sets sub-channel attributes. The given sub-channel attributes are also set to take their default values from this instance.

Parameters:

subChannels - sub-channel attributes (may be null)

See Also:

getSubChannel(int), getSubChannel(String), getSubChannels(), setDefaults(com.davisor.graphics.chart.ChannelAttributes), setSubChannel(int,ChannelAttributes)

setRender

public void setRender(DataRenderAttributes render)

Sets the chart render attributes.

setType

public void setType(Type dataType)

Sets the data channel type.