Java Table Programmers Guide

Programmers Guide for the Java Table Component

Purpose................................................................................................................................ 2 Introduction......................................................................................................................... 2 Creating the Table............................................................................................................... 2 Using Metadata API............................................................................................................ 4 Creating and Adding rows to the Table .............................................................................. 5 Retrieving Rows.................................................................................................................. 6 Deleting Rows..................................................................................................................... 6 Deleting Duplicate Rows .................................................................................................... 7 Sorting................................................................................................................................. 8 Setting / Getting Values in TableRow ................................................................................ 9 Using the JDBC Table ...................................................................................................... 10 References......................................................................................................................... 11

Purpose
This guide is intended to assist users in the development and deployment of web applications using the Java Table version 1.0.

Introduction
The Java-Table is a data-structure that helps represent tabular data models in memory. It can serve as a layer over existing database driver implementations for storing tabular data retrieved from databases. The implementation definitions are centered on providing facilities to developers who want to manipulate tabular data at an abstract level and pass this data between distributed tiers and components. The current JDBC API provides an environment for creating and manipulating tabular data associated with tabular data stores. Implementations of the Table interface extend this model to allow tabular data to be manipulated and passed between tiers and components.

Creating the Table

The Table object in the Java-Table component provides the main APIs for using the JavaTable data-structure. The Table consists of a set of rows and named columns. Hence it provides APIs for creation, removal, insertion and retrieval of rows. The number of rows and columns required can be specified during the creation of the Table itself. Also the number of rows is dynamic, hence a user can add more rows than the capacity specified during creation A Table object can be created using the Table Factory. The TableFactory provides APIs for specifying the table name, the number of columns and the columns to be used as keys for the table. The Table factory also provides a factory method where the types for the columns can be specified. The following is an example where a Table is created with the number of columns and the columns to be used as keys. In the below API, no names are associated to the columns, hence the column numbers will be used as the column names (starting with 0)
// name of the table String name = "Employee-Table"; // employee-id, name, age int columns = 3; // this means only the first column is used as the unique key int[] unique_key = {0}; // create the table Table table = TableFactory.createTable(name, columns, key);

A table can also be created by specifying column types to each of the columns. In the case of the above API, the column types are defaulted to a SimpleColumnType. American Express Page 2 9/15/2003

Column types are specified by specifying an array of column type objects that can be passed to the Table creation factory method. The size of the array is treated as the number of columns in the Table. The names of the column type objects specified in the array are used as the names of the table columns. Hence each object specified in the column type must be a unique object (there can be more than one column type references in the array which point to the same object, because this means there are more than one column with the same name). All column type objects extend the com.americanexpress.util.gdao.ColumnType interface. The various column type objects supported by the component are SimpleColumnType, NonNullColumnType and TypedColumn. Creation of a Table which has all the above three column types is shown below.
/* * This method creates a Table using the TableFactory. It creates a * Table with three columns. The firs column is a non-null, the second * column is a simple type and the third column is typed for Integer. * This means the third column will cause a TableRow validation to * return false in case a non Integer value is inserted * * The key includes the non-null value (I column) as the unique key. * */ public void createTable() { // Table name for a customer table String name = "Employee Table"; // create three distinct column types SimpleColumnType simp = new SimpleColumnType("Simple"); SimpleColumnType s-non-null = new SimpleColumnType("Non-Null"); NonNullColumnType nonNull = new NonNullColumnType(s-non-null); SimpleColumnType s-typed = new SimpleColumnType("Typed-Integer"); Class clazz = Integer.class; TypedColumn typed = new TypedColumn (s-typed, clazz); // three columns ColumnType[] columnTypes = {NonNull, simp, typed }; // the non-null column is the key here int[] keys = {0}; // create a table with the column types Table table = TableFactory.createTable(name, columnTypes, keys); }

American Express

Page 3

9/15/2003

Using Metadata API

The Table provides many APIs which allow users to operate on the metadata associated with it. The Table provides APIs to retrieve the name of the table the number of columns the size of the table (number of rows) the names of columns and the types of the columns the maximum limit of the table size The name of the table can be retrieved using the API getName() which returns the name of the table specified during construction. The getColumnCount() API returns the number of columns in a table. The getSize() method returns the size of the table, i.e. the number of rows that have been added into the table.
int n_columns = table.getColumnCount();

The column types can be obtained by using the getColumnType() method. The getColumnType(int pos) method is based on the position of the column. The method returns the column type object for the position that is specified. The name of the column can also be obtained from this column type object.
// retrieve the column type at position 1 ColumnType type = table.getColumnType(1); // get the name of the column in that position type.getName();

It is also possible to set the column type at run time. This is possible by using the setColumnType() method. Using this method a ColumnType object can be attached to a specified position in the table, i.e. column.
ColumnType simpleColumn = new SimpleColumnType("Simple"); table.setColumnType(0, simpleColumn);

The table.getRowLimit() returns the maximum limit on the number of rows allowed in a table. The value of this by default is Integer.MAX_VALUE (2 billion rows!!). The developer can set the limit to something reasonable by calling the setRowLimit method. In case the row limit is set and the program tries to populate the table exceeding the set size, the add method ignores the rows and returns a false.

American Express

Page 4

9/15/2003

Creating and Adding rows to the Table

Once a table is created, TableRow objects can be created and added to the table. The Table row object provides methods for accessing individual objects stored in the row based on the position of columns and based on the name of the column. It also provides methods for setting values to objects based on the column position or name. The following example creates and adds ten rows to the above table.
for(int i=0; i<rows; i++) { // create a row for the table TableRow row = table.createRow(); // set the employee id row.setColumn(0, new Integer(i)); // add the row to the table table.add(row); }

It is also possible to add a row to a specified position in the table. In this case, the new element is added to the position specified and the row already present in the position and the subsequent rows are shifted by one position.
// create a row for the table TableRow row = table.createRow(); // set the employee id row.setColumn(0, new Integer(12345)); // add the row to the table at position 1 table.add(row, 1);

By default the add methods allow adding unlimited number of rows (Integer. MAX_VALUE). But this size of the table can be limited by calling the setRowLimit method. In the case where this flag is set and the size of the table exceeds the limit, no further rows are added to the table. The Table implementation by default provided the facility to add duplicate rows into the table. But this can be configured so that the table does not allow duplicates. The disableDuplicates method is called to disable the addition of duplicate rows to the table. Duplicate rows are those rows which have identical values for the columns which are specified as Keys. When the disableDuplicates method is called, the table add method ignores duplicate rows and returns false. The table can be made to allow duplicates by calling the method enableDuplicates(). Configuring the table to restrict duplicate rows helps maintain unique values for rows in the table. Also the get and remove methods can be called to retrieve and remove these unique rows.

American Express

Page 5

9/15/2003

Retrieving Rows
It is possible to retrieve the set of rows added to the table based on their position in the table or based on a unique key which can be specified. The unique key to be specified can be created from the table API by specifying a set of values for the key. The example below demonstrates the APIs for row retrieval. The createKeyInstance API in the table can be used to create a key object which can be used for retrieval of rows from the table.
// the second row has a value 1 for the key Object[] values = {new Integer(1)}; // create a key from the table for this value Key key = table.createKeyInstance(values); // retrieve the entire row for this key TableRow row = table.get(key); // since the position of this row is also known, i.e. position 1, // we can directly invoke the position based API to retrieve this // row. TableRow row = table.get(1);

The get method returns a unique value for the key specified in case the table is set up not to allow duplicates. The Table ALLOWS DUPLICATE VALUES by default. In this case, we could have more than one row with identical values in the key columns. In this case, the get method returns the last added row which has the key identical to the key specified. When the table.disableDuplicates() has been called, each key has one and only one row.

Deleting Rows
This API is similar to the methods used for retrieval. Rows can be deleted based on their position in the table or by specifying the unique of the row to be deleted. The example below demonstrates the APIs for row deletion. The createKeyInstance API in the table can be used to create a key object for deletion also. It is also possible to delete all the rows in the table. This is achieved by using the clear() API in the table
// the second row has a value 1 for the key Object[] values = {new Integer(1)}; // create a key from the table for this value Key key = table.createKeyInstance(values); // retrieve the entire row for this key TableRow row = table.remove(key); // In case the position of a row is known, i.e. position 2, etc // we can directly invoke the position based API to remove this // row. TableRow row = table.delete(2); //delete all the rows table.clear()

American Express

Page 6

9/15/2003

The remove(key) method deletes a unique value for the key specified in case the table is set up not to allow duplicates. The Table ALLOWS DUPLICATE VALUES by default. In this case, we could have more than one row with identical values in the key columns. In this case, the remove(key) method deletes the last added row which has the key identical to the key specified. When the table.disableDuplicates() has been called, each key has one and only one row.

Deleting Duplicate Rows

The Table API supports deletion of rows in the table by comparison. If there are rows in the table which are logically duplicated as per a specification, then these rows can be deleted by calling the method deleteAdjacentDuplicates(). There are three overloaded variants of this API available. The deleteAdjacentDuplicates() API which does not accept any parameters deletes duplicate rows in the table by comparing the unique key values. In case the method finds more than one row which has the same values for the unique keys, the redundant rows are deleted. In this case, the first row which was added is retained and all other duplicates are removed from the table. The deleteAdjacentDuplicates(Comparator c) API which accepts a comparator deletes duplicates rows after comparing the rows by using the comparator algorithm passed to the method. The third variant of this API is deleteAdjacentDuplicates(String s), which accepts a string as the specification for comparison and deletion. The specification needs to mention the columns that we need to compare to identify duplicate rows. The specification starts with the Comparing string. An example usage is shown below.
String name = "My Table"; int[] keys = {0,1}; SimpleColumnType simple1 = new SimpleColumnType("Column1"); SimpleColumnType simple2 = new SimpleColumnType("Column2"); ColumnType[] columns = {simple1, simple2 }; // create the table Table table = TableFactory.createTable(name, columns, keys); // specification to compare column 2 values for similarity String spec = "COMPARING Column2"; // insert 10 similar rows int rows = 10; for(int i=0; i<rows; i++) { // create a row TableRow row = table.createRow(); row.setColumn(0, new Integer(i));

American Express

Page 7

9/15/2003

// set the same value to column #2 of all 10 rows row.setColumn(1, new Integer(0)); // add the rows to the table table.add(row); } // delete the adjacent duplicated. The result should be 9 // because there are 10 duplicate rows int deletedRows = myTable.deleteAdjacentDuplicates(spec);

Sorting
The Table API supports sorting of rows in the table by comparison. Rows in the table can be logically sorted as per a specification, by calling the method sort() method. There are three overloaded variants of this API available. The sort() API which does not accept any parameters sorts rows in the table by comparing the unique key values. The sort(Comparator c) API which accepts a comparator sorts rows after comparing the rows by using the comparator algorithm passed to the method. The third variant of this API is sort(String s), which accepts a string as the specification for comparison and deletion. The specification needs to mention the columns that we need to compare for sorting. The specification starts with the ORDER BY string and specifies the columns to be compared for sorting. An example usage is shown below.
SimpleColumnType simple1 = new SimpleColumnType("Column1"); SimpleColumnType simple2 = new SimpleColumnType("Column2"); ColumnType[] columns = {simple1, simple2 }; Table myTable = TableFactory.createTable(name, columns, keys); String spec = ORDER BY column2; // insert 10 dissimilar rows int rows = 10; for(int i=0; i<rows; i++) { // create a row TableRow row = myTable.createRow(); row.setColumn(0, new Integer(i)); row.setColumn(1, new Integer(i+1)); // add the rows to the table myTable.add(row); } // sort the rows myTable.sort(spec);

American Express

Page 8

9/15/2003

Setting / Getting Values in TableRow

The Table row object provides methods for accessing individual objects stored in the row based on the position of columns on based on the name of the column. It also provides methods for setting values to objects based on the column position or name. Users can set object values into a position in a column using the setColumn() method of the TableRow. There are two variants of this method. The first one is a position based method where the index of the column position can be specified to set the value. There is another method which accepts names of the column to set the value for a particular column.
SimpleColumnType simple1 = new SimpleColumnType("Column1"); SimpleColumnType simple2 = new SimpleColumnType("Column2"); ColumnType[] columns = {simple1, simple2 }; Table table = TableFactory.createTable(name, columns, keys); TableRow row = table.createRow(); // set an Integer value of 10 to the zeroth position of the row row.setColumn(0,new Integer(10)); // set a value of Age to the column Column2 row.setColumn("Column2", "Age"); table.add(row);

Similarly, users can also get the values of objects that are already set into the row using position and name based methods available in the TableRow object. The return values for the get methods are generic objects, hence these have to type-cast to their sub-types.
// set an Integer value of 10 to the zeroth position of the row Integer value1 = (Integer)row.getColumn(0); // set a value of Age to the column Column2 String age = (String)row.getColumn("Column2");

Additionally the TableRow object provides a method to create a Key object based on the values available in a TableRow. Users can call the getKey method to create a Key object from the TableRow.
// get a Key object for the values available in the row Key key = row.getKey();

The TableRow also provides a validate() method which is used to make sure that the values set into the various columns are of the correct type (Simple, NonNull, TypedColumn). The validate method returns false incase this rule is violated.
// validate a row to make sure the values are of proper types boolean isValid = row.validate();

American Express

Page 9

9/15/2003

Using the JDBC Table

The JDBC Table implementation of the Table extends the default implementation of the Table. The JDBC Table simply adds a constructor to the Table implementation which accepts a JDBC ResultSet. The JDBC Table iterates through the ResultSet which is passed to the constructor and creates TableRow objects for each row in the result set. The constructor then sets the values available in the ResultSet into the objects in the JDBC Table. The implementation also iterates though the column metadata for the JDBC ResultSet to identify the column types and sets the appropriate column type for the JDBC Table implementation. Except the new constructor that accepts a JDBC ResultSet, none of the other interface methods in the Table are overridden by the JDBC Table.
public void createJDBCTable() { String name = "JdbcTable"; int[] keys = {0}; String query = .. some database query; Connection connection = null; Statement statement = null; ResultSet rstSet = null; try { conn = DriverManager.getConnection("jdbc:axiondb:egdb"); stmt = conn.createStatement(); rstSet = stmt.executeQuery(query); } catch (SQLException sqle) { sqle.printStackTrace(); } try { //insert code testing basic functionality JdbcTableImpl jdbcTable = new JdbcTableImpl(name, keys, rstSet); } catch (Throwable e) { fail("Failed with:" + e); } // close the resources }

American Express

Page 10

9/15/2003

References
1) 2) 3) 4) 5) Java Table: K245 Requirements Document GDAF Requirements Java Table: Supplement for Requirements Review Session Java Table: Design Document Java Table: Java Documentation

American Express

Page 11

9/15/2003