Index of Porting Issues

General Issues Affecting All JClass 4.0 Products	Overview of the Changes in JClass 4.0 Cell Editor/Renderer Changes
JClass BWT	Swing and JClass SwingSuite replace BWT
JClass Chart	Porting Guide for JClass Chart
JClass DataSource	Porting Guide for JClass DataSource
JClass Field	Porting Guide for JClass Field
JClass HiGrid	Porting Guide for JClass HiGrid
JClass LiveTable	Porting Guide for JClass LiveTable
Other Migration Issues:
The jclass.contrib package:	removed from JClass 4.0
The jclass.util package:	has been split, replaced by JClass SwingSuite
The jclass.base package:	removed from JClass 4.0

Introduction

This paper lists the changes in the API between JClass 3.6 and JClass 4.0 versions, and suggests ways of rewriting 3.6-era code to conform with the 4.0 API.

JClass products have become well established in the Java component market. The versions prior to JClass 3.6 have been based on the Java 1.1 API, and in some cases could be used with JDK 1.0.2 as well. The JClass 3.6 release gives programmers the choice of a platform, either JDK 1.1 or Java 2, just as JClass 4.0 does. However, only the 4.0 version of JClass takes advantage of many features unique to Java 2, while supplying a JDK 1.1 version with as many backward-compatible functions as possible. Thus, Swing, PLAF, the Collections API, and more are integrated into JClass 4.0.

Sitraka achieved the following goals in its JClass 4.0 release:

• It makes internal use of javax.swing components. Application programmers can place support for look and feel in their products.
• Because it is based on Java 2, it is compatible with the latest Sun technology.
• It uses Java's Collections API, replacing the interim approach used in JClass 3.6.
• Code was reorganized to make it both simpler and more functional. This paper suggests the parts of typical end-user application code that may need changing.

• It allows you to customize the look and feel of your applications using current PLAF technology.
• It simplifies the data-binding mechanism, making it easier to bind components to data.
• It lets you use the functionality of Swing, augmented by JClass SwingSuite.
• JClass Chart has benefited from many improvements. For instance, any component can be placed in chart headers and footers.
• Components can be placed in the cells of a JClass Table.
• Data binding in JClass DataSource has been simplified.
• JClass HiGrid's feature set has been expanded and includes a new fine-grained event structure.
• It includes JClass PageLayout, a full-featured printing utility for Java 2.
• It includes JClass JarMaster, a JAR packaging tool.

Sitraka will continue to maintain and sell JClass 3. New versions, such as JClass 3.6.2, are essentially bug fixes, but the product itself will continue to be available. If then there is no reason to upgrade to JClass 4.0. On the other hand, if you are planning an upgrade to your existing application you need to assess whether moving to Java 2 is appropriate, and if so, you'll need to upgrade to JClass 4.0 as well.

JClass 4.0 is meant for new application development. Any new projects that you are planning likely will be based on the Java 2 platform, and consequently will need JClass 4.0.

If you decide to upgrade, this document provides information and helpful suggestions.

Overview of the Changes in JClass 4.0

The release of JClass version 4.0 products permits you to take full advantage of JFC and Swing, as well as ensures that all JClass components are compatible with Java 2.

What Changed	Why the Change
JClass 4.0 is designed for Java 2 but also works with JDK 1.1.5 + Swing 1.1.1 (and later). There are two distributions, a K version for Java 2 (JDK 1.2.2 and later) and a J version for JDK 1.1.5 + Swing 1.1.1 (and later).	JClass 4.0 lets you use the Java 2 platform, but works with JDK 1.1 as well, thus permitting a flexible migration path if one is needed.
Class 4.0 package names begin with com.klg.jclass rather than the older naming convention of simply jclass.	A package name of com.klg.jclass conforms with the now-standardized package naming convention.
JClass 4.0 is based on Swing, not on AWT.	Swing's component architecture is newer and more adaptable than the earlier AWT model.
There is no JClass BWT 4.0.	JClass BWT was designed to be a solution for improving on AWT's components until Swing became available. Now that Swing is here, Sitraka has produced JClass SwingSuite to provide components that are not in Swing. The combination of Swing and JClass SwingSuite is a rich visual component toolkit.
There is a new, easier-to-use binding mechanism for data bound components.	The JClass 4.0 data binding mechanism has been made simpler to use and more efficient. See the JClass DataSource Porting Issues, and Data Binding in JClass 4.0 for details.
Cell editor/renderer changes affect JClass Chart, JClass HiGrid, JClass Field, and JClass Table.	The new editor/renderer objects can contain other components.
Java's Collections classes are used.	Collections simplify coding.
JClass Chart has a new data model.	JClass Chart's new data model permits more flexible ways of providing the chart with data.
JCStrings have been replaced by HTML.	HTML is a standard formatting protocol. JCString is a proprietary Sitraka format that was useful until Swing implemented HTML formatting inside labels and text panes.
A common cell editor/renderer registry.	In JClass 3.6, both JClass HiGrid and JClass LiveTable contained default mappings from a type to its associated editor/renderer. In JClass 4.0, the mapping is shared, resulting in more consistent behavior.

How to Migrate

You'll see tables like the one above throughout this document. Some tables contain a third column suggesting how to migrate your code. If a more detailed explanation is required, a separate How to Migrate section follows the table, just as you see here.

Porting Steps

Generally speaking, you begin by examining your code to see whether you have to do any high-level design changes, such as those listed in following first three steps. Next, you take care of the details. There may be name changes for classes and methods. This guide contains sections for each JClass product. There you'll find a table listing the old and new names. You can follow the links to the API for complete details.

The recommended steps for porting your code to JClass 4.0 are:

1. Determine whether you need to be aware of Swing's MVC architecture. This is a consideration for those who are porting BWT to Swing and JClass SwingSuite. For more information, see Introducing the Swing Architecture.
2. Determine whether you need to be concerned with changes in data access. For example, JClass Chart has new paradigms for getting data into a chart that require a redesign that includes the names and locations of certain classes.
3. Determine whether you need to change the way events are handled. For example, JClass HiGrid has many new events. If your code has added a listener, you will need to modify it to take account of the new fine-grained event structure.
4. Install the new JClass 4.0 jar and ensure it is in your CLASSPATH.
5. If you are using the J version of a JClass product, your application may need to import the com.sun.java.util.collections JAR with your CLASSPATH set accordingly. You'll need the Swing 1.1 JAR as well. Most JClass 4.0 J products require these classes.
6. If you are using the K version of a JClass product, your application may require an import statement for javax.swing.*. For example, headers in a JClass LiveTable are JComponents, so if you are placing a JLabel in a header you'll need to import javax.swing.JLabel or use the Swing component's full package name.
7. In your source files, change the import code lines to reference the new packages. Example: com.klg.jclass.chart instead of jclass.chart.
8. Replace any JClass 3.6 component with its JClass 4.0 equivalent, if necessary. For example, JClass BWT's names are not the same as Swing's, although in many cases all that is required is to replace JC with J in the component's name.
9. Rename methods that have changed in the new classes. Change their parameters if necessary. Compile your code and use any error messages to guide you to the methods that you may have missed.
10. Check the API for the methods you are using to ensure that the functionality is what you want.

Cell Editor/Renderer Changes

What Changed

New renderers have been added to JClass 4.0. Now there is a shared editor/renderer registry for all JClass components.

Most classes now begin with JC.

The drawing-based rendering model (formerly called CellRenderer) is now called JCLightCellRenderer.

Why the Changes

Additional renderer types added to the flexibility of the products.

The naming scheme is consistent across JClass packages and products.

The getPreferredSize() method now takes a Graphics object. See the following table for details.

How to Migrate

Changes to the Cell Renderers

JClass 3.6	JClass 4.0	How to Migrate
jclass.cell.CellRenderer	com.klg.jclass.cell. JCLightCellRenderer	A JCLightCellRenderer paints directly in the area it is given rather than having a component manage the painting.
getPreferredSize(CellInfo, Object)	getPreferredSize(Graphics, JCCellInfo, Object)	If you have supplied your own renderer, you must modify it to pass the Graphics object as well as changing the name of CellInfo to JCCellInfo.
	There is now a new rendering model based on a component called JCComponentCellRenderer. Some of the default renderers now use this component instead of JCLightCellRenderer.	JCComponentCellRenderer allows use of a Swing Component as a template for drawing in multiple cells a graphic that look exactly like the component from which it is derived. This model is easier to use than the drawing-based model when component's appearance is needed. It automatically takes care of look-and-feel support in the renderer.
	JCComponentCellRenderer and JCLightCellRenderer have a common base class called JCCellRenderer.
ButtonCellRenderer	None	Write a component cell renderer, that is, one that uses a component such as a JButton to do the rendering, thus automatically handling PLAF issues.
CheckboxCellRenderer	JCCheckBoxCellRenderer	Change the name.
ChoiceCellRenderer	JCComboBoxCellRenderer	Change the name.
EllipsisCellRenderer	None	Use JCStringCellRenderer or JCLabelCellRenderer
ImageCellRenderer	JCImageCellRenderer	Change the name.
RawImageCellRenderer	JCRawImageCellRenderer	Change the name.
ScaledImageCellRenderer	JCScaledImageCellRenderer	Change the name.
StringCellRenderer	JCStringCellRenderer	Change the name.
WordWrapCellRenderer	JCWordWrapCellRenderer	Change the name.
None	JCHTMLCellRenderer	New renderer for HTML text.
None	JCLabelCellRenderer.	This new renderer for raw text uses Swing's JLabel for drawing.

Changes to the Cell Editors

The advanced cell editors and renderers have been removed. Users are expected to use JClass Field for this purpose.

The editing interface has changed slightly:

JClass 3.6	JClass 4.0	How to Migrate
BaseCellEditor. initialize(InitialEvent, CellInfo, Object)	initialize(AWTEvent, JCCellInfo, Object)	Pass the new event and cell info classes.
getPreferredSize(CellInfo,Object)	None. Use the component's preferred size.	Now you can ask the component what its preferred size is.
KeyModifier[]getReservedKeys()	JCKeyModifier[]getReservedKeys()	Use the new name.

Swing Replaces BWT

JClass BWT's lightweight peerless components were offered as a solution that application programmers and developers could use until Sun's Swing component set became available. Now that Swing has been released, JClass BWT is no longer being improved. Although JClass BWT continues to be supported by Sitraka, it will be phased out eventually. Now is a good time to rewrite your code to bring it in line with JFC and Swing. This section is aimed at helping developers to make the transition to Swing.

For the most part, Swing components can now be used in place of the earlier BWT components. The new JClass SwingSuite components, layout managers, and tools add functionality missing from Swing.

For a detailed discussion of JClass 4.0 and Swing, see the White Paper on JClass and Swing .

Swing Extensions

JClass SwingSuite, introduced to the JClass family shortly after the release of Swing, was designed specifically to enhance individual javax.swing components. JClass SwingSuite consists of a collection of JavaBeans, components, layout managers and handy utilities that augments the standard Swing components or provides additional components missing from Swing. For example, Swing provides checkboxes and radio buttons, but no spin boxes. In JClass SwingSuite, however, the JCSpinBox fills the need for components that allow the user to select a number or a String by clicking up or down arrows.

The following table lists the BWT component and its replacement using Swing. JClass SwingSuite possibilities are listed as well.

BWT Component	Swing Replacement	SwingSuite Improvement
JCAlignerLayout	None	JCAlignLayout
JCArrowButton	JButton with Arrow GIF
JCButton	JButton
JCCheckbox	JCheckBox
JCCheckboxGroup	JRadioButton	JCCheckboxList
JCComboBox	JComboBox
JCField	JTextField
JCLabel	JLabel
JCList	JList
JCMultiColumnList	JTable	JCSortableTable
JCOutliner	JTree	JCTreeTable JCTreeExplorer
JCProgressMeter	JProgressBar	JCProgressHelper
JCScrollBar	JScrollBar
JCScrolledWindow	JScrollPane	JCMDIPane
JCSeparator	JSeparator
JCSlider	JSlider
JCSpinBox JCSpinBoxString	None	JCSpinBox JCSpinNumberBox
JCSplitterWindow	JSplitPane
JCTabButton	JTabbedPane
JCTabManager	JTabbedPane
JCTextArea	JTextArea

Summary of Porting Issues

JClass BWT components (JCButton, JCComboBox, JCLabel, JCList, JCOutliner) use JCStrings to format text. If you need HTML-formatted text, you can add a component like Swing's JTextPane. (As well, JClass 4.0 has replaced JCStrings with HTML.)

Where a BWT component supported GIF images in its constructor, you use an Icon, such as ImageIcon, in Swing.

Some BWT components, like JCCheckBox, can be constructed by reading a value from an HTML parameter. Others, like JCList, JCSlider, JCTextArea, JCTextField, and JCField, can read applet tags. This functionality is not available in the equivalent Swing component.

JClass Chart 3.6 to 4.0

Overview

The major changes are listed in the table below, then each item is discussed in more detail with a recommended porting strategy.

What Changed and Why

What Changed	Why the Change
Package Name Change (com.klg.jclass.chart)	The old package name pre-dated naming standard.
New Applet Subpackage	Makes it easier to find applet load/save code. Important for users who wish to remove the applet code from deployment JARs.
New Beans Subpackage	Makes it easier to find Beans. Important for users who wish to remove the beans from deployment JARs.
Chart Label Components	Chart labels are no longer derived from components. Instead, they contain components. This is a more flexible scheme, since any JComponent-derived object can be used as a chart label.
Data Binding Changes	The data binding for JClass Chart has been rewritten, resulting in some minor API changes.
New Data Subpackage	Makes it easier to find stock data sources. Stock data source names now include the JC prefix. An improved container-style data source called JCDefaultDataSource is now included.
JCChartLabelManager	Not every user requires chart labels. To reduce download, chart label management is deferred to an object called JCChartLabelManager.
New Data Model	The old model dated back to JDK 1.0.2. New model is easier to understand.
No More JCString	JCString has been replaced by HTML in cells. You can format your text on a character-by-character basis if you wish.
Pluggable headers and footers	Headers and footers are now JComponents. This allows re-use of Swing code, and adds flexibility to the product. It also adds casts to your code.
A Swing-like API	JClass 4.0 is Swing-based. Applies to applet PARAM tags as well.
Use of collection classes	Collection classes were not available for JDK 1.0.2. Use of collection classes adds flexibility.

New Applet Subpackage

All code dealing with loading or saving of Chart as HTML PARAM tags has been moved to the com.klg.jclass.chart.applet subpackage. This change should be transparent to users. Deployment JARs for users not using HTML load/save can be made smaller by removing the applet subpackage.

Some parameter changes were necessary, mostly as a result of core chart API changes. These changes are shown below:

JClass Chart 3.6	JClass Chart 4.0
LeftMargin, TopMargin, BottomMargin, RightMargin	No equivalent
BorderType	No equivalent
BorderWidth	No equivalent
DoubleBuffer	No equivalent
Offset	No equivalent
IsShowing	IsVisible
IsShowingInLegend	VisibleInLegend
IsIncluded	Included
No equivalent	Join, Cap and Background in series.line
axis.IsVertical	axis.Vertical
axis.IsLogarithmic	axis.Logarithmic
axis.IsReversed	axis.Reversed
axis.GridIsShowing	axis.grid.visible
axis.Grid*	axis.grid.* Note that axis.grid now supports all line style properties, including patterns.
axis.IsEditable	axis.editable
chartLabel.attachX/Y	chartLabel.coord format: x,y
chartLabel.IsConnected	chartLabel.connected
chartLabel.IsDwellLabel	chartLabel.dwellLabel
candleChartFormat.isComplex	candleChartFormat.complex
HLOCChartFormat.isShowingOpen	HLOCChartFormat.showingOpen
HLOCChartFormat.isShowingClose	HLOCChartFormat.showingClose
HLOCChartFormat.isOpenCloseFullWidth	HLOCChartFormat.openCloseFullWidth

New Beans Subpackage

All the beans have been moved to the com.klg.jclass.beans subpackage. There have been no changes to Bean properties.

Chart Label Components

JCChartLabel is no longer a component, but contains a component. Therefore, all of the usual component methods like getBackground(), getFont(), and so on. need to be changed and prefaced by a call to getComponent(), for example:

getComponent().getBackground() Note that this allows a JClass Chart label to be any Swing component.

Data Binding Changes

The data binding beans remain in the same places. However, the dataBindingMetaData property has been replaced by dataBindingConfig.

New Data Subpackage

All stock data sources have been moved into a data subpackage. Some of the data source names have been changed. The next table explains the changes.

Chart 3.6 (jclass.chart)	Chart 4.0 (com.klg.jclass.chart.data)
No equivalent	BaseDataSource Common base class for most stock data sources
AppletDataSource	JCAppletDataSource
ChartSwingDataSource	JCChartSwingDataSource
VectorDataSource	JCDefaultDataSource Note that JCDefaultDataSource provides functionality that VectorDataSource did not
No equivalent	JCEditableDataSource Editable version of JCDefaultDataSource
FileDataSource	JCFileDataSource
InputStreamDataSource	JCInputStreamDataSource
StringDataSource	JCStringDataSource
URLDataSource	JCURLDataSource
JDBCDataSource	JDBCDataSource

New Data Model

The data model for Chart 4.0 is a change to a data series-based model from a table-based model used in Chart 3.6. As an example, consider charting the following data points:

(1,20)
(2, 70)
(3,50)

import jclass.chart.Chartable;
import java.util.Vector;
                         
public class simple implements Chartable {
                         
double xdata[] = {1, 2, 3,};
double ydata[] = {20, 70, 50,};
                         
public  int getDataInterpretation() {
return Chartable.ARRAY;
}
                     
public Object getDataItem(int row, int column) {
if (row == 0) {
return new Double(xdata[column]);
}
else if (row == 1) {
return new Double(ydata[column]);
}
return null;
}
                         
public Vector getRow(int row) {
Vector rval = new Vector();
if (row == 0) {
for (int i = 0; i < xdata.length; i++) {
rval.addElement(new Double(xdata[i]));
}
}
else if (row == 1) {
for (int i = 0; i < ydata.length; i++) {
rval.addElement(new Double(xdata[i]));
}
}
return rval;
}
                         
                         
public int getNumRows() {
return 2;
}
                         
                         
public String[] getPointLabels() {
return pointLabels;
}
}

In Chart 4.0, the corresponding code is much simpler:

import com.klg.jclass.chart.ChartDataModel;
                         
public class simple implements ChartDataModel {
double xdata[] = {1, 2, 3,};
double ydata[] = {20, 70, 50,};
                         
public double[] getXSeries(int index) {
return xdata;
}
                         
public double[] getYSeries(int index) {
return ydata;
}
                         
public int getNumSeries() {
return 1;
}
}

JClass Chart 3.6 allowed data models to update a chart via the Observer/Observable mechanism or the event/listener mechanism. Chart 4.0 only allows the event/listener mechanism.

Listed below are JClass Chart 3.6 data model classes and their equivalent in JClass Chart 4.0.

Version 3 Class Name	Version 4 Class or Interface Name
Chartable	ChartDataModel and LabelledChartDataModel
EditableChartable	EditableChartDataModel
ChartDataModel	ChartDataModel Observer/Observable is no longer used for updated chart data sources.
ChartDataListener	ChartDataListener
ChartDataEvent	ChartDataEvent
ChartDataSupport	ChartDataSupport
No equivalent	ChartDataManageable tells JCChart that an object can manage chart data listeners
No equivalent	ChartDataManager manages ChartDataListeners

Migration Reminder

Use JCDefaultDataSource as the starting point as you update your data sources. It handles JClass Chart's event listener relationship automatically and it has convenience methods for firing events.

JCChartLabelManager

JClass Chart 4.0 label management has been moved to an interface called JCChartLabelManager. If you implement your own delegate, it must be of type JCChartLabelManager. A default implementation called JCDefaultChartLabelManager is provided.

Use of the delegate results in a smaller deployment JAR for users who don't use chart labels. It also helps focus the JCChart API by removing the chart label-related methods.

Name in JClass 3.6	Now in JCChartLabelManager
void addChartLabel(JCChartLabel label)	Moved to JCChartLabelManager
void removeChartLabel(JCChartLabel label)	Moved to JCChartLabelManager
int getNumChartLabels()	Moved to JCChartLabelManager
void removeAllChartLabels()	Moved to JCChartLabelManager
JCChartLabel getChartLabels(int index)	Moved to JCChartLabelManager
void setChartLabels(int index, JCChartLabel label)	Moved to JCChartLabelManager
JCChartLabel[] getChartLabels()	JCChartLabelManager.getChartLabels()
void setChartLabels(JCChartLabel[] s)	JCChartLabelManager.setChartLabels(List s)

No More JCString

JCStrings have been replaced by HTML in cells. This is supported by Swing, and has been added to JClass Chart 4.0 where appropriate.

You can now put raw HTML into headers and footers, as long as the text starts with <html>. HTML is also valid in axis annotations, axis titles and legend elements.

Pluggable Headers and Footers

Headers and Footers can now be any JComponent-derived object. By default, JCChart.getHeader() and JCChart.getFooter() return objects of type JComponent, which by default are JLabels. This means a cast is required. Code that used to look like this:

chart.getHeader().setText("Foo")

JLabel header = (JLabel)chart.getHeader();
header.setText("Foo");

Swing-like API

JClass Chart's header, footer, chart area, legend, and chart itself are all derived from JComponent. The following changes to methods apply:

Method Name	Description of the Change
get/setBorderType()	Replaced by JComponent.setBorder() Note that enum-based replacements for standard Swing borders from BorderFactory may be created.
Various draw() methods, for example, draw() (in JCChartArea)	Now using Swing's paint mechanism.
get/setBorderWidth()	In Swing, borders have their own width.
get/setHeight() get/setWidth() get/setLeft() get/setTop(), and related IsDefault methods	All replaced by Component.setBounds(), Component.setLocation(), and Component.setSize(). In Chart 4.0, layout options for chart area, legend, header and footer are somewhat more limited. However, JCChart will now accept new layout managers. Also, JCChart allows specification of layout hints for header, footer, chart area and legend using JCChart.setLayoutHints().
get/setIsShowing()	Component.get/setVisible()
setInsets()	No direct equivalent. Use borders.

Important:
In general, any property in Chart 3.6 that started with "Is" has been modified. Changes include:

General Property Type	Property Name in Version 3.6	Property Name in Version 4.0
IsShowing/Visible	ChartDataViewSeries.IsShowing	ChartDataViewSeries.Visible
	ChartDataViewSeries.IsShowingInLegend	ChartDataViewSeries.VisibleInLegend
	ChartDataView.IsShowingInLegend	ChartDataView.VisibleInLegend
	JCAxis.GridIsShowing	JCAxis.GridVisible
	JCAxis.IsShowing	JCAxis.Visible
	JCAxisTitle.IsShowing	JCAxisTitle.Visible
IsIncluded	ChartDataViewSeries.IsIncluded	ChartDataViewSeries.Included
IncludedIsEditable	JCAxis.IsEditable	JCAxis.Editable

Migration Reminder

Now that JCChart is a Swing component, you must first call chart.setOpaque(true) if you want the call chart.setBackground(color) to work as it does in JClass Chart 3.6.

Use of Collection Classes

JClass Chart aggregates objects like JCAxis, ChartDataView, ChartDataViewSeries using Collections. In Chart 3.6, Vectors were used. The API has been updated to take advantage of the flexibility offered by Collections.

In most cases, JClass Chart would build the object arrays manually. Collections (and their iterators) allow JClass Chart to expose the internal collection directly.

Changes include:

JClass Chart 3	JClass Chart 4
String[] ChartDataView.getPointLabels()	List ChartDataView.getPointLabels()
ChartDataViewSeries[] ChartDataView.getSeries()	List ChartDataView.getSeries()
JCChartStyle[] ChartDataView.getChartStyle()	List ChartDataView.getChartStyle()
ChartDataView[] JCChart.getDataView()	List JCChart.getDataView()
JCChartLabel[] JCChart.getChartLabels()	List JCChartLabelManager.getChartLabels() List JCDefaultChartLabelManager.getChartLabels()
JCAxis[] JCChartArea.getXAxis()	List JCChartArea.getXAxes()
JCAxis[] JCChartArea.getYAxis()	List JCChartArea.getYAxes()

For convenience, many of the index-based accessors remain. For example, you can still obtain a reference axis based on an index:

JCAxis xaxis = chart.getChartArea().getXAxis(1);

Collections allow users to take advantage of iterators. In Chart 3.6, iterating over all the x axes required the following code:

JCAxis[] xaxes = chart.getChartArea().getXAxis();
for (int i = 0; i < xaxes; i++) {
JCAxis xaxis = xaxes[i];
// Do something interesting
}

In Chart 4.0, iterators can be used:

for (ListIterator li = chart.getChartArea().getXAxes().listIterator();
i.hasNext();) {
JCAxis xaxis = (JCAxis)li.next();
}

JClass DataSource Porting Issues

What Changed

What has not changed is the underlying data model API, except that the Swing tree model has replaced the JClass DataSource tree model. This change should be invisible to most applications.

Like JClass DataSource 3.6, JClass DataSource 4.0 has two capabilities: a data model and data binding. The data model is an API for the management of hierarchical data. Data binding is built on top of the data model and presents convenience classes used to bind JClass Chart, JClass LiveTable and JClass Field to the data model. JClass HiGrid connects directly to the data model, so it has no need to concern itself with the additional data binding mechanism.

Why the Change

Programmers wanting to do single-level binding, using components such as JClass Field, JClass LiveTable or JClass Chart, still have to think and program hierarchically when using JClass DataSource 3.6, even though they should not have to know about the inherent hierarchical nature of JClass DataSource to bind single-level controls.

How to Migrate

The JClass 3.6 method of data binding still works however, with the 4.0 version you can create a data source, connect a field/table to it and add listeners to a single level. The components themselves do not need to know about any level other than the one they are interested in. This means they only receive events which directly affect the data in their level, or cascading events which affect their level. This simplifies the way that data-display components are programmed.

Since the data binding API is not public in JClass 3.6, there is no need to ensure backwards compatibility. JClass Field, LiveTable and Chart binding have been updated to use the new API. To hide the hierarchical underpinnings of the DataSource, there is now a class called com.klg.jclass.datasource.Binding. This class, along with those derived from it like JDBCBinding, creates the DataModel and MetaDataModel objects for the user. Here is an example which creates two levels in JDBC:

JDBCBinding orders = new JDBCBinding(c, "select * from Orders");
// pass parent, orders, to new child to establish the hierarchy
JDBCBinding details = new JDBCBinding(c, "select * from OrderDetails", orders);

You would then create the component by either passing in the instance of Binding, or explicitly setting it as in these examples which bind a TextField component:

DSdbJTextField orderId = new DSdbJTextField(orders, "OrderID");

or

DSdbJTextField orderId = new DSdbJTextField(); orderId.setDataBinding(orders, "OrderID");

Data Binding in JClass 4.0

What Changed

The data-binding mechanism was changed in JClass 4.0. This change affects all data-bound components.

Why the Change

In JClass 3.6, the data-binding mechanism propagated events like AWT did in JDK 1.0.2. That is, it broadcast events to all listeners; it was a listener's responsibility to determine if the event was of interest.

In JClass 4.0, the event model has changed so components only receive events of interest to them using the delegation event model in JDK 1.1 and Java 2. Only components registered as listeners on a particular level receive that level's events. Components now register as listeners on a Binding level. The Binding itself registers once as a listener on the data model. It then passes through only those events which affect its bound components. This is more efficient because the events only go to interested components. This reduces the complexity of the components' binding since they don't have to do the filtering.

This change does not affect you unless you have written your own data bound components.

JClass Field 3.6 to 4.0

There have been significant structural changes to JClass Field in its 4.0 version. These modifications allow more flexibility and control over the composition of fields. Although the changes are noteworthy, you can easily convert any code created with previous versions to version 4.0. The following sections describe how to upgrade your code to JClass Field 4.0.

What Changed and Why

In earlier versions of JClass Field, each field consisted of a visual component together with a validator. The validator portion determined what type of data the field expected. The names of the fields indicated their visual aspect and supported data type. For example, a text field that contained integers and a text field that held string values were named JCIntTextField and JCStringTextField respectively.

This meant that every time you added a new component to your application you also had to supply a new combination of an editor and a validator.

Now the five basic styles of visual components, which are represented by one of JClass Field's standard Beans: JCTextField, JCSpinField, JCComboField, JCPopupField, and JCLabelField, are separated from the validators and the supported data types. To use a field, you must associate it with a validator and declare an appropriate value model. The following table lists a few examples of the combination of components, validators and value models in JClass Field 4.0 that are equivalent to fields in earlier versions:

Component in JClass Field 3.6	Equivalent Component in JClass Field 4.0
JCIntTextField	JCTextField + JCIntegerValidator + IntegerValueModel
JCTimeSpinField	JCSpinField + JCTimeValidator + TimeValueModel
JCStringComboField	JCComboField + JCStringValidator + StringValueModel
JCCalendarPopup	JCPopupField + JCDateTimeValidator + CalendarValueModel
JCCurrencySpinField	JCSpinField + JCDoubleValidator + DoubleValueModel + isCurrency property set to true

You can duplicate all the fields contained in earlier versions by selecting the corresponding field, validator and value model. In fact, you can create even more fields since JClass Field 4.0 expands the list of supported validators to include java.lang.byte, java.lang.short, java.lang.long, java.lang.float, java.math.BigDecimal, java.sql.date, and java.sql.timestamp, and introduces a new GUI component, JCLabelField. This new field can be used to simulate a heading or to display uneditable data.

Code Differences

The following table shows the differences in code between JClass Field 4.0 and previous versions for a text field containing a string value.

JClass Field 3.6	JClass Field 4.0
JCStringTextField	JCTextField + JCStringValidator + StringValueModel
1 JCStringTextField text1 = new JCStringTextField();	1 JCTextField text1 = new JCTextField();
2	2 JCStringValidator sv = new JCStringValidator();
3 text1.setMask("(@@@) @@@-@@@@");	3 sv.setMask("(@@@)@@@-@@@@");
4 text1.setPlaceHolderChars("(___) ___-____");	4 sv.setPlaceHolderChars("(___)___-____");
5 text1.setValue("4165941026");	5 text1.setValueModel(new StringValueModel("4165941026"));
	6 text1.setValidator(sv);

Converting Your Code

This section breaks down the above code listings and gives a line-by-line description of the differences.

Line 1	Similar for both versions; it simply creates the field named text1.
Line 2	Declares the validator required by version 4.0.
Line 3	Sets the mask property for the field in earlier versions and for the validator for version 4.0.
Line 4	Sets the placeHolderChars property for the field in earlier versions and for the validator for version 4.0.
Line 5	Sets the initial value of the field, using the value property in earlier versions and using the value model declaration in version 4.0. Although you do not have to set the value using the value model, the value model declaration and its association with the field are necessary.
Line 6	Associates the validator with the field in version 4.0.

Property Changes

Since the introduction of the validator and JCInvalidInfo objects, the properties have been divided among these two objects and the field component, which in earlier versions contained all the properties. The following table shows how the JClass Field 4.0 properties are allocated.

How JClass Field Properties are Redistributed in JClass 4.0:

Properties in JCValidator	Properties in JCInvalidInfo	Field Component Properties (same as earlier versions)
allowNull casePolicy currency currencyLocale currencySymbol (G) defaultDetail defaultEditFormats(G) defaultFormat(G) defaultValue displayList displayPattern editFormats editPattern firstValidCursorPosition(G) format increment invalidChars iPValidators locale mask maskChars maskInput matchPickList max millenniumThreshold min numMaskMatch parsedMask(G) pickList pickListIndex(G) placeHolderChars range (S) spinPolicy timeZone useIntlCurrencySymbol validChars	invalidPolicy invalidBackground invalidForeground beepOnInvalid	about background doubleBuffered editable enabled font foreground maximumSize minimumSize name preferredSize required selectOnEnter state (G) toolTipText

Summary of Porting Guidelines for JClass Field

The following list gives a general outline of the steps you should follow to port your code to JClass Field 4.0 from earlier versions.

• Determine the field, value model, and validator that correspond to your existing field. Create each of these objects and associate the value model and validator with the field.
• Separate any JClass Field properties you use into field component, validator and invalid properties.
• If you have any invalid properties, declare the field's JCInvalidInfo object and set the properties using the new invalidInfo.
• Set any other properties using the field component or validator objects.

Changes in Event Handling

JClass Field events also have undergone significant changes in version 4.0. The event listener that receives the events generated by the four editable fields is now called JCValueListener instead of JCFieldListener. Its methods are valueChanging() and valueChanged() instead of valueChangedBegin(), valueChangedEnd(), and stateIsInvalid.

Changes to any one of the fields are handled by invoking addValueListener(). You supply the code to implement the JCValueListener interface. If you need further information on how to register the method see addValueListener, removeValueListener in Chapter 3 of the JClass Field manual.

The methods of the JClass Field event listeners are compared below:

JCFieldListener: Event Methods (JClass Field 3.6)	JCValueListener: Event Methods (JClass Field 4.0)
JCFieldListener. valueChangedBegin	JCValueListener. valueChanging()
JCFieldListener. valueChangedEnd	JCValueListener. valueChanged()
JCFieldListener. stateIsInvalid	No equivalent (see below).

Although the stateIsInvalid() method is not available in JCValueListener, you can use a java.beans.PropertyChangeListener to determine the value of the state of a field.

Porting Guide for JClass HiGrid

JClass HiGrid has been significantly upgraded without sacrificing much of its backwards compatibility with the JClass 3.6 API. As with JClass DataSource, the replacement of the JClass 3.6-style tree model from the package to the core javax.swing.tree.treemodel interface should pose few problems unless you have explicitly used this low-level API.

If you have simply used the default functionality of JClass HiGrid 3.6, you may need only change the package name in your import statement: import com.klg.jclass.higrid.*;

The next table presents the changes that have an impact on porting issues. As well, if you have used JClass HiGrid as a JavaBean in an IDE, some of the information in the following table may prove useful.

What Changed	Why the change	How to Migrate
HiGrid Events are subdivided into more than a dozen separate classes.	By listening for a specific event your code is much simpler.	Add a listener for the specific event you wish to process. See the event classes in the JClass HiGrid 4.0 API for details.
Cell editor/renderer changes.	Editor/renderer changes for all JClass 4.0 products.	See Cell Editor/Renderer changes in this document.
Now uses Swing's tree model.	No need for a duplicate of a Java base class.	Change the import statement to javax.swing.tree.treemodel.
No more ItemSelectable interface	JClass HiGrid now has a fine-grained event structure.	Use row selection events.
getBeepOnInvalid.	The accessor for a Boolean property usually begins with "is."	Now named isBeepOnInvalid.
Property levelIndent.	In JClass 3.6 he property takes an integer parameter while in JClass 4 it is a Boolean. This simplifies the way tables are indented.	Now called levelIndented.
Spelling change for resetRuntimeGrid().	To match the spelling of DesignTime and PrintTime.	resetRunTimeGrid().
Name change for selectRow().	Changed to a more descriptive name. Its parameters remain the same.	toggleRowSelection().
Names of the JClass HiGrid JavaBeans have changed. HiGridBean HiGridBeanEvent HiGridExternalDS	Names now have the descriptive "JC" prefix.	JCHiGrid JCHiGridEvent JCHiGridExternalDS

Some classes have been moved or renamed.

What Changed	Why the change	How to Migrate
AggregateAll	More descriptive term.	BaseAggregate
Border	Also more descriptive.	HiGridBorder
DefaultScrollbar	Swing components are used in JClass 4.0.	Uses JScrollbar
EditStatusRenderer	Default convenience class added.	DefaultEditStatusRenderer
ErrorHandler	Default convenience class added.	DefaultErrorHandler
HiGridListener	Listeners match the new events in JClass HiGrid 4.0.	Large number of listeners in the com.klg.jclass.higrid package.
RowNodeHandler	Default convenience class.	DefaultDataModelListener
The jclass.higrid.bean package	The beans packages are significantly different.	The com.klg.jclass.higrid.beans package.

Note: Serialization files produced with a JClass HiGrid 3.6 Bean are incompatible with those in JClass HiGrid 4.0. You are not able to load, using a 4.0 product, a serialization file produced with a 3.6 product. Instead, you must use the newer jar to reconfigure properties, then save a new serialization file.

Porting Guide for JClass LiveTable

Grid/Table functionality

JClass LiveTable is a flexible table/grid control for tabular data that significantly surpasses the functionality offered by JTable, its Swing equivalent. JClass LiveTable's JCTable can dynamically display data from any external data source and offers numerous features unavailable in JTable, including spanning cells, frozen rows and columns, improved performance and built-in data binding. What's more, JClass LiveTable scales to the most demanding environments.

What Changed

JClass LiveTable 4.0 is significantly different from previous versions. This guide gets you started, but you will want to consult the JClass LiveTable Programmer's Guide and the API for complete details.

Why the Change

The focus of JClass 4.0 is to make any changes necessary to take full advantage of Swing, and to restructure the product for future expansion.

How to Migrate

LiveTable 4.0 comes with two tools designed to help you move from LiveTable 3.x to 4.0:

• JCLASS_HOME/bin/table3to4.pl is a perl conversion script. It is designed to convert about 60-80% of table code.
• com.klg.jclass.table.Table is a subclass of JCTable that supports the old LiveTable 3.6 API.

Package and Class Name Changes

The major changes are listed in the following table.

What Changed	Why the Change
Package name change (com.klg.jclass.table)	Old package name pre-dated naming standard.
Swing-like API	JClass 4.0 is Swing-based so that it remains current.
Data Subpackage	Makes it easier to find stock data sources. Stock data sources now include the JC prefix.
New Beans Subpackage	Makes it easier to find Beans. Important for users who wish to remove the Beans from deployment JARs.
Changes to the Beans API	Various Bean properties have been modified. Essentially, the JClass LiveTable 4.0 Beans are not backwards compatible. This porting guide does not talk about the Beans.
No More JCString	JCString has been replaced by HTML in cells.
JCTable and Table	In LiveTable 3.6, Table was the core class and JCTable was a backwards-compatibility class for LiveTable 2.* customers. In LiveTable 4.0, JCTable is the core class, and Table is a backwards-compatibility class for LiveTable 3.6 customers.
New Events	The events fired by LiveTable have been rationalized based on user feedback. The listener methods have been renamed to be consistent across all methods.
Cell Changes	JClass LiveTable now supports two different rendering models. Many renderers and editors were updated to make use of Swing and of the new rendering model. All stock editors and renderers use the JC prefix.

Highlights of Main Changes

Data Model Changes in JClass LiveTable 4.0

JClass LiveTable 3.6 Data Model Name	JClass Table 4.0 Data Model Name
TableData	TableDataModel

Otherwise, the interface is identical.

Data Source Changes in JClass LiveTable 4.0

The stock data sources that come with JClass LiveTable have been moved into a data subpackage called com.klg.jclass.table.data. Some of the names have been changed. The following table lists these changes:

JClass LiveTable 3.6	JClass Table 4.0
AppletDataSource	JCAppletDataSource
BeanFileDataSource	JCBeanFileDataSource
CachedDataSource	JCCachedDataSource
EditableCachedDataSource	JCEditableCachedDataSource
EditableFileDataSource	JCEditableFileDataSource
EditableVectorDataSource	JCEditableVectorDataSource
FileDataSource	JCFileDataSource
InputStreamDataSource	JCInputStreamDataSource
ResultSetDataSource	JCResultSetDataSource
TableSwingDataSource	JCTableModelDataSource
URLDataSource	JCURLDataSource
VectorDataSource	JCVectorDataSource

New Beans Subpackage and Bean Property Changes in JClass LiveTable 4.0

All the Beans have been moved to the com.klg.jclass.table.beans subpackage. There have been many Bean property changes, listed in the following table.

JClass LiveTable 3.6	JClass Table 4.0
about	same
advancedEditorRenderers	removed
allowCellResize	same
appearance	styles
autoScroll	same
background	suppressed
cellBorderType	part of styles
cellBorderWidth	same
cellSize	same
columnLabelDisplay	part of labelLayout
columnLabelSort	removed
columnLabelBorderType	removed
data	same
displayClipArrows
doubleBuffer	Removed
editHeightPolicy	same
editState	Part of styles
editWidthPolicy	Same
focusRectColor	focusColor
foreground	suppressed
frameBorderType	same
frameBorderWidth	same
frozenCellLayout	same
frozenColumns	Part of frozenCellLayout
frozenRows	Part of frozenCellLayout
horzSBDisplay	Part of sBLayout
jumpScroll	same
labelLayout	same
leftColumn	same
marginWidth	same
marginHeight	same
minCellVisibility	same
popupMenuEnabled	removed
printSettings	removed
resizeEvent	removed
resizeByLabelsOnly	allowResizeBy
rowLabelBorderType	removed
rowLabelDisplay	Part of labelLayout
sBLayout	same
selectedBackground	same
selectedForeground	same
selectIncludeLabels	same
selectionPolicy	same
spanningCells	spannedCells
textPositioning	part of styles
topRow	same
trackCursor	same
traverseCycle	same
vertSBDisplay	part of sBLayout
New:	focusIndicator

No More JCString

JCStrings have been replaced by HTML in cells. This is supported by Swing, and has been added to LiveTable where appropriate.

You can now put raw HTML into headers and footers, as long as the text starts with <html>. HTML is also valid in axis annotations, axis titles and legend elements.

Style-based Property Setting

Please refer to Building a Table for details on style-based property setting. Styles are objects that encapsulate all the visual attributes of cells. You set the property for the style object, then apply it to a range of cells.

In LiveTable 3.6, each visual attribute was set individually on a range of cells. For example, the following code sets the foreground and background color on a range of cells:

table.setForeground(1, JCTableEnum.ALL, Color.blue);
table.setBackground(1, JCTableEnum.ALL, Color.black);

Using styles, the attribute is set on the style, and the style is applied to the cells:

JCCellStyle style;
style.setForeground(Color.blue);
style.setBackground(Color.blue);
table.setCellStyle(1, JCTableEnum.ALL, style);


In general, styles are easier to use for tables that tend to set multiple attributes on ranges of cells (the majority of cases for table users). Note that if you do not wish to use style-based property settings, you can use the Table class.

In JClass LiveTable 4.0, JCTable is the core class. Table is a subclass of JCTable that is to be used if you want to use JClass LiveTable 3.6 API calls. Table does not support the entire JClass LiveTable 3.6 API.

New Events

The new event structure has been rationalized and is documented in Events and Listeners. It is recommended that you rewrite your event handling code based on the new events.

Cell Editors and Renderers

See Editor/Renderer Changes. Note that in the JClass LiveTable 3.6, you could place multiple rows of text in a label by creating a string and embedding the "\n" character. In version 4, you can format text using a Swing component that accepts HTML tags.

Other Migration Issues

Package jclass.contrib has been removed in version 4.0

What Changed

In JClass 3.6, the jclass.contrib package contained some helpful utilities used by JClass demos and examples. Some of the utilities were created to allow a single component to handle Swing and non-Swing development. The package has been replaced by components in Swing and JClass SwingSuite.

Why the Change

In JClass 4.0, the jclass.contrib package is no longer needed.

How to Migrate

The following version 3.6 classes have changed their names or have been removed from version 4.0. Please consult the APIs for the old and the new classes to determine your porting strategy.

jclass.contrib Class Name	JClass 4.0 Equivalent
ContribApplet	javax.swing.JApplet
ContribCheckbox	javax.swing.JCheckBox
ContribCheckboxGroup	com.klg.jclass.util.swing.JCCheckBoxList
ContribDialog	javax.swing.JDialog
ContribFrame	com.klg.jclass.util.swing.JCExitFrame
JCChoice	javax.swing.JComboBox
JCColorUtil	No equivalent
JCDialog	javax.swing.JOptionPane.showConfirmDialog()
JCDialogCB	No equivalent. Pre-dates Java 1.1 event/listener model.
JCMenu	No equivalent.
JCMultiLineDisplay	javax.swing.JTextPane
JCOutlinePanel	javax.swing.JPanel with a titled border.
JCRelativeLayout	No equivalent.
JCSpreadLabel	No equivalent.
JCTitlePanel	javax.swing.JPanel with a titled border.

Package jclass.util has been changed in version 4.0

What Changed

There have been many changes in jclass.util. The majority of the classes have been been moved to com.klg.jclass.util and com.klg.jclass.util.swing, while others are now part of core Java.

Why the Change

Originally intended as a general area for useful classes, jclass.util quickly expanded to include too many classes. Some of the classes have been removed in 4.0, and others have been moved into more appropriate packages.

How to Migrate

The table below summarizes the changes:

jclass.util Class Name	JClass 4.0 Equivalent
BasePopupMenu	Moved to com.klg.jclass.util.swing
ConvertUtil	Methods moved to com.klg.jclass.util.JCTypeConverter.
GotoRowDialog	Moved to com.klg.jclass.util.swing.
JCAboutCanvas	No equivalent, however, this class is for internal use only.
JCAlignLayout	Moved to com.klg.jclass.util.swing.
JCCSVTokenizer	No equivalent.
JCCache	No equivalent, see collections API for possible replacements.
JCConverter	Methods moved into com.klg.jclass.util.JCTypeConverter and com.klg.jclass.util.swing.JCSwingTypeConverter.
JCEnvironment	Now in com.klg.jclass.util, but note changes to the API.
JCFile	No equivalent. Most functionality available via java.io.*.
JCFixedVector	No equivalent, see java.util.Vector and other core collections for equivalent.
JCHeapSort	Replaced by java.util.Collections methods.
JCImage	Replaced by javax.swing.ImageIcon.
JCImageCreator	Now called com.klg.jclass.util.swing.JCIconCreator
JCListenerList	Now called com.klg.jclass.util.swing.JCListenerList.
JCQuickSort	Replaced by java.util.Collections methods.
JCRectList	No equivalent.
JCRectUtil	Moved to com.klg.jclass.util.swing.
JCSortAlgorithm	Replaced by java.util.Collections methods
JCSortInteger	Effectively now part of java.lang.String via implementation of java.lang.Comparable interface.
JCSortInterface	Replaced by java.lang.Comparable.
JCSortString	Effectively now part of java.lang.String via an implementation of java.lang.Comparable interface
JCSortable	Replaced by java.lang.Comparable
JCString	No equivalent. Use HTML instead.
JCStringComponent	Replaced by javax.swing.JLabel. You can now render HTML-formatted rich text inside a JLabel by making sure "" appears at the start of the text.
JCStringTokenizer	Same name: JCStringTokenizer.
JCTitleLayout