org.voltdb

Class VoltTable

java.lang.Object

org.voltdb.VoltTableRow

org.voltdb.VoltTable

All Implemented Interfaces:

org.json_voltpatches.JSONString

public final class VoltTable
extends VoltTableRow
implements org.json_voltpatches.JSONString

The primary representation of a result set (of tuples) or a temporary table in VoltDB. VoltTable has arbitrary schema, is serializable, and is used from within Stored Procedures and from the client library.

Accessing Rows by Index

Given a VoltTable, individual rows can be accessed via the fetchRow(int) method. This method returns a VoltTableRow instance with position set to the specified row. See VoltTableRow for further information on accessing individual column data within a row.

A VoltTable is also a VoltTableRow

Like a VoltTableRow, a VoltTable has a current position within its rows. This is because VoltTable is a subclass of VoltTableRow. This allows for easy sequential access of data. Example:

while (table.advanceRow()) {
System.out.println(table.getLong(7));
}

Building a Table Dynamically

VoltTables can be constructed on the fly. This can help generate cleaner result sets from stored procedures, or more manageable parameters to them. Example:

VoltTable t = new VoltTable(
new VoltTable.ColumnInfo("col1", VoltType.BIGINT),
new VoltTable.ColumnInfo("col2", VoltType.STRING));
t.addRow(15, "sampleString");
t.addRow(-9, "moreData");

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	VoltTable.ColumnInfo Object that represents the name and schema for a VoltTable column.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_SERIALIZED_TABLE_LENGTH Size in bytes of the maximum length for a VoltDB tuple.
static java.lang.String	MAX_SERIALIZED_TABLE_LENGTH_STR String representation of MAX_SERIALIZED_TABLE_LENGTH.

Fields inherited from class org.voltdb.VoltTableRow

MAX_TUPLE_LENGTH, MAX_TUPLE_LENGTH_STR

Constructor Summary

Constructors

Constructor and Description
VoltTable(VoltTable.ColumnInfo[] columns) Create an empty table from column schema given as an array.
VoltTable(VoltTable.ColumnInfo[] columns, int columnCount) Create an empty table from column schema.
VoltTable(VoltTable.ColumnInfo firstColumn, VoltTable.ColumnInfo... columns) Create an empty table from column schema.

Method Summary

Modifier and Type	Method and Description
void	add(VoltTableRow row) Append a row from another VoltTable to this VoltTable instance.
void	addRow(java.lang.Object... values) Append a new row to the table using the supplied column values.
long	asScalarLong() Tables containing a single row and a single integer column can be read using this convenience method.
byte[]	buildReusableDependenyResult()
void	clearRowData() Delete all row data.
VoltTable	clone(int extraBytes) Generates a duplicate of a table including the column schema.
VoltTableRow	cloneRow() Get a new VoltTableRow instance with identical position as this table.
void	convertToHeapBuffer()
boolean	equals(java.lang.Object o) Deprecated. Exists for unit testing, but probably shouldn't be called.
VoltTableRow	fetchRow(int index) Return a VoltTableRow instance with the specified index.
void	flattenToBuffer(java.nio.ByteBuffer buf) Serialize this table to a given ByteBuffer.
static VoltTable	fromJSONObject(org.json_voltpatches.JSONObject json) Construct a table from a JSON object.
static VoltTable	fromJSONString(java.lang.String json) Construct a table from a JSON string.
java.nio.ByteBuffer	getBuffer() Directly access the table's underlying ByteBuffer.
int	getColumnCount() Returns the number of columns in the table schema
int	getColumnIndex(java.lang.String name) Return the index of the column with the specified column name.
java.lang.String	getColumnName(int index) Return the name of the column with the specified index.
VoltType	getColumnType(int index) Return the type of the column with the specified index.
int	getRowCount() Returns the number of rows.
protected int	getRowStart()
int	getSerializedSize() Get the serialized size in bytes of this table.
byte	getStatusCode() Set the status code associated with this table.
VoltTable.ColumnInfo[]	getTableSchema() Get the schema of the table.
int	hashCode() Deprecated. This only throws. Doesn't do anything.
boolean	hasSameContents(VoltTable other) Check to see if this table has the same contents as the provided table.
void	setStatusCode(byte code) Set the status code associated with this table.
java.lang.String	toFormattedString() Return a "pretty print" representation of this table with column names.
java.lang.String	toFormattedString(boolean includeColumnNames) Return a "pretty print" representation of this table with or without column names.
java.lang.String	toJSONString() Get a JSON representation of this table.
java.lang.String	toString() Returns a String representation of this table.
static java.lang.String	varbinaryToPrintableString(byte[] bin) Make a printable, short string for a varbinary.

Methods inherited from class org.voltdb.VoltTableRow

advanceRow, advanceToRow, get, get, getActiveRowIndex, getDecimalAsBigDecimal, getDecimalAsBigDecimal, getDouble, getDouble, getGeographyPointValue, getGeographyPointValue, getGeographyValue, getGeographyValue, getLong, getLong, getOffset, getString, getString, getStringAsBytes, getStringAsBytes, getTimestampAsLong, getTimestampAsLong, getTimestampAsSqlTimestamp, getTimestampAsSqlTimestamp, getTimestampAsTimestamp, getTimestampAsTimestamp, getVarbinary, getVarbinary, resetRowPosition, wasNull

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MAX_SERIALIZED_TABLE_LENGTH

public static final int MAX_SERIALIZED_TABLE_LENGTH

Size in bytes of the maximum length for a VoltDB tuple. This value is counted from byte 0 of the header size to the end of row data.

See Also:

Constant Field Values

MAX_SERIALIZED_TABLE_LENGTH_STR

public static final java.lang.String MAX_SERIALIZED_TABLE_LENGTH_STR

String representation of MAX_SERIALIZED_TABLE_LENGTH.

Constructor Detail

VoltTable

public VoltTable(VoltTable.ColumnInfo[] columns,
                 int columnCount)

Create an empty table from column schema. While VoltTable(ColumnInfo...) is the preferred constructor, this version may reduce the need for an array allocation by allowing the caller to specify only a portion of the given array should be used.

Parameters:

columns - An array of ColumnInfo objects, one per column in the desired order.

columnCount - The number of columns in the array to use.

VoltTable

public VoltTable(VoltTable.ColumnInfo[] columns)

Create an empty table from column schema given as an array.

Parameters:

columns - An array of ColumnInfo objects, one per column in the desired order.

VoltTable

public VoltTable(VoltTable.ColumnInfo firstColumn,
                 VoltTable.ColumnInfo... columns)

Create an empty table from column schema. Note that while this accepts a varargs set of columns, it requires at least one column to prevent user errors.

Parameters:

firstColumn - The first column of the table.

columns - An array of ColumnInfo objects, one per column in the desired order (can be empty).

Method Detail

clearRowData

public final void clearRowData()

Delete all row data. Column data is preserved. Useful for reusing an VoltTable.

cloneRow

public VoltTableRow cloneRow()

Get a new VoltTableRow instance with identical position as this table. After the cloning, the new instance and this table can be advanced or reset independently.

Specified by:

cloneRow in class VoltTableRow

Returns:

A new VoltTableRow instance with the same position as this table.

getColumnName

public final java.lang.String getColumnName(int index)

Return the name of the column with the specified index.

Parameters:

index - Index of the column

Returns:

Name of the column with the specified index.

getColumnType

public final VoltType getColumnType(int index)

Description copied from class: VoltTableRow

Return the type of the column with the specified index.

Specified by:

getColumnType in class VoltTableRow

Parameters:

index - Index of the column

Returns:

VoltType of the column

getColumnIndex

public final int getColumnIndex(java.lang.String name)

Description copied from class: VoltTableRow

Return the index of the column with the specified column name.

Specified by:

getColumnIndex in class VoltTableRow

Parameters:

name - Name of the column

Returns:

Index of the column

fetchRow

public final VoltTableRow fetchRow(int index)

Return a VoltTableRow instance with the specified index. This method is not performant because it has to scan the length prefix of every row preceding the requested row in order to find the position of the requested row. Use advanceRow or advanceToRow instead.

Parameters:

index - Index of the row

Returns:

The requested Row.

Throws:

java.lang.IndexOutOfBoundsException - if no row exists at the given index.

add

public final void add(VoltTableRow row)

Append a row from another VoltTable to this VoltTable instance. Technically, it could be from the same table, but this isn't the common usage.

Parameters:

row - Row to add.

addRow

public final void addRow(java.lang.Object... values)

Append a new row to the table using the supplied column values.

Parameters:

values - Values of each column in the row.

Throws:

VoltTypeException - when there are casting/type failures between an input value and the corresponding column

asScalarLong

public final long asScalarLong()

Tables containing a single row and a single integer column can be read using this convenience method. Looking at the return value is not a reliable way to check if the value is null. Use VoltTableRow.wasNull() instead.

Returns:

The integer row value.

toString

public java.lang.String toString()

Returns a String representation of this table. Resulting string will contain schema and all data and will be formatted.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this table.

varbinaryToPrintableString

public static java.lang.String varbinaryToPrintableString(byte[] bin)

Make a printable, short string for a varbinary. String includes a CRC and the contents of the varbinary in hex. Contents longer than 13 chars are truncated and elipsized. Yes, "elipsized" is totally a word. Example: "bin[crc:1298399436,value:0xABCDEF12345...]"

Parameters:

bin - The bytes to print out.

Returns:

A string representation that is printable and short.

toFormattedString

public java.lang.String toFormattedString()

Return a "pretty print" representation of this table with column names. Output will be formatted in a tabular textual format suitable for display.

Returns:

A string containing a pretty-print formatted representation of this table.

toFormattedString

public java.lang.String toFormattedString(boolean includeColumnNames)

Return a "pretty print" representation of this table with or without column names. Output will be formatted in a tabular textual format suitable for display.

Parameters:

includeColumnNames - Flag to control if column names should be included or not.

Returns:

A string containing a pretty-print formatted representation of this table.

toJSONString

public java.lang.String toJSONString()

Get a JSON representation of this table.

Specified by:

toJSONString in interface org.json_voltpatches.JSONString

Returns:

A string containing a JSON representation of this table.

fromJSONString

public static VoltTable fromJSONString(java.lang.String json)
                                throws org.json_voltpatches.JSONException,
                                       java.io.IOException

Construct a table from a JSON string. Only parses VoltDB VoltTable JSON format.

Parameters:

json - String containing JSON-formatted table data.

Returns:

Constructed VoltTable instance.

Throws:

org.json_voltpatches.JSONException - on JSON-related error.

java.io.IOException - if thrown by our JSON library.

fromJSONObject

public static VoltTable fromJSONObject(org.json_voltpatches.JSONObject json)
                                throws org.json_voltpatches.JSONException,
                                       java.io.IOException

Construct a table from a JSON object. Only parses VoltDB VoltTable JSON format.

Parameters:

json - String containing JSON-formatted table data.

Returns:

Constructed VoltTable instance.

Throws:

org.json_voltpatches.JSONException - on JSON-related error.

java.io.IOException - if thrown by our JSON library.

hasSameContents

public boolean hasSameContents(VoltTable other)

Check to see if this table has the same contents as the provided table. This is not Object.equals(Object) because we don't want to provide all of the additional contractual requirements that go along with it, such as implementing Object.hashCode().

Parameters:

other - Table to compare to.

Returns:

Whether the tables have the same contents.

equals

@Deprecated
public boolean equals(java.lang.Object o)

Deprecated. Exists for unit testing, but probably shouldn't be called.

An unreliable version of Object.equals(Object) that should not be used. Only present for unit testing.

Overrides:

equals in class java.lang.Object

hashCode

@Deprecated
public int hashCode()

Deprecated. This only throws. Doesn't do anything.

Also overrides Object.hashCode() since we are overriding Object.equals(Object). Throws an UnsupportedOperationException.

Overrides:

hashCode in class java.lang.Object

Throws:

java.lang.UnsupportedOperationException - if called.

clone

public final VoltTable clone(int extraBytes)

Generates a duplicate of a table including the column schema. Only works on tables that have no rows, have columns defined, and will not have columns added/deleted/modified later. Useful as way of creating template tables that can be cloned and then populated with rows repeatedly.

Parameters:

extraBytes - The number of extra bytes to leave for to-be-added rows beyond the header.

Returns:

An VoltTable with the same column schema as the original and enough space for the specified number of rows and strings.

getRowCount

public final int getRowCount()

Description copied from class: VoltTableRow

Returns the number of rows.

Returns:

Number of rows in the table

getRowStart

protected final int getRowStart()

getColumnCount

public final int getColumnCount()

Description copied from class: VoltTableRow

Returns the number of columns in the table schema

Specified by:

getColumnCount in class VoltTableRow

Returns:

Number of columns in the table schema

getStatusCode

public byte getStatusCode()

Set the status code associated with this table. Default value is 0.

Returns:

Status code

setStatusCode

public void setStatusCode(byte code)

Set the status code associated with this table. Default value if not set is 0

Parameters:

code - Status code to set

getSerializedSize

public int getSerializedSize()

Get the serialized size in bytes of this table. This is used mostly internally by VoltDB for table serialization purposes.

Returns:

The size in bytes.

flattenToBuffer

public void flattenToBuffer(java.nio.ByteBuffer buf)

Serialize this table to a given ByteBuffer. Used mostly internally by VoltDB for moving tables over the network.

Parameters:

buf - Buffer to serialize table to.

buildReusableDependenyResult

public byte[] buildReusableDependenyResult()

convertToHeapBuffer

public final void convertToHeapBuffer()

getBuffer

public java.nio.ByteBuffer getBuffer()

Directly access the table's underlying ByteBuffer. This should be avoided if possible by end users, as there is potential to really mess stuff up. VoltDB mostly uses it to compute various checksums quickly.

Returns:

The underlying ByteBuffer instance.

getTableSchema

public VoltTable.ColumnInfo[] getTableSchema()

Get the schema of the table. Can be fed into another table's constructor.

Returns:

An ordered array of VoltTable.ColumnInfo instances for each table column.