com.google.visualization.datasource.datatable
Class DataTable

java.lang.Object
  com.google.visualization.datasource.datatable.DataTable

public class DataTable
extends java.lang.Object

A table of data, arranged in typed columns. An instance of this class is the result of a request to a data source. A DataTable can be rendered in many ways: JSON, HTML, CSV (see com.google.visualization.datasource.render), and can be manipulated using queries (see Query and QueryEngine). A table contains any number of typed columns (see (@link ColumnDescription}) each with an id and a label, and any number of rows. Each row must have as many cells as there are columns in the table, and the types of values in the cells must match the types of the columns. Each cell contains, as well as the typed value, a formatted value of type string, used for display purposes. Also, you can use the custom properties mechanism to hold any other data you require. There are custom properties on every cell, row, column, and on the entire table.

Author:

Yoah B.D.

Constructor Summary

DataTable()
Create a new empty result.

Method Summary

void	addColumn(ColumnDescription columnDescription) Add a column to the table.
void	addColumns(java.util.Collection<ColumnDescription> columnsToAdd) Adds columns to the table.
void	addRow(TableRow row) Adds a single row to the end of the result.
void	addRowFromValues(java.lang.Object... values) A convenience method for creating a row directly from its cell values and adding it to the data table.
void	addRows(java.util.Collection<TableRow> rowsToAdd) Adds a collection of rows to the end of the result.
void	addWarning(Warning warning) Adds a warning.
DataTable	clone() Returns a new data table, with the same data and metadata as this one.
boolean	containsAllColumnIds(java.util.Collection<java.lang.String> colIds) Check that all the cols in colIds are in the data.
boolean	containsColumn(java.lang.String columnId) Returns whether or not the table contains a column named columnId.
static DataTable	createSingleCellTable(java.lang.String str) Returns a data table with str as the content of its single cell.
TableCell	getCell(int rowIndex, int colIndex) Returns the cell at the specified row and column indexes.
java.util.List<TableCell>	getColumnCells(int columnIndex) Returns the list of all cells of a certain column, by the column index.
java.util.List<TableCell>	getColumnCells(java.lang.String columnId) Returns the list of all cells of a certain column, by the column Id.
ColumnDescription	getColumnDescription(int colIndex) Returns the column description of a column by its index.
ColumnDescription	getColumnDescription(java.lang.String columnId) Returns the column description of a column by it's id.
java.util.List<ColumnDescription>	getColumnDescriptions() Returns the list of all column descriptions.
java.util.List<TableCell>	getColumnDistinctCellsSorted(int columnIndex, java.util.Comparator<TableCell> comparator) Returns a sorted list of distinct table cells in the specified column.
int	getColumnIndex(java.lang.String columnId) Returns the column index in the columns of a row (first is zero).
java.util.Map<java.lang.String,java.lang.String>	getCustomProperties() Returns an immutable map of the custom properties.
java.lang.String	getCustomProperty(java.lang.String key) Retrieves a custom property.
int	getNumberOfColumns() Returns the number of columns in this data table.
int	getNumberOfRows() Returns the number of rows in this data table.
TableRow	getRow(int rowIndex) Returns the row at the given index.
java.util.List<TableRow>	getRows() Returns the list of all table rows.
Value	getValue(int rowIndex, int colIndex) Returns the value in the cell at the specified row and column indexes.
java.util.List<Warning>	getWarnings() Returns the list of warnings in this table.
void	setCustomProperty(java.lang.String propertyKey, java.lang.String propertyValue) Sets a custom property.
void	setRows(java.util.Collection<TableRow> rows) Sets a collection of rows after clearing any current rows.
java.lang.String	toString() Returns a string representation of the data table.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataTable

public DataTable()

Create a new empty result.

Method Detail

addRow

public void addRow(TableRow row)
            throws TypeMismatchException

Adds a single row to the end of the result. Throws a TypeMismatchException if the row's cells do not match the current columns. If the row is too short, i.e., has too few cells, then the remaining columns are filled with null values (the given row is changed).

Parameters:

row - The row of values.

Throws:

TypeMismatchException - Thrown if the values in the cells do not match the columns.

addRowFromValues

public void addRowFromValues(java.lang.Object... values)
                      throws TypeMismatchException

A convenience method for creating a row directly from its cell values and adding it to the data table.

Parameters:

values - The row values.

Throws:

TypeMismatchException - Thrown if a value does not match its corresponding column.

addRows

public void addRows(java.util.Collection<TableRow> rowsToAdd)
             throws TypeMismatchException

Adds a collection of rows to the end of the result.

Parameters:

rowsToAdd - The row collection.

Throws:

TypeMismatchException

setRows

public void setRows(java.util.Collection<TableRow> rows)
             throws TypeMismatchException

Sets a collection of rows after clearing any current rows.

Parameters:

rows - The row collection.

Throws:

TypeMismatchException

getRows

public java.util.List<TableRow> getRows()

Returns the list of all table rows.

Returns:

The list of all table rows.

getRow

public TableRow getRow(int rowIndex)

Returns the row at the given index.

Parameters:

rowIndex - the index of the requested row.

Returns:

The row at the given index.

getNumberOfRows

public int getNumberOfRows()

Returns the number of rows in this data table.

Returns:

The number of rows.

getNumberOfColumns

public int getNumberOfColumns()

Returns the number of columns in this data table.

Returns:

The number of columns.

getColumnDescriptions

public java.util.List<ColumnDescription> getColumnDescriptions()

Returns the list of all column descriptions.

Returns:

The list of all column descriptions. The returned list is immutable.

getColumnDescription

public ColumnDescription getColumnDescription(int colIndex)

Returns the column description of a column by its index.

Parameters:

colIndex - The column index.

Returns:

The column description.

getColumnDescription

public ColumnDescription getColumnDescription(java.lang.String columnId)

Returns the column description of a column by it's id.

Parameters:

columnId - The id of the column.

Returns:

The column description of the specified column.

getColumnCells

public java.util.List<TableCell> getColumnCells(int columnIndex)

Returns the list of all cells of a certain column, by the column index. Note: This is the most naive implementation, that for each request to this method just creates a new List of the needed cells.

Parameters:

columnIndex - The index of the requested column.

Returns:

The list of all cells of the requested column.

addColumn

public void addColumn(ColumnDescription columnDescription)

Add a column to the table.

Parameters:

columnDescription - The column's description.

addColumns

public void addColumns(java.util.Collection<ColumnDescription> columnsToAdd)

Adds columns to the table.

Parameters:

columnsToAdd - The columns to add.

getColumnIndex

public int getColumnIndex(java.lang.String columnId)

Returns the column index in the columns of a row (first is zero).

Parameters:

columnId - The id of the column.

Returns:

The column index in the columns of a row (first is zero).

getColumnCells

public java.util.List<TableCell> getColumnCells(java.lang.String columnId)

Returns the list of all cells of a certain column, by the column Id.

Parameters:

columnId - The id of the requested column.

Returns:

The list of all cells of the requested column.

getCell

public TableCell getCell(int rowIndex,
                         int colIndex)

Returns the cell at the specified row and column indexes.

Parameters:

rowIndex - The row index.

colIndex - The column index.

Returns:

The cell.

getValue

public Value getValue(int rowIndex,
                      int colIndex)

Returns the value in the cell at the specified row and column indexes.

Parameters:

rowIndex - The row index.

colIndex - The column index.

Returns:

The value in the cell.

getWarnings

public java.util.List<Warning> getWarnings()

Returns the list of warnings in this table. The list returned is immutable.

Returns:

The list of warnings in this table.

getColumnDistinctCellsSorted

public java.util.List<TableCell> getColumnDistinctCellsSorted(int columnIndex,
                                                              java.util.Comparator<TableCell> comparator)

Returns a sorted list of distinct table cells in the specified column. The cells are sorted according to the given comparator in ascending order.

Parameters:

columnIndex - The index of the required column.

comparator - A Comparator for TableCells.

Returns:

A sorted list of distinct table cells in the specified column.

addWarning

public void addWarning(Warning warning)

Adds a warning.

Parameters:

warning - The warning to add.

containsColumn

public boolean containsColumn(java.lang.String columnId)

Returns whether or not the table contains a column named columnId.

Parameters:

columnId - The column id to check.

Returns:

True if columnId exists in this table, false otherwise.

containsAllColumnIds

public boolean containsAllColumnIds(java.util.Collection<java.lang.String> colIds)

Check that all the cols in colIds are in the data.

Parameters:

colIds - A list of column ids.

Returns:

True if all the columns are in the data table, false otherwise.

createSingleCellTable

public static DataTable createSingleCellTable(java.lang.String str)

Returns a data table with str as the content of its single cell.

Parameters:

str - The cell's content

Returns:

A data table with str as the content of its single cell.

clone

public DataTable clone()

Returns a new data table, with the same data and metadata as this one. Any change to the returned table should not change this table and vice versa. This is a deep clone.

Overrides:

clone in class java.lang.Object

Returns:

The cloned data table.

getCustomProperty

public java.lang.String getCustomProperty(java.lang.String key)

Retrieves a custom property. Returns null if it does not exist.

Parameters:

key - The property key.

Returns:

The property value, or null if it does not exist.

setCustomProperty

public void setCustomProperty(java.lang.String propertyKey,
                              java.lang.String propertyValue)

Sets a custom property.

Parameters:

propertyKey - The property key.

propertyValue - The property value.

getCustomProperties

public java.util.Map<java.lang.String,java.lang.String> getCustomProperties()

Returns an immutable map of the custom properties.

Returns:

An immutable map of the custom properties.

toString

public java.lang.String toString()

Returns a string representation of the data table. Useful mainly for debugging.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of the data table.