edu.nrao.sss.html
Class HtmlTable

java.lang.Object
  edu.nrao.sss.html.HtmlElement
      edu.nrao.sss.html.HtmlTable

public class HtmlTable
extends HtmlElement

An HTML table.

Version Info:

$Revision: 502 $

$Date: 2007-04-04 11:39:33 -0600 (Wed, 04 Apr 2007) $

$Author: dharland $

Since:

2007-03-15

Author:

David M. Harland

Field Summary

Fields inherited from class edu.nrao.sss.html.HtmlElement

NBSP_HTML, NBSP_TEXT, NBSP_UNICODE

Constructor Summary

HtmlTable()
Creates a new empty table.

Method Summary

void	addRow(HtmlTableRow newRow) Adds newRow to this table.
static List<HtmlTable>	createFromHtml(Reader source) Returns a list of new HTML tables created by parsing the given source.
URL	getParentPage() Returns the page to which this table belongs, if any.
List<String>	getParsingErrors() Returns a list of the parsing errors reported during the most recent call to readHtmlFrom(Reader, int).
List<HtmlTableRow>	getRows() Returns a copy of this table's list of rows.
List<HtmlTableRow>	getRows(HtmlTableRow.Type desiredType) Returns a new list that contains the rows of this table whose type is equal to desiredType.
List<List<HtmlTableRow>>	getRowsInSections() Returns the rows of this table segregated into header rows, data rows, and footer rows.
boolean	isSimple() Returns false.
void	readHtmlFrom(Reader source, int tableIndex) Adds rows to this table by parsing source.
void	readTextFrom(Reader reader, String columnSeparator) Appends new rows to this table by parsing the delimited text in reader.
int	removeEmptyRows() Removes all empty rows (those with no cells) from this table.
boolean	removeRow(HtmlTableRow unwantedRow) Removes unwantedRow from this table.
int	size() Returns the number of rows in this table.
HtmlTable	toCompressedTable() Returns a new table that is an expanded form of this table.
HtmlTable	toExpandedTable() Returns a new table that is an expanded form of this table.
void	writeTextTo(Writer device, String rowDelimiter, String columnDelimiter) Writes this table as text.

Methods inherited from class edu.nrao.sss.html.HtmlElement

addAttribute, copyAttributesOf, getAttribute, getAttributes, getAttributeValue, getTag, removeAllAttributes, removeAttribute, writeHtmlTo

Methods inherited from class java.lang.Object

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

Constructor Detail

HtmlTable

public HtmlTable()

Creates a new empty table.

Method Detail

isSimple

public boolean isSimple()

Returns false.

Specified by:

isSimple in class HtmlElement

Returns:

true if this is a simple element.

getParentPage

public URL getParentPage()

Returns the page to which this table belongs, if any.

Returns:

the page to which this table belongs. If this table belongs to no page, the value returned is null.

addRow

public void addRow(HtmlTableRow newRow)

Adds newRow to this table.

If the new row is null or already in this table, this method does nothing. Otherwise the new row is removed from its previous table, if any, and added to this one. The new cell's parent table is set to this one.

Parameters:

newRow - a new row for this table.

removeRow

public boolean removeRow(HtmlTableRow unwantedRow)

Removes unwantedRow from this table.

If the unwanted row is null or not part of this table, this method does nothing. Otherwise the unwanted row is removed from this table, and its parent table is set to null.

Parameters:

unwantedRow - the row to be removed from this table.

Returns:

true if unwantedRow was removed from this table.

removeEmptyRows

public int removeEmptyRows()

Removes all empty rows (those with no cells) from this table.

Returns:

the number of rows removed.

getRows

public List<HtmlTableRow> getRows()

Returns a copy of this table's list of rows.

While the list is a copy, the rows in the returned list are the actual rows held in this table.

Returns:

a copy of this tables's list of rows.

getRows

public List<HtmlTableRow> getRows(HtmlTableRow.Type desiredType)

Returns a new list that contains the rows of this table whose type is equal to desiredType.

Parameters:

desiredType - the type of row desired.

Returns:

the rows from this table that are of the desired type.

getRowsInSections

public List<List<HtmlTableRow>> getRowsInSections()

Returns the rows of this table segregated into header rows, data rows, and footer rows.

The returned list will always have exactly three elements. The first list holds header rows, the second holds data rows, and the last holds footer rows. Each element will always hold a list -- it will never hold null. If a table has no rows of a given type, that list will be empty.

Returns:

the rows of this table segregated into header rows, data rows, and footer rows.

size

public int size()

Returns the number of rows in this table.

Returns:

the number of rows in this table.

writeTextTo

public void writeTextTo(Writer device,
                        String rowDelimiter,
                        String columnDelimiter)
                 throws IOException

Writes this table as text. Each row is separated by rowDelimiter. Within each row, each column is separated by columnDelimiter.

Handling COLSPAN and ROWSPAN
In order to make a rectangular grid of rows and columns, this method processes the colspan and rowspan attributes of each HtmlTableCell. It does this by repeating a table cell's information in the appropriate number of rows and columns of the grid. A hole anywhere in the grid is represented by an empty string, in which case you will see consecutive columnDelimiters. If a table has been specified erroneously such that two cells overlap in the grid, this method favors the table cells of the row with the higher index, overwriting those from previous rows.

Example:

Given this 4x4 table:

--A--	--B--
	--C--		--D--
--E--			--F--
--G--

The result of calling this method with ";" for the column delimiter and new-line for the row delimiter is:

    --A--;--B--;--B--;;
    --A--;--C--;--C--;--D--;
    --E--;--C--;--C--;--F--;
    --G--;--G--;;--F--;

Parameters:

device - where the text is written.

rowDelimiter - used to separate the rows.

columnDelimiter - used to separate columns within a row.

Throws:

IOException - if anything goes wrong while writing to the device.

createFromHtml

public static List<HtmlTable> createFromHtml(Reader source)
                                      throws IOException

Returns a list of new HTML tables created by parsing the given source.

Caveat: This method translates only "outer" tables -- those not contained in the cells of other tables. Tables inside table cells are captured as the unparsed content of HtmlTableCells. One way to overcome this is to subject the unparsed content of the returned tables' cells to this same method.

Parameters:

source - a source of HTML to be parsed for tables.

Returns:

a list of HTML tables created by parsing the given source.

Throws:

IOException - if anything goes wrong while reading the source.

readHtmlFrom

public void readHtmlFrom(Reader source,
                         int tableIndex)
                  throws IOException

Adds rows to this table by parsing source. Only data from the table at position tableIndex, starting from the current cursor position in source, is used. Indexing starts at zero and starts with the first table open tag found. If no such tag is found, this table is unaltered by this method.

Caveat: This method indexes and translates only "outer" tables -- those not contained in the cells of other tables. Tables inside table cells of the parsed table are captured as the unparsed content of HtmlTableCells. One way to overcome this is to subject the unparsed content of the returned tables' cells to createFromHtml(Reader).

Parameters:

source - a source of HTML to be parsed for tables.

Throws:

IOException - if anything goes wrong while reading the source.

getParsingErrors

public List<String> getParsingErrors()

Returns a list of the parsing errors reported during the most recent call to readHtmlFrom(Reader, int). The returned list is not held by this table, so manipulating it will have no effect on this object.

Returns:

a list of the parsing errors reported during the most recent call to readHtmlFrom(Reader, int).

readTextFrom

public void readTextFrom(Reader reader,
                         String columnSeparator)
                  throws IOException

Appends new rows to this table by parsing the delimited text in reader. Each line presented by reader is assumed to be a new row.

Parameters:

reader - a text source of table rows.

columnSeparator - the delimiter separating columns in a row.

Throws:

IOException

toExpandedTable

public HtmlTable toExpandedTable()

Returns a new table that is an expanded form of this table.

By "expanded" we mean that any cells that had colspan or rowspan values greater than one have been split into multiple cells with column and row spans of one. For example, a cell in this table with a column span of three and a row span of two is present not once, but six times, in the returned table. Furthermore, the six occurrences, while equal to each other, are six distinct instances.

No cells are shared by this table and the returned table.

Example
Let the following be the HTML for this table:

--A--	--B--
	--C--		--D--
--E--			--F--
--G--

The table created by this method looks like this:

--A--	--B--	--B--
--A--	--C--	--C--	--D--
--E--	--C--	--C--	--F--
--G--	--G--		--F--

Notice one side effect: the upper right corner of the original table has a missing cell; in the new table there is, instead, an empty cell.

If the second table is then recompressed via toCompressedTable(), it looks like this:

--A--	--B--
	--C--		--D--
--E--			--F--
--G--

The original table is nearly reproduced. The only difference is the empty cell in place of the missing cell in the upper right corner.

Caveat: the algorithm used for column widths is only approximate. It is possible to achieve odd-looking widths for some tables.

Returns:

an expanded version of this table.

toCompressedTable

public HtmlTable toCompressedTable()

Returns a new table that is an expanded form of this table.

By "compressed" we mean that adjacent cells in this table that have equal contents attributes have been merged, to the extent possible, into one cell with a column span and/or a row span greater than one.

No cells are shared by this table and the returned table.

See the example in toExpandedTable(); this method first calls that method, so any problems mentioned in that method's documentation may have an effect on the results of this method.

Returns:

a compressed version of this table.