net.sourceforge.chart2d
Class Dataset

java.lang.Object
  |
  +--net.sourceforge.chart2d.Dataset

public class Dataset

extends java.lang.Object

The container for the data values to chart. A dataset is like a third order array (ex. float[][][]). The first order is the "sets" order. A set contains data divided by category. The "sets" refer to the objects described by the legend labels, if a legend exists. The second order is the "cats" or categories order. Data within a set can be divided by category. A category can have multiple data items. If using a graph chart, the categories are described by the labels-axis labels. For pie charts, there is only one category. The third order is the "items" order. The "items" order are the values for a particular category and set. For example, if we had data for the years 1999 and 2000 of how many units were sold on each day during that time, then one way to chart this would be using a graph chart and making the years correspond to the "sets" order, "months", correspond to the "cats" order, and the number of units sold per day correspond to the "items" order.
There are two important rules to mention about this. For each set, the number of cats must be the same. For each cat, the number of items must be the same. In our example, we would probably want to choose the number of items per category to be 30, corresponding the average number of days per month. For months with less than thirdy days, we would populate the unfilled days with the average of the filled days or simply carry the last value of the filled days into the unfilled days. For months with more than thirty days, we would average the last two days, and use that value as the value of the last day.
To create a new dataset, use one of its constructors. To populate it with data, use its set method. Pass the container to any number of GraphProperties or PieChart2DProperties classes using their setDataset method. If passing to a PieChart2DProperties, the value used for each pie sector is the sum of the values in each set of data.

Field Summary

static boolean

VALIDATE_ON_UPDATE_DEFAULT The default is true.

Constructor Summary

Dataset()
Creates a dataset with 0 sets, 0 categories, and 0 items.

Dataset(Dataset dataset)
Creates a dataset that is a copy of another dataset.

Dataset(int sets, int cats, int items)
Creates a dataset with the specified number of sets, categories per set, and items per set and per category.

Method Summary

(package private) void	addChart2D(Chart2D chart2D) Adds a Chart2D object to the set of objects that are using this properties object.
void	convertToStacked() Converts the dataset for use in "stacked" charts.
float	get(int set, int cat, int item) Returns the value for the variable in the set specified by set, the category specified by cat within the set, and the item specified by item within the category.
(package private) boolean	getChart2DNeedsUpdate(Chart2D chart2D) Gets whether this Chart2D object hasn't been updated with changes that have been made since its last udpate.
java.util.Vector	getChart2DVector() Returns the vector of Chart2D objects that are using this object.
float	getGreatest() Returns the greatest value of all the data in the datset.
float	getLeast() Returns the least value of all the data in the datset.
int	getNumCats() Returns the number of categories per set of data in this dataset.
int	getNumItems() Returns the number of items per category of data in this dataset.
int	getNumSets() Returns the number of sets of data in this dataset.
(package private) float[][]	getOldGraphStruct() Returns a float[][] representation of this dataset for use by GraphChartArea.
(package private) float[]	getOldPieStruct() Returns a float[] representation of this dataset for use by PieChartArea.
boolean	getValidateOnUpdate() Returns whether the dataset should be validated whenever a chart is to be updated.
void	remove(int set, int cat, int item) Removes values from the dataset.
(package private) void	removeChart2D(Chart2D chart2D) Removes a Chart2D object from the set of objects that are using this properties object.
void	set(Dataset dataset) Specifies all the values of this dataset from another Dataset.
void	set(int set, int cat, int item, float value) Specifies the value for the variable in the set specified by set, the category specified by cat within the set, and the item specified by item within the category.
void	setDatasetToDefaults() Specifies the dataset should be set to its default state.
void	setValidateOnUpdate(boolean validate) Returns whether the dataset should be validated whenever a chart is to be updated.
void	shiftLower(float[] values) Shifts all the data items one place, from the higher order to the lower order, replacing the highest order items with the specified items.
(package private) void	updateChart2D(Chart2D chart2D) Updates this Chart2D object with any changes that have been made since its last udpate.
boolean	validate(boolean debug) Validates the dataset, printing a debug message if indicated.

Methods inherited from class java.lang.Object

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

Field Detail

VALIDATE_ON_UPDATE_DEFAULT

public static boolean VALIDATE_ON_UPDATE_DEFAULT

The default is true.

Constructor Detail

Dataset

public Dataset()

Creates a dataset with 0 sets, 0 categories, and 0 items. Using the set method will automatically create whatever internal objects are needed for adding data on the fly. The performance of the other constructor, Dataset (int, int, int) is a little better.

Dataset

public Dataset(int sets,
               int cats,
               int items)

Creates a dataset with the specified number of sets, categories per set, and items per set and per category. All internal objects are created at once. Using the set method will create whatever more internal objects are needed for adding more data on the fly.

Parameters:

sets - The number of sets.

cats - The number of categories per set.

items - The number of items per category and per set.

Dataset

public Dataset(Dataset dataset)

Creates a dataset that is a copy of another dataset. Copying is a deep copy.

Parameters:

dataset - The dataset to copy.

Method Detail

setDatasetToDefaults

public void setDatasetToDefaults()

Specifies the dataset should be set to its default state. It's default state is a dataset with no sets, no cats, and no items.

set

public void set(int set,
                int cat,
                int item,
                float value)

Specifies the value for the variable in the set specified by set, the category specified by cat within the set, and the item specified by item within the category. For making a dataset for a pie chart, you'll need only one category per set, and only one item per category; if more exist only the lowest order item in the lowest order category of each set will be used. If internal resources have not yet been allocated to contain such a variable, resources are created.

Parameters:

set - The specified set of the variable.

cat - The specified cat of the variable.

item - The specified item of the variable.

value - The specified value of the variable.

set

public void set(Dataset dataset)

Specifies all the values of this dataset from another Dataset. The values are copied using a deep copy.

Parameters:

dataset - The Dataset to copy.

convertToStacked

public void convertToStacked()

Converts the dataset for use in "stacked" charts. This is a convenience method. Stacked charts are those where each set of data is to be stacked on top of the previous set. So if you have multiple sets of data and you want the graph components corresponding to each set to be stacked on top of the previous set but you don't want to have to adjust your data yourself to get this ***affect*** then use this method. Multiple calls to this method will change your dataset each time. NOTE TO SELF: Not optimized.

setValidateOnUpdate

public void setValidateOnUpdate(boolean validate)

Returns whether the dataset should be validated whenever a chart is to be updated.

Parameters:

validate - If true, then the properties will be validated every time they are used to update a chart.

getChart2DVector

public java.util.Vector getChart2DVector()

Returns the vector of Chart2D objects that are using this object.

Returns:

Vector The associated Chart2D objects.

get

public float get(int set,
                 int cat,
                 int item)

Returns the value for the variable in the set specified by set, the category specified by cat within the set, and the item specified by item within the category. If internal resources have not yet been allocated to contain such a variable and validateOnUpdate is true, then Float.NAN is returned. Otherwise a null pointer error may occurr.

Parameters:

set - The specified set of the variable.

cat - The specified cat of the variable.

item - The specified item of the variable.

Returns:

float The value of this variable.

getNumSets

public int getNumSets()

Returns the number of sets of data in this dataset.

Returns:

int The number of sets of this dataset.

getNumCats

public int getNumCats()

Returns the number of categories per set of data in this dataset. This method requires that the dataset be valid according to the method validate(). If not, then a null pointer error may occurr.

Returns:

int The number of cats per set of this dataset.

getNumItems

public int getNumItems()

Returns the number of items per category of data in this dataset. This method requires that the dataset be valid according to the method validate(). If not, then a null pointer error may occurr.

Returns:

int The number of items per category of this dataset.

getGreatest

public float getGreatest()

Returns the greatest value of all the data in the datset. If the dataset is invalid or empty, then returns Float.MIN_VALUE;

Returns:

float The greatest value in the dataset.

getLeast

public float getLeast()

Returns the least value of all the data in the datset. If the dataset is invalid or empty, then returns Float.MAX_VALUE;

Returns:

float The least value in the dataset.

getValidateOnUpdate

public boolean getValidateOnUpdate()

Returns whether the dataset should be validated whenever a chart is to be updated.

Returns:

boolean If true, then the properties will be validated every time they are used to update a chart.

remove

public void remove(int set,
                   int cat,
                   int item)

Removes values from the dataset. Depending on the values of the paramters, eight different operations may result. The simplest is to remove a particular item from a particular set and a particular category. But one can also perform more complex operations. For example, one can remove every set of data. The key to modifying the behavior is passing in a negative one or -1 value for a parameter. A -1 value specifies that whatever is to be removed, will be removed for all such things (ie sets, cats, or items) corresponding to that parameter. So if one wanted to remove every set of data, one could pass -1 to set, to cat, and to item. This would be specify to remove all items, for all cats, for all sets. If one wanted to remove only a single item from a particular set and a particular category, then one would pass a non -1 value for each of the parameters. Below is a listing of the options and a short description. The letters "a", "b", "c" indicates a non -1 value.
set= -1, cat= -1, item= -1 Removes every set of data.
set= a, cat= -1, item= -1 Removes a particular set of data.
set= -1, cat= a, item= -1 Removes a particular category of data for every set.
set= a, cat= b, item= -1 Removes a particular category of data for a particular set.
set= -1, cat= -1, item= a Removes a particular item for every set and every category.
set= -1, cat= a, item= b Removes a particular item of a particular category in every set.
set= a, cat= -1, item= b Removes a particular item of a particular set in every category.
set= a, cat= b, item= c Removes a particular item of a particular category of a particular set.

Parameters:

set - The set of data within which data is to be removed.

cat - The cat of data within which data is to be removed.

item - The item of data that is to be removed.

shiftLower

public void shiftLower(float[] values)

Shifts all the data items one place, from the higher order to the lower order, replacing the highest order items with the specified items. This method is designed to be used with graph charts where the data is dynamically updated and graphed over time categories. For example, if you picture a normal line chart with say three sets of data, that charts the amount of memory being used by various programs on your computer and is updated every second. The number of lines would correspond to the number of programs being charted. The number of x axis labels would refer to the number of seconds of data is being charted (ex 10 seconds). Every second, we could call shiftLower and this would shift left all the old data in the chart, and shift in to the right of the chart, some new data. There would have to be a new data value for each line in the chart. The the number of lines corresponds to the number of programs, and the number of programs, corresponds to the number of legend labels, etc, the number of data values shifted in must be equal to the number of sets in the dataset.

Parameters:

values - An array of values of length getNumSets() to shift in.

validate

public boolean validate(boolean debug)

Validates the dataset, printing a debug message if indicated. A dataset is valid if and only if for each set of data, there are an equal number of categories of data, and for each category of data there are an equal number of items of data. If the dataset does not pass this test, it will be set to its default valid state, which is the state provided by the default constructor. In this state, a dataset has no sets, no categories, and no items.

Parameters:

debug - If true, a short message will be printed to standard out.

Returns:

boolean If true, the dataset is valid.

getOldGraphStruct

float[][] getOldGraphStruct()

Returns a float[][] representation of this dataset for use by GraphChartArea.

Returns:

float[][] A representation of this dataset.

getOldPieStruct

float[] getOldPieStruct()

Returns a float[] representation of this dataset for use by PieChartArea.

Returns:

float[] A representation of this dataset.

getChart2DNeedsUpdate

boolean getChart2DNeedsUpdate(Chart2D chart2D)

Gets whether this Chart2D object hasn't been updated with changes that have been made since its last udpate.

Parameters:

chart2D - The Chart2D object that may need to be updated.

Returns:

boolean If true, then the Chart2D object needs to be updated.

updateChart2D

void updateChart2D(Chart2D chart2D)

Updates this Chart2D object with any changes that have been made since its last udpate.

Parameters:

chart2D - The Chart2D object that will be updated.

addChart2D

void addChart2D(Chart2D chart2D)

Adds a Chart2D object to the set of objects that are using this properties object.

Parameters:

chart2D - The Chart2D object that will have these properties.

removeChart2D

void removeChart2D(Chart2D chart2D)

Removes a Chart2D object from the set of objects that are using this properties object.

Parameters:

chart2D - The Chart2D object to disassociate from these properties.