5

Data Sources

Overview  Pre-Built Chart DataSources  Loading Data from a File

 Loading Data from a Swing TableModel  Loading Data from an XML Source 

Data Binding using JDBCDataSource  JCData3dUtil class  Making Your Own Chart Data Source

HoleValueChartDataModel - Specifying Hole Values

Making an Updating Chart Data Source  Summary of JClass Chart 3D Data Interfaces

All elements mentioned in this chapter refer to both the Java 2 API and the Java 3D API, unless specifically noted.

---

5.1 Overview

Data is loaded into a chart by attaching one or more data sources to it. A chartable data source is an object that takes real-world data and puts it into a form that JClass Chart 3D can use. Once your data source is attached, you can chart the data in a variety of ways.

The design of JClass Chart 3D makes it possible to chart data from virtually any real-world source. There is a toolkit you can use to create custom chartable objects (data sources) for your real-world data.

Creating your own data sources can be time-consuming. For that reason, JClass Chart 3D provides pre-built chartable data sources for most common real-world data: files, XML sources, and databases.

To understand data sources better, it is important to differentiate between point data and grid data. To refresh your understanding, please review Data Types, in Chapter 1.

This chapter describes how to use the pre-built data sources and how to create your own.

Before delving into how to use the pre-built data sources and how to create your own, a quick review of key elements is important. Please read all of this overview section before proceeding.

5.1.1 Nomenclature

A data model is an abstract model, ie, an interface. A data source is an implementation of the data model. It is the object that actually creates and manipulates the data.

5.1.2 Chart Data Model Hierarchy

5.1.3 Responsibility for Data

It is the application's responsibility to create and manage all required data objects.

The application creates a data source by implementing a data model or set of data models. The application then sets the data source on the Chart3dDataView via either its elevationDataSource or zoneDataSource property. The data view then extracts the data from the data source and stores references to it in an internal data object. The data is not copied.

The application can then get a reference to the internal data object through the data view's elevationData and zoneData properties. The application can then query the internal object for its data values and set certain properties on it.

Grid Data Versus Point Data

A grid data source must implement the Chart3DGridDataModel. When it is set on the data view, an internal data object of type Chart3dGridData is created. A Chart3dGridData object allows you to query its data values and to set certain properties, such as the xLabels, yLabels, and chartStyle.

A point data source must implement the Chart3DPointDataModel. When it is set on the data view, an internal data object of type Chart3dPointData is created. A Chart3dPointData object allows you to query its data values (stored in Chart3dPointSeries objects) and to set certain properties on the Chart3dPointSeries objects, such as its label and its chartStyle.

Note that the elevationDataSource property can take either a grid data source or a point data source, whereas the zoneDataSource property can take only a grid data source. Also, if you set the zoneDataSource property, it must have the same number of X- and Y-values as the elevationDataSource property.

5.1.4 Changing data

Changing data uses an event mechanism. There are two ways to alert the chart to changes:

• use the setElevationDataSource and setZoneDataSource methods (the recommended way)
• through the Chart3dDataEvent mechanism

In the first method, you change the data in the data source object and then reset the data on the data view. The data is re-extracted and the chart will update.

The second option uses the Chart3dDataEvent mechanism. In the data source, when the data changes, a data event is sent to a data listener, and a reaction to the event occurs. Chart3dDataView is registered as a data listener for all the data sources it currently references via the elevationDataSource or the zoneDataSource. Your data source must implement the Chart3dDataManager interface for this mechanism to work.

(As an aside, while you can change the data reference to the data source without setting the data source [without calling a listener], it is strongly not recommended, in that the effects will not be known until a redraw is done.)

5.1.5 Internal data

Internal data is meant as a read-only object. You should not set data values through internal data objects. However, you may use internal data to:

• set chart styles
• set data labels - (x,y) for grid data; (series) for point data

5.1.6 Chart3DDataModel interface

In order for a data source object to work with JClass Chart 3D, it must implement the Chart3dDataModel interface. The simplest of these are the Chart3dPointDataModel interface and the Chart3dGridDataModel interface.

Chart3dPointDataModel interface

The Chart3dPointDataModel interface is the core point data model interface for JClass Chart 3D. In JClass Chart 3D, point data is specified in terms of a doubly subscripted array of Point3d objects.

The Chart3dPointDataModel interface has a single method: getPoints(), which retrieves a doubly subscripted array of Point3d objects (arranged by series):

import javax.vecmath.Point3d;
public Point3d[][] getPoints();

Thus, if:

Point3d[][] points=getPoints();

then the third point of the second series is referred to by:

points[1][2]

When the data view extracts data from the data source, it creates a Chart3dPointSeries for each series of points and stores a singly subscripted array of points in each one.

Here is a code sample that gets the point list for the second series from the internal data object.

Chart3dPointData pointData=(Chart3dPointData) dataView.getElevationData();
ArrayList series=pointData.getSeries();
Chart3dPointSeries pointSeries=(Chart3dPointSeries) series.get(1);
Point3d[] pointSecond=pointSeries.getPoints();

Chart3dGridDataModel interface

The Chart3dGridDataModel interface is the core grid data model interface for JClass Chart 3D. In JClass Chart 3D, grid data is specified in terms of an X-array of grid values, a Y-array of grid values, and a doubly subscripted array of z data values.

There are three methods associated with the Chart3dGridDataModel interface:

• getXGrid() - retrieves the X-grid values array, returning an array of double values representing X-grid points. The values in this array must be strictly increasing.
• getYGrid() - retrieves the Y-grid values array, returning an array of double values representing Y-grid points. The values in this array must be strictly increasing.
• getZValues() - retrieves the z values -- one for each (x,y) grid point, returning doubly subscripted array of double values representing the z values

When the data view extracts data from a grid data source, references to the xGrid, yGrid, and zValue arrays are stored in a Chart3dGridData object. The application can retrieve these from a Chart3dGridData object if desired.

The following table outlines the differences between point and grid data - this concept is crucial in working with JClass Chart 3D.

Point Data	JClass Chart 3D Data	Grid Data
Chart3DPointData	Base data model	Chart3DGridData
Chart3DPointDataModel	Interface	Chart3DGridDataModel
series, points	Basic elements	X grid, Y-grid, Z values
Point3D[][]points	Data types	double [] xGrid double [] yGrid double [][] zValues
elevationData elevationDataSource	Relevant Chart3DDataView properties	elevationData elevationDataSource zoneData zoneDataSource
Chart3DPointData	Internal data	Chart3DGridData
Chart3DPointSeries --> chartStyle -->label	Internal data setable properties	chartStyle xLabels yLabels xLabelsArrayList yLabelsArrayList
Scatter chart	Chart Types	Bar, surface, or scatter chart

---

5.2 Pre-Built Chart DataSources

The pre-built DataSources for JClass Chart 3D are located in the com.klg.jclass.chart3d.data package. Their names and descriptions follow.

DataSource name	Description
Base3dDataSource	Empty base class that implements the Chart3dDataModel and the HoleValueChart3dDataModel. It extends the Chart3dDataSupport class which implements the Chart3dDataManager interface.
Base3dGridDataSource	Base for any data source that chooses to store data internally using the data arranged in a grid. It implements the Chart3dGridDataModel.
Base3dPointDataSource	Base for any data source that chooses to store data internally using a series of points. It implements Chart3dPointDataModel.
JCDefault3dGridDataSource	Extends Base3dGridDataSource to create a more useful default container for JClass Chart 3D data.
JCDefault3dPointDataSource	Extends Base3dPointDataSource to create a more useful default container for JClass Chart 3D data.
JCEditable3dGridDataSource	Extends JCDefault3dGridDataSource with convenience methods that permit data editing. It implements EditableChart3dDataModel.
JCEditable3dPointDataSource	Extends JCDefault3dPointDataSource with convenience methods that permit editing of data. It implements EditableChart3dDataModel.
JCFile3dDataSource	Convenience class that parses data from a file.
JCSwing3dDataSource	A 3d DataSource that converts a Swing TableModel into a form usable by JClass Chart 3D. Extends the JCEditable3dGridDataSource.
JCXML3dDataSource	Parses data from an XML file. Extends the JCDefault3dGridDataSource.
JDBC3dDataSource	Extends JCDefault3dDataSource to create a data source for use with JDBC.

---

5.3 Loading Data from a File

Data that is read from a file is read as regular grid data or irregular grid data.

5.3.1 Regular and Irregular Grid Data

Basically, regular grid data has X- and Y-values at regular intervals. Irregular grid data does not.

An easy way to bring data into a chart is to load it from a formatted file using JCFile3dDataSource. To load data this way, you create a data file that follows JClass Chart 3D's standard format, as outlined in Section 5.3.2, Standard file format.

Then you call JCFile3dDataSource's static createDataSourceFromFile method to create a data source from a file. Here's a code snippet showing this action:

Chart3dDataModel dataSource=JCFile3dDataSource.createDataSourceFromFile("file.dat"));

or

chart3d.getDataView(0).setElevationDataSource(JCFile3dDataSource.createcreateDataSourceFromFile ("igrid.dat"));

5.3.2 Standard file format

The JCFile3dDataSource class is a convenience class that parses data from a file. Do not create an instance of this class; rather, use the static method createDataSourceFromFile(String fileName) as described in the previous section.

This method returns an object of type Base3dDataSource which must be cast to the appropriate type (either JCEditable3dGridDataSource or JCEditable3dPointDataSource). The input file can either contain an irregular or regular grid data or point data. The key words GRID, IGRID, or POINT identify the data format the file contains.

A regular grid file has the following format:

# Comments use the # sign
# For this example the grid has 5 by 3 points
# The grid dimensions are optionally followed by xLabels and yLabels
GRID
5 'A A' 'B' 'C' 'D' 'E'

3 'Y1' 'Y2' Y3'

# Holes have value 100.0
# The Grid increases in
# X steps of 1.0 and Y steps of 2.0
# The origin of the Grid is x = -20.0 and y = 50.0
100.0 1.0 2.0 -20.0 50.0

# 15 data points would follow, 1 for each point
49.875000 43.765625 38.50000 33.984375 30.12400
26.828125 24.0000 21.656875 19.375000 17.39062 16.222 18.444 23.555
58.664 37.894564

An Irregular Grid would supply all the X- and Y-values as well as the data points. An irregular grid file has the following format:

# Irregular grid has 5 by 3 points
# The grid dimensions are optionally followed by xLabels and yLabels
IGRID
5 'A A' 'B' 'C' 'D' 'EE'

3 'Y1' 'Yahoo' 'Y3'

# Holes have value 100.0
100.0

# 5 x values are given
# 3 y values are given
20 21.1 22.3 23 24.4
50.3 51.3 52.6

# 15 Data values follow
23.34343 12.89239 11.99423 15.781212 18.18989
26.828125 24.0000 21.656875 19.375000 17.39062 16.222 18.444 23.555
58.664 37.894564

A point data file would look like this:

# There are 3 series
# The series number is optionally followed by series labels
# The hole value is -1000
POINT 3 'Series 1' 'Series 2' 'Series 3'
-1000

# The are 5 points in series 1
# 5 points follow in (x, y, z) format
5
5.65 6.24 1.78
7.41 7.26 4.21
5.45 5.44 1.43
0.97 9.66 3.41
3.86 1.42 0.20

# The are 4 points in series 2
4
6.57 7.43 8.37
3.79 3.63 2.65
7.89 3.48 5.65
0.78 7.03 0.65

# The are 6 points in series 3
6
9.91 7.54 1.74
6.53 4.62 1.99
8.41 3.49 5.06
7.85 9.16 0.64
6.96 9.18 8.95
3.47 3.19 6.29

---

5.4 Loading Data from a Swing TableModel

The JCSwing3dDataSource class enables you to use any data object that implements Swing's TableModel interface as a JClass Chart 3D data source. The TableModel interface is typically used for Swing JTable components, so your application may already have created a data object of this type.

JCSwing3dDataSource "wraps" around a TableModel object, so that the data appears to the chart in the format it understands.

This data source is available through the elevationSwingDataModel1 and the zoneSwingDataModel1 properties in JClass Chart 3D's JavaBeans. To use them, prepare your data in a Swing TableModel object and set the SwingDataModel property to that object.

---

5.5 Loading Data from an XML Source

5.5.1 XML Primer

XML - eXtensible Markup Language - is a scaled-down version of SGML (Standard Generalized Markup Language), the standard for creating a document structure. XML was designed especially for Web documents, and allows designers to create customized tags ("extensible"), thereby enabling common information formats for sharing both the format and the data on the Internet, intranets, and so on.

XML is similar to HTML in that both contain markup tags to describe the contents of a page or file. But HTML describes the content of a Web page (mainly text and graphic images) only in terms of how it is to be displayed and interacted with. XML, however, describes the content in terms of what data is being described. This means that an XML file can be used in various ways. For instance, an XML file can be utilized as a convenient way to exchange data across heterogeneous systems. As another example, an XML file can be processed (for example, via XSLT [Extensible Stylesheet Language Transformations]) in order to be visually displayed to the user by transforming it into HTML.

Here are links to more information on XML.

• http://www.w3.org/XML/ - another W3C site; contains exhaustive information on standards. Of particular note are the XML schema 1 (structures) and XML schema 2 (datatypes) working drafts. They make up an extension that specifies how to constrain XML documents to particular schema. This is important if you want to represent database data or object-oriented data as XML.
• http://www.java.sun.com/docs/index.html - Sun's XML site
• http://www.oasis-open.org/cover/xml.html - thorough list of links to XML papers and ongoing work

5.5.2 Using XML in JClass

In order to work with XML in your programs or even to compile the JClass XML examples, you will need to have jaxp.jar in your CLASSPATH. Additionally, you will need at least a DOM level 2 parser, such as crimson.jar. Both of these JAR files are distributed with JClass Chart 3D - you can find them in JCLASS_HOME/lib/.

Please note that XML may be used for grid data only, not point data.

The JCXML3dDataSource class parses data in XML format. Specification for the XML data can be found in the chart3d.dtd file (JCLASS_HOME/com/klg/jclass/xml-dtd/).

Example of XML in JClass

For an XML data source example, the XML Chart example is in JCLASS_HOME/examples/chart3d/j2d/data. This example uses the 3d.xml data file.

XML Constructor

The JCXML3dDataSource constructor takes an InputStream in XML form and may also take a Reader that contains XML, a file, a String, or other input source.

Example XML data file

Here is an example of an XML data file specifying chart data according to the supported .DTD file. Labels are optional, as are hole and name. Grids are required, and each must contain at least one val element.

<?xml version="1.0"?>
<!DOCTYPE data SYSTEM "chart3d.dtd">
<data hole="-100" name="my data">

<xgrid>
<xval>0.78</xval>
<xval>1.565</xval>
<xval>2.00</xval>
</xgrid>

<ygrid>
<yval>1.00</yval>
<yval>2.0</yval>
<yval>3.0</yval>
<yval>4.0</yval>
<yval>5.0</yval>
/ul>
</ygrid>

<zgrid>
<zval>15.64</zval>
<zval>23.4546</zval>
<zval>45.4545</zval>
<zval>20.4546</zval>
<zval>14.4545</zval>
</zgrid>

<zgrid>
<zval>18.5656</zval>
<zval>23.884</zval>
<zval>35.6454</zval>
<zval>21.47</zval>
<zval>37.45</zval>
</zgrid>

<zgrid>
<zval>16.58</zval>
<zval>10.5656</zval>
<zval>17.65</zval>
<zval>19.645</zval>
<zval>34.4561</zval>
</zgrid>

<xlabel>January</xlabel>
<xlabel>February</xlabel>
<xlabel>March</xlabel>

<ylabel>Orcs</ylabel>
<ylabel>Zombies</ylabel>
<ylabel>Skeletons</ylabel>
<ylabel>Vampires</ylabel>
<ylabel>Werewolves</ylabel>
</data>

---

5.6 Data Binding using JDBCDataSource

JDBC3dDataSource is not a full data binding solution. It is a data source that you can use to chart data from an SQL Result Set. It does not perform any binding operations such as connecting to or querying the database. You will have to provide that functionality in your application.

To use it, you just attach an instance of JDBC3dDataSource to your chart and pass it a Result Set from your application, as follows:

chart.getDataView(0).setElevationDataSource(new JCDBC3dDataSource(myResultSet));

---

5.7 JCData3dUtil class

The JCData3dUtil class (com.klg.jclass.chart3d.data.JCData3dUtil) is a utility class that contains convenience methods for manipulating, filtering, and copying JClass Chart 3D data models.

The source for all of the following methods is the Chart3dGridDataModel class.

• Use the createDataCopy() method to create a copy of Chart3dGridDataModel's X- grid, Y-grid, and Z values.
• Use the dataCopy() method to copy the xGrid, yGrid and zValues from a source to a destination data model.
• Use createShadedDataModel (double sweepAngle, double riseAngle, double brightness, double ambient) to create a data model that simulates light reflecting off the surface of the source data model with Z values ranging from 0 (no reflection) to 1 (full reflection), as well as an ambient light source. The data model returned from this method may then be used as zone data for the source to produce a grey scale effect. See the Shaded demo, which comes with your JClass Chart 3D distribution, for an example of how to use this method.
• Use createSmoothedDataModel (double centerWeight) to create a "smoothed" data model based on the source data model. The amount of smoothing may be controlled by varying the centerWeight argument. When it is 0, the "smoothed" Z value of a data point is based entirely on the weighted average of its neighbors. When it is 1, no smoothing takes place. When it is between 0 and 1, the result is influenced by its neighbors in proportion to the centerWeight.
• Use createCubicSampledDataModel (double[] xSamples, double[] ySamples) to create a data model which is a subset of source using cubic Interpolation with an xGrid described by xSamples and a yGrid described by ySamples. An alternative to this method is to use createLinearSampledDataModel (double[] xSamples, double[] ySamples) method since the linear interpolation method used to calculate the Z values is generally faster, though it usually produces a coarser approximation of the source data. These last two methods are also available in several other flavours. Please refer to the JClass Chart 3D API for more examples.

---

5.8 Making Your Own Chart Data Source

5.8.1 The Simplest Chart Data Source Possible

In order for a data source object to work with JClass Chart 3D, it must implement the Chart3dDataModel interface. The EditableChart3dDataModel interface can be used in conjunction with the Chart3dDataModel when you want to allow the data source to be editable. The LabelledChart3dDataModel and the HoleValueChart3dDataModel interfaces can also be used in conjunction with ChartData3dModel to extend its functionality to allow for label values (via the LabelledChart3dDataModel interface) and hole values (via the HoleValueChart3dDataModel interface). The LabelledChart3dDataModel has an extension for grid data and for point data, which calls methods specific to the type of data.

The Chart3dDataModel interface is intended for use with existing data objects. If a data object implements its extensions, Chart3dGridDataModel and Chart3dPointDataModel, it provides a way for the Chart to extract the data from the data source. For example, the Chart3dGridDataModel allows JClass Chart 3D to ask the data source for the x-grid values, y-grid values, and for z values. The interface looks like this:

public double[] getXGrid();
public double[] getYGrid();
public double[][] getZvalues();

The values returned by getXGrid() and getYGrid() do not have to be equally spaced, but they must be in strictly increasing order. The length of the first dimension of the doubly subscripted array returned by getZvalues() should be the same as the length of the xGrid array. Also, the length of each array that makes up the second dimension of zValues should be the same as the yGrid array. If this is not true, the shortest length will be used for all related arrays.

As an example, consider the following code snippets, taken from JCChart3d.java. This is the actual default data source for JClass Chart 3D.

The following three methods would allow an object to implement the Chart3dGridDataModel.

/**
* Method required to implement Chart3dGridDataModel interface.
* Retrieves the <i>x</i> grid values
*
* @return array of double values representing <i>x</i> grid points
*/
public double[] getXGrid()
{
  double xarray[] = new double[11];
  for (int i = 0; i < xarray.length; i++) {
    xarray[i] = (double)i;
  }
  return(xarray);
}

/**
* Method required to implement Chart3dGridDataModel interface.
* Retrieves the <i>y</i> grid values
*
* @return array of double values representing <i>y</i> grid points
*/
public double[] getYGrid()
{
  double yarray[] = new double[11];
  for (int i = 0; i < yarray.length; i++) {
    yarray[i] = (double)i;
  }
  return(yarray);
}

/**
* Method required to implement Chart3dGridDataModel interface.
* Retrieves the <i>z</i> values -- one for each (<i>x</i>,<i>y</i>)
* grid point
*
* @return doubly subscripted array of double values representing
* <i>z</i> values
*/
public double[][] getZValues()
{
  double zvals[][] = new double[11][11];
  for (int i = 0; i < zvals.length; i++) {
    for (int j = 0; j < zvals[i].length; j++) {
      double xval = (double)(i-5);
      double yval = (double)(j-5);
      zvals[i][j] = xval*xval + yval*yval;
    }
  }
  return(zvals);
}

The following method would allow an object to implement the Chart3dPointDataModel.

/**
* Method required to implement Chart3dPointDataModel interface.
* Retrieves a list of points for a scatter plot.
*/
public Point3d[][] getPoints()
{
  Point3d[][] series = new Point3d[5][];
  int sizes[] = {3, 5, 6, 4, 2};

  for (int i = 0; i < series.length; i++) {
    Point3d[] points = new Point3d[sizes[i]];
    for (int j = 0; j < points.length; j++) {
      points[j] = new Point3d((double)(20 + 2*i),
        (double)(30 + j), (double)(10*i + j));
    }
    series[i] = points;
  }
  return(series);
}

5.8.2 LabelledChartDataModel - Labelling Your Chart

Sometimes it is important to label each data series and each point in a graph. This information can be added to a data source using the LabelledChart3dDataModel interface. For grid data, one should implement the LabelledChart3dGridDataModel, and for point data, the LabelledChart3dPointDataModel. Both extend the LabelledChart3dDataModel.

The LabelledChart3dDataModel interface contains one method:

public String getDataSourceName();

The getDataSourceName() returns the name of the data source. This appears in the chart as the title of the legend.

LabelledChart3dGridDataModel and LabelledChart3dPointDataModel

The LabelledChart3dGridDataModel interface specifies X-labels and Y-labels for a JClass Chart 3D data model. xlabels and ylabels are used for the X- and Y-axis respectively if the annotation type of the axis is JCAxis.ANNOTATION_DATA_LABELS. This interface also specifies the number of X-grid and Y-grid values.

The LabelledChart3dPointDataModel interface specifies the number of series and the series labels for a JClass Chart 3D data model. Series labels are displayed in the legend.

Note that both interfaces are used only in conjunction with the Chart3dDataModel interface, which means that, in order for an object to be recognized as a chart data source, it needs to implement the Chart3dDataModel interface.

The Base3dGridDataSource class - the base for any data source that chooses to store data internally using data arrayed in a grid - implements the LabelledChart3dGridDataModel interface. The Base3dPointDataSource class - the base for any data source that chooses to store data internally using a series of points - implements the LabelledChart3dPointDataModel interface.

5.8.3 EditableChartDataModel - Modifying Your Data

If you want users to modify data using the edit action in JClass Chart 3D, your data source must implement the EditableChart3dDataModel interface. This interface is used in conjunction with a Chart3dGridDataModel or a Chart3dPointDataModel, and the data object must also implement one of these interfaces to be recognized as a data source. The EditableChart3dDataModel has a single method:

public boolean setZValue(JCData3dIndex index, double newValue);

For grid data, the index will be of type JCData3dGridIndex and the X- and Y-indices of the newValue can be extracted from the index object. For point data, the index will be of type JCData3dPointIndex and the series and point indices can again be extracted from the index object. Note that the EditableChart3dDataModel only allows for Z values to be changed. In other words, newValue is a z value.

Here is a code example showing how to set the zValue of a point for a given series and point index for a point data array (stored in points):

/**
* Sets the zValue of a point for a given series and point index. This
* series and point index is retrieved from the passed in data index,
* which must be of type JCData3dPointIndex.
* @param index The data index from which the series and point indices
* of the point to be edited is obtained.
* @param newValue <code>Point3d</code> object for that position
* @return Whether the edit succeeded
*/
public boolean setZValue(JCData3dIndex index, double newValue)
{
if (index == null || !(index instanceof JCData3dPointIndex)) {
return(false);
}
JCData3dPointIndex pointDataIndex = (JCData3dPointIndex)index;
int seriesIndex = pointDataIndex.getSeries();
int pointIndex = pointDataIndex.getPoint();
   if (seriesIndex < 0 ||
     seriesIndex >= points.length ||
     pointIndex < 0 ||
     pointIndex >= points[seriesIndex].length)
  {
    return(false);
  }
  Point3d point = points[seriesIndex][pointIndex];
  point.z = newValue;
  int type = Chart3dPointDataEvent.RELOAD_POINT;
  fireChart3dDataEvent(new Chart3dPointDataEvent(this, type, pointDataIndex));
  return(true);
} //setZValue

Here is a code example showing how to set the zValue for a given data index for grid data (stored in the zValues array):

/**
* Sets the point for a given data index which must be of type
* JCData3dGridIndex.
*
* @param index The data index from which the x and y indices of the
* point to be edited is obtained.
* @param newValue The new z value for the point
* @return Whether edit succeeded
*/
public boolean setZValue(JCData3dIndex index, double newValue)
{
if (index == null || !(index instanceof JCData3dGridIndex)) {
return(false);
}
JCData3dGridIndex gridIndex = (JCData3dGridIndex)index;
int xIndex = gridIndex.getX();
int yIndex = gridIndex.getY();
   if (xIndex < 0 ||
     xIndex >= zValues.length ||
      yIndex < 0 ||
      yIndex >= zValues[xIndex].length)
    {
      return(false);
    }
  zValues[xIndex][yIndex] = newValue;
  int type = Chart3dGridDataEvent.RELOAD_ZVALUE;
  fireChart3dDataEvent(new Chart3dGridDataEvent(this, type, gridIndex));
  return(true);
} //setDataValue

In this example, the value is saved back into the zValues array from JCDefault3dGridDataSource, using the xIndex and yIndex values to index to the appropriate array member.

The EditGrid and EditPoint examples (found in the JCLASS_HOME/examples/chartd3d/j2d/data directory) demonstrate how to use the EditableChartDataModel interface.

---

5.9 HoleValueChartDataModel - Specifying Hole Values

If you want to supply a specific hole value along with your data, your data source must implement the HoleValueChart3dDataModel interface.

A hole value is a particular value for which the chart will not draw anything each time the hole value is encountered in the data. For a surface chart, the facets surrounding the value are not drawn. For a bar chart, that particular bar is not drawn. For a scatter plot, the point is not drawn.

The HoleValueChart3dDataModel interface has one method, getHoleValue(). This method retrieves the hole value for the data source.

---

5.10 Making an Updating Chart Data Source

Quite often, the data shown in JClass Chart 3D is dynamic. This kind of data requires creation of an updating data source. An updating data source is capable of informing a chart that a portion of the data has been changed. JClass Chart 3D can then act on the change.

JClass Chart 3D uses the standard AWT/Swing event/listener mechanism for passing changes between the chart data source and JClass Chart 3D. At a very high level, JClass Chart 3D is a listener to data source events that are fired by the data source.

5.10.1 Chart Data Source Support Classes

There are a number of data source related support classes included with JClass Chart 3D. These classes make it easier to build updating data sources.

Chart3dDataEvent and Chart3dDataListener

The Chart3dDataListener interface is implemented by objects interested in receiving Chart3dDataEvents. Most often, the only Char3dDataListener is JClass Chart 3D itself. Chart3dDataEvent and Chart3dDataListener give data sources a way to send update messages to JClass Chart 3D.

The Chart3dDataListener interface has only one method:

public void chart3dDataChange(Chart3dDataEvent e);

Thus, this mechanism uses the Chart3dDataEvent class to inform the listener of a change. In most systems, only JClass Chart 3D need implement this interface. The Chart3dDataView is the class that implements the Chart3dDataListener interface within JClass Chart 3D.

The Chart3dGridDataEvent class, which extends Chart3dDataEvent, is used to encapsulate a JClass Chart 3D grid data change event. This class has two methods: getX and getY. getX returns the X-index of the affected data, returning JCData3dIndex.ALL if all X-values are affected. getY returns the Y-index of the affected data, returning JCData3dIndex.ALL if all Y-values are affected.

The Chart3dPointDataEvent class, which also extends Chart3dDataEvent, retrieves the point index associated with the event. This class has two methods: getPoint and getSeries. getPoint returns the index of the point affected, returning JCData3dIndex.ALL if all points are affected. getSeries retrieves the series index associated with the event, returning JCData3dIndex.ALL if all points are affected.

The Chart3dDataEvent has a type property that indicates the message type of the event. The message type delineates what type of update the data source has made.

Properties of the Chart3dDataEvent class - note that these properties are relevant for both grid and point data:

Message Type	Meaning
RELOAD_DATA_SOURCE_NAME	Enum value indicating the data source name is attached.
RESET	Enum indicating that everything - data, labels, name, etc - has changed.
RELOAD	Enum indicating that the data needs to be reloaded.
RELOAD_HOLE_VALUE	Enum value indicating the hole value is affected.

Properties in the Chart3dGridDataEvent class:

Message Type	Meaning
RELOAD_ALL_XLABELS	Enum value indicating all xLabels are affected.
RELOAD_ALL_YLABELS	Enum value indicating all yLabels are affected.
RELOAD_XGRID	Enum value indicating all X-values are affected.
RELOAD_XLABEL	Enum value indicating a particular xLabel is affected.
RELOAD_XVALUE	Enum value indicating a given X-value is affected.
RELOAD_YGRID	Enum value indicating all Y-values are affected.
RELOAD_YLABEL	Enum value indicating a particular yLabel is affected.
RELOAD_YVALUE	Enum value indicating a given Y-value is affected.
RELOAD_ZALL	Enum value indicating the entire doubly indexed array of zValues is affected.
RELOAD_ZARRAY	Enum value indicating one array of zValues is affected.
RELOAD_ZVALUE	Enum value indicating one z Value is affected.

Properties in the Chart3dPointDataEvent class:

Message Type	Meaning
ADD_SERIES	Enum value indicating a data series has been added to the end of the set of data series.
INSERT_SERIES	Enum value indicating a data series has been inserted at a particular index in the set of data series.
RELOAD_ALL_SERIES_LABELS	Enum value indicating all series labels need to be reloaded.
RELOAD_POINT	Enum value indicating a single data value has changed.
RELOAD_SERIES	Enum value indicating a data series has changed.
RELOAD_SERIES_LABEL	Enum value indicating a particular series label needs to be reloaded.
REMOVE_SERIES	Enum value indicating a data series has been removed.

Chart3dDataManager

The Chart3dDataManager interface is used by a data source to tell JClass Chart 3D that it will be sending a Chart3dDataEvent to JClass Chart 3D. Without this interface, there is no way for JClass Chart 3D to know that it has to attach itself as a Chart3dDataListener to the data source.

The two methods involved to add and remove a JClass Chart 3D data listener:

• addChart3dDataListener(Chart3dDataListener n) - adds a chart 3D data listener.
• removeChart3dDataListener(Chart3dDataListener n) - removes a chart 3D data listener.

A Chart3dDataManager is an object that knows how to register and deregister Chart3dDataListeners. Chart uses this object to register itself as a listener to events from the data source.

The quickest way to get such a data source set up is to extend or use the Chart3dDataSupport class.

Chart3dDataSupport

Chart3dDataSupport provides a default implementation of Chart3dDataManager. It will manage a list of Chart3dDataListeners. It also provides two convenience methods for firing events to the listeners.

The first fireChart3dDataEvent method fires a chart data event to any registered listeners. This version of fireChart3dDataEvent will create a Chart3dDataEvent object out of the message and a JCData3dIndex. For example:

public void fireChart3dDataEvent(int type, JCData3dIndex index)

where type is a valid message type from Chart3dDataEvent, Chart3dGridDataEvent, or Chart3dPointDataEvent, and index is the data index which tells which (x, y) or (series, point) to which this event refers.

If you already have a Chart3dDataEvent, the second fireChart3dDataEvent method fires this event to any registered listeners. For example:

public void fireChart3dDataEvent(Chart3dDataEvent evt)

where evt is the event to send to registered listeners.

Creating an Updating Data Source

If your datasource either extends or contains Chart3dDataSupport, sending updates from the data source to the chart is easy. Simply call fireChart3dDataEvent() with the event you wish to send.

fireChart3dDataEvent(Chart3dDataEvent.RESET,
  new JCData3dGridIndex(x,y));

To have JClass Chart 3D automatically added as a listener, your data source needs to implement the Chart3dDataManager interface.

If you do implement this interface, then the Chart3dDataView object will automatically register itself as a listener when you set the data source on either its elevationDataSource or zoneDataSource. Note that the listener will remove itself when another data source replaces your data source in the data view.

---

5.11 Summary of JClass Chart 3D Data Interfaces

Characteristic	Base	Grid Data	Point Data
Data	Chart3dDataModel	Chart3dGridData Model	Chart3dPointDataModel
Hole value	HoleValueChart3dDataModel	none	none
Labels - data source name	LabelledChart3dData Model	LabelledChart3d GridDataModel	LabelledChart3dPoint DataModel
Setting new Z values	EditableChart3dData Model	none	none
Managing listeners	Chart3dDataManager	none	none
Listening for data events	Chart3dDataListener	none	none