com.ccg.io
Class TableProcessor

java.lang.Object
  com.ccg.io.TableProcessor

public class TableProcessor
extends Object

Base class to facilitate the processing of text tables.

Often it seems like one comes across tables of data that reside in ASCII files. These tables may resemble the form of a "tab separated value" file as shown below:

Last    First   Phone
Blankenbaker    Erik    555-555-7893
Blankenbaker    Paul    555-555-7839
Blankenbaker    Scott   555-555-8393
Brown   Megan   555-555-3923
 

This class greatly simplifies the processing of tables of this form. Basically it involves the following steps:

• The developer extends this class and overrides one or more of the following methods: processData(), processHeader(), exceptionData(java.lang.Exception, java.io.LineNumberReader), exceptionHeader(java.lang.Exception, java.io.LineNumberReader).
• You then create one of your derived objects and specify the table parser to be used for parsing the column data from each row in the table (the TextTable object works for tables that are of the tab separated value form).
• You then invoke the process(java.io.LineNumberReader) method, which does the rest and makes each row of data parsed available to your processData() handler.

A example program PhoneTable.java has been provided which demonstrates how one can use this to process text tables of different forms and layouts by appropriately mapping the locations of column headers. Developers are encouraged to examine this sample code to get a good idea of how this object is used to process table data.

Since:

1.0

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

TextTable, PhoneTable.java

Constructor Summary

TableProcessor(TextTable t)
Initializes the object with a table parser object.

Method Summary

boolean	exceptionData(Exception e, LineNumberReader lnr) Method which is invoked when a problem occurs processing a row of data.
boolean	exceptionHeader(Exception e, LineNumberReader lnr) Method which is invoked when a problem occurs processing column headers.
Exception	getDataException() Get the last exception which occurred while processing data.
Exception	getHeaderException() Get the last exception which occurred while processing header.
TextTable	getTable() Get the table definition object.
int	process(LineNumberReader in) Reads all rows from the text table (including column headers).
boolean	processData() Invoked for each row of data that has been parsed from the source table.
boolean	processHeader() Invoked when the initial header line of a table is being processed.
String	readLine(LineNumberReader lnr, StringBuffer joiner) Helper method to "smartly" join split lines together.
void	setDataException(Exception val) Set the last exception which occurred while processing data.
void	setHeaderException(Exception val) Set the last exception which occurred while processing header.
void	setTable(TextTable val) Set the table definition object.

Methods inherited from class java.lang.Object

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

Constructor Detail

TableProcessor

public TableProcessor(TextTable t)

Initializes the object with a table parser object.

You create a TableProcessor object (which is capable of processing the entire contents of a table) by providing it with a table parser (which is capable of parsing the columns from a single data row). After construction, you then use the process(java.io.LineNumberReader) method to process the contents of the table.

Parameters:

t - The table object used for parsing the column fields from each row read from the file. If you pass null, you should use the setTable(com.ccg.io.TextTable) method to set to a non-null value prior to invoking process(java.io.LineNumberReader).

Since:

1.0

See Also:

TextTable, process(java.io.LineNumberReader)

Method Detail

process

public int process(LineNumberReader in)

Reads all rows from the text table (including column headers).

This method will read the contents of a input source and process each row read. If the table has column headings, then the first row will be assumed to contain the table column headers and the processHeader() method will be invoked after it has been read. All subsequent rows will be assumed to be data rows and the processData() method will be invoked each time a data row is successfully parsed from the source.

See the class overview for more details on how a developer would extend this class. Also, don't forget to set the table prior to invoking this method (this is required by the constructor).

It should be noted that this method doesn't throw an exception. Instead it logs any exceptions encountered. You can use the getDataException() and/or getHeaderException() to determine if there were any problems during the processing of your data.

Parameters:

in - The input source to read the table data from (you can pass null in which case 0 is returned).

Returns:

Number of data rows successfully parsed and processed.

Since:

1.0

See Also:

readLine(java.io.LineNumberReader, java.lang.StringBuffer)

readLine

public String readLine(LineNumberReader lnr,
                       StringBuffer joiner)
                throws IOException

Helper method to "smartly" join split lines together.

This is the default implementation of the code which reads the next row of table data from the input source as a single line. It was discovered that tab separated value tables will sometimes split their lines if a field contains new line characters. This implementation tries to be "smart" about this situation and counts double quote characters (") on each line read. If there is a "open" quote after reading a line, it is assumed that more lines need to be read from the source and appended until all "quoted" fields are complete.

If you find yourself processing ASCII tables that don't follow this convention, you may need to override this method. However, this method seems to work for tables exported in the tab-separated-value form from Excel, Quattro Pro, Xess, and StarOffice.

Parameters:

lnr - Source to read the next line from.

joiner - Scratch buffer to build the line read from source (expect this buffer to be trashed after each invocation).

Returns:

Line read from the source

Throws:

IOException - If there was a problem reading line(s) from the source

Since:

1.0

See Also:

process(java.io.LineNumberReader)

processHeader

public boolean processHeader()

Invoked when the initial header line of a table is being processed.

This method is typically only invoked one time (at most) if the table being processed contains column headings at the start of the table. You can override this method to verify that the column headings are what you expect (return true if they are OK, or false if not).

It can be very handy/efficient to determine your column heading mappings at this point. By doing so here one time, you can greatly improve the efficiency at which your code parses the table data (I need to provide an example of this).

Returns:

true if column headings are OK, false if not (if you fail, you may optionally use exceptionHeader(java.lang.Exception, java.io.LineNumberReader) or setHeaderException(java.lang.Exception) to allow others to know why). This default implementation always returns true.

Since:

1.0

See Also:

processData()

exceptionHeader

public boolean exceptionHeader(Exception e,
                               LineNumberReader lnr)

Method which is invoked when a problem occurs processing column headers.

This method is invoked when there is a problem processing the column headers at the start of the table. If this method returns true, then processing will continue. If this method returns false, then processing of the table contents will stop.

You can override this method if you are interested in knowing when problems occur with the processing of the column headers.

Parameters:

e - An exception describing what went wrong

lnr - The source we were reading the data from.

Returns:

true if we should continue processing, false if not (this default implementation returns false).

Since:

1.0

See Also:

processHeader()

processData

public boolean processData()

Invoked for each row of data that has been parsed from the source table.

Each time a row has been parsed from the table, you can use this method to examine/process the data that was parsed. First use the getTable() method to get access to the object where the fields are stored, you can then access the data in specific columns using the standard TextTable methods.

Returns:

true if its OK to continue processing the next row read, false if we whould stop now (if you fail, you may optionally use exceptionData(java.lang.Exception, java.io.LineNumberReader) or setDataException(java.lang.Exception) to allow others to know why). This default implementation always returns true.

Since:

1.0

See Also:

processHeader()

exceptionData

public boolean exceptionData(Exception e,
                             LineNumberReader lnr)

Method which is invoked when a problem occurs processing a row of data.

This method is invoked when there is a problem processing a row of data in the table. If this method returns true, then processing will continue. If this method returns false, then processing of the table contents will stop.

You can override this method if you are interested in knowing when problems occur with the processing of data (or if you want to change the default behavior).

Parameters:

e - An exception describing what went wrong

lnr - The source we were reading the data from.

Returns:

true if we should continue processing, false if not (this default implementation returns false).

Since:

1.0

See Also:

processData()

setTable

public void setTable(TextTable val)

Set the table definition object.

Parameters:

val - New TextTable value to assign.

See Also:

getTable()

getTable

public TextTable getTable()

Get the table definition object.

Returns:

Current TextTable value assigned.

See Also:

setTable(com.ccg.io.TextTable)

setDataException

public void setDataException(Exception val)

Set the last exception which occurred while processing data.

Parameters:

val - New Exception value to assign.

See Also:

getDataException()

getDataException

public Exception getDataException()

Get the last exception which occurred while processing data.

Returns:

Current Exception value assigned.

See Also:

setDataException(java.lang.Exception)

setHeaderException

public void setHeaderException(Exception val)

Set the last exception which occurred while processing header.

Parameters:

val - New Exception value to assign.

See Also:

getHeaderException()

getHeaderException

public Exception getHeaderException()

Get the last exception which occurred while processing header.

Returns:

Current Exception value assigned.

See Also:

setHeaderException(java.lang.Exception)