com.streambase.sb

Class Tuple

java.lang.Object

com.streambase.sb.Tuple

All Implemented Interfaces:

com.streambase.sb.internal.CloneableData, java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

CompiledTuple

public abstract class Tuple
extends java.lang.Object
implements java.lang.Cloneable, com.streambase.sb.internal.CloneableData, java.io.Serializable

An class that represents a Tuple of StreamBase data.

To create a new Tuple object, use the Schema.createTuple() method on a Schema instance.

The DataType of each Field must be appropriate for the get and set methods invoked on the Field. For example, the Tuple.getDouble(Schema.Field) & Tuple.setDouble(Schema.Field, double) methods work only on double fields. The Tuple.setField(Schema.Field, Object) will do default conversions from different types.

For performance-critical paths, use the type-specific get and set methods that take a parameter of type Schema.Field (as opposed to the the methods that take an int or a String).

Note that all methods accepting a Schema.Field argument will throw an IllegalArgumentException if the Field object was not obtained from the Schema associated with this Tuple instance (Tuple.getSchema()).

This class is not thread safe. If instances of this class are accessed from multiple threads, access must be synchronized.

Note: Serializations of instances of this class that are created (e.g., by using ObjectOutputStream) in one version of StreamBase in general will not be deserializable in any other version of StreamBase.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Tuple.DefaultTupleFormatter A default formatter that converts each type to String using Java default String conversions.
static interface	Tuple.SetResult An interface containing flags returned from certain setXXXX calls
static interface	Tuple.TupleFormatter This interface is not public API, and should not be implemented by users.

Field Summary

Fields

Modifier and Type	Field and Description
protected static int	CREATE_IF_NULL during a get create tuple if it is null
static Tuple	EMPTY_TUPLE
protected static int	NO_FLAGS no flags
static java.lang.String	NULL_STRING The default String representation of a null valued field (value "null")
protected static int	THROW_ON_NULL during a get throw an exception on null

Method Summary

Modifier and Type	Method and Description
protected void	checkType(Schema.Field resolvedField, DataType dataType)
protected int	checkTypeAndNonNull(Schema.Field resolvedField, DataType dataType) check the type and make sure it is non null
abstract void	clear() Sets all of this tuple's fields to null values.
Tuple	clone() Clone this tuple, the new tuple will not share any buffers or data with the original
void	copyField(Schema.Field sourceField, Tuple destTuple, Schema.Field destField) Copy the field from this tuple to the destination tuple
protected void	copyTuple(Tuple sourceTuple) copy the source tuple to this tuple
abstract Tuple	createReadOnlyTuple() Return a new tuple that is guaranteed to be read only
abstract Tuple	createWritableTuple() Return a new tuple that is guaranteed to be writable
boolean	equals(java.lang.Object obj) Test whether the given object is equal to this one.
Tuple	getAllocatedTuple(int fieldIndex) Return a reference (not a copy) to the specified nested tuple field.
Tuple	getAllocatedTuple(Schema.Field field) Return a reference (not a copy) to the specified nested tuple field.
Tuple	getAllocatedTuple(java.lang.String fieldPathName) Return a reference (not a copy) to the specified nested tuple field.
ByteArrayView	getBlobBuffer(int fieldIndex) Return a ByteArrayView for a given blob field.
ByteArrayView	getBlobBuffer(Schema.Field field) Return a ByteArrayView for a given blob field.
ByteArrayView	getBlobBuffer(java.lang.String fieldPathName) Return a ByteArrayView for a given blob field.
boolean	getBoolean(int fieldIndex) Return the value of the boolean field at a specified field index.
boolean	getBoolean(Schema.Field field) Return the value of a specified boolean field.
boolean	getBoolean(java.lang.String fieldPathName) Return the value of a named boolean field.
Tuple	getCapture(int fieldIndex) Return the value of the named capture field.
Tuple	getCapture(Schema.Field field) Return the value of the named capture field.
Tuple	getCapture(java.lang.String fieldPathName) Return the value of the named capture field.
protected abstract Tuple	getCaptureImpl(Schema.Field field)
double	getDouble(int fieldIndex) Return the value of the double field at a specified field index.
double	getDouble(Schema.Field field) Return the value of a specified double field.
double	getDouble(java.lang.String fieldPathName) Return the value of a named double field.
java.lang.Object	getField(int fieldIndex) Return the value of the field at a specified field index.
java.lang.Object	getField(Schema.Field field) Return the value of a specified field.
java.lang.Object	getField(java.lang.String fieldPathName) Return the value of a named field.
java.lang.String	getFieldAsString(Schema.Field field, Tuple.TupleFormatter formatter) Get the current field as a human readable string, using the Tuple.TupleFormatter provided.
java.util.Map<java.lang.String,java.lang.Object>	getFields() Deprecated. use Tuple.toMapView()
Function	getFunction(int fieldIndex) Return the value of the function field at a specified field index.
Function	getFunction(Schema.Field field) Return the value of the given function field.
Function	getFunction(java.lang.String fieldName) Return the value of the named function field.
int	getInt(int fieldIndex) Return the value of the int field at a specified field index.
int	getInt(Schema.Field field) Return the value of a specified int field.
int	getInt(java.lang.String fieldPathName) Return the value of a named int field.
java.util.List<?>	getList(int fieldIndex) Return the value of the list field at a specified field index.
java.util.List<?>	getList(Schema.Field field) Return the value of a specified list field.
java.util.List<?>	getList(java.lang.String fieldPathName) Return the value of a named list field.
long	getLong(int fieldIndex) Return the value of the long field at a specified field index.
long	getLong(Schema.Field field) Return the value of a specified long field.
long	getLong(java.lang.String fieldPathName) Return the value of a named long field.
Schema	getSchema() Return the Schema for this Tuple
java.lang.String	getString(int fieldIndex) Return the value of the named string field.
java.lang.String	getString(Schema.Field field) Return the value of a specified string field.
java.lang.String	getString(java.lang.String fieldPathName) Return the value of the named string field.
Timestamp	getTimestamp(int fieldIndex) Return the value of the timestamp field at a specified field index.
Timestamp	getTimestamp(Schema.Field field) Return the value of a specified timestamp field.
Timestamp	getTimestamp(java.lang.String fieldPathName) Return the value of a named timestamp field.
Tuple	getTuple(int fieldIndex) Return a reference (not a copy) to the specified nested tuple field.
Tuple	getTuple(Schema.Field field) Return a reference (not a copy) to the specified nested tuple field.
Tuple	getTuple(java.lang.String fieldPathName) Return a reference (not a copy) to the specified nested tuple field.
static Tuple.TupleFormatter	getTupleFormatter() Returns a shared instance of the default tuple field formatter that converts each type to String using Java default String conversions.
int	hashCode() Compute a hashCode for the object.
boolean	isNull(int fieldIndex) Determines whether a field in the tuple is null.
boolean	isNull(Schema.Field field) Determines whether the given field's value in this Tuple is null.
boolean	isNull(java.lang.String fieldPathName) Determines whether a field in the tuple is null.
abstract boolean	isReadOnly() Returns true if this is a read only tuple (read only tuples throw an UnsupportedOperationException when setter methods are called)
void	serialize(com.streambase.sb.util.ByteOrderedDataOutput output) Serialize this tuple into a ByteOrderedDataOutput
abstract void	serialize(com.streambase.sb.util.ByteOrderedDataOutput output, int tupleId) Serialize this tuple into a ByteOrderedDataOutput while specifing the tupleId.
void	setBlobBuffer(int fieldIndex, ByteArrayView value) Set the blob field at a specified field index to a copy of a specified blob.
void	setBlobBuffer(Schema.Field field, ByteArrayView value) Set a specified blob field to a copy of a specified blob.
void	setBlobBuffer(java.lang.String fieldPathName, ByteArrayView value) Set a named blob field to a copy of a specified blob.
void	setBoolean(int fieldIndex, boolean value) Set the boolean field at a specified field index to a specified value.
void	setBoolean(Schema.Field field, boolean value) Set a named boolean field to a specified value.
void	setBoolean(java.lang.String fieldPathName, boolean value) Set a named boolean field to a specified value.
void	setCapture(int field, Tuple value) Set a specified capture field to a copy of a specified tuple.
void	setCapture(Schema.Field field, Tuple value) Set a specified capture field to a copy of a specified tuple.
void	setCapture(java.lang.String field, Tuple value) Set a specified capture field to a copy of a specified tuple.
void	setDouble(int fieldIndex, double value) Set the double field at a specified field index to a specified value.
void	setDouble(Schema.Field field, double value) Set a named double field to a specified value.
void	setDouble(java.lang.String fieldPathName, double value) Set a named double field to a specified value.
void	setField(int fieldIndex, java.lang.Object value) Set the field at a specified field index to a specified boxed value.
void	setField(Schema.Field field, java.lang.Object value) Set a specified field to a specified boxed value.
void	setField(Schema.Field field, java.lang.Object value, com.streambase.sb.util.CSV.FormatInfo format) Set the field at a specified field name to a specified boxed value.
void	setField(java.lang.String fieldPathName, java.lang.Object value) Set the named field to a specified value.
void	setField(java.lang.String fieldPathName, java.lang.Object value, com.streambase.sb.util.CSV.FormatInfo format) Set the field at a specified field name to a specified boxed value.
void	setFields(java.util.Map<java.lang.String,java.lang.Object> fields) Takes a map of field names and values as Objects and sets the corresponding tuple field with the supplied value.
void	setFunction(int field, Function value) Set a specified function field to the given Function
void	setFunction(Schema.Field field, Function value) Set a specified function field to the given Function
void	setFunction(java.lang.String field, Function value) Set a specified function field to the given Function
void	setInt(int fieldIndex, int value) Set the int field at a specified field index to a specified value.
void	setInt(Schema.Field field, int value) Set a specified int field to a specified value.
void	setInt(java.lang.String fieldPathName, int value) Set the named int field to a specified value.
void	setList(int fieldIndex, java.util.List<?> value) Set the list field at a specified field index to a copy of the specified value.
void	setList(Schema.Field field, java.util.List<?> value) Set a specified list field to a copy of a specified value.
void	setList(java.lang.String fieldPathName, java.util.List<?> value) Set a named list field to a copy of a specified value.
void	setLong(int fieldIndex, long value) Set the long field at a specified field index to a specified value.
void	setLong(Schema.Field field, long value) Set a specified long field to a specified value.
void	setLong(java.lang.String fieldPathName, long value) Set a named long field to a specified value.
void	setNull(int fieldIndex) Set the field at a specified field index to null.
void	setNull(Schema.Field field) Set the specified field to null
void	setNull(java.lang.String fieldPathName) Set a named field to null.
void	setString(int fieldIndex, java.lang.CharSequence value) Set the string field at a specified field index to a specified value.
void	setString(Schema.Field field, java.lang.CharSequence value) Set a specified string field to a specified value.
void	setString(java.lang.String fieldPathName, java.lang.CharSequence value) Set a named field to a specified value.
void	setTimestamp(int fieldIndex, Timestamp value) Set the timestamp field at a specified field index to a specified value.
void	setTimestamp(Schema.Field field, Timestamp value) Set a named timestamp field to a specified value.
void	setTimestamp(java.lang.String fieldPathName, Timestamp value) Set a named timestamp field to a specified value.
void	setTuple(int fieldIndex, Tuple value) Set a specified nested tuple field to that of the specified tuple.
void	setTuple(Schema.Field field, Tuple value) Set a specified nested tuple field to that of the specified tuple NOTE: A copy of the the tuple may be made to convert the given tuple to the appropriate internal representation.
void	setTuple(java.lang.String fieldPathName, Tuple value) Set a named nested tuple field to a specified tuple.
java.lang.String	toDelimitedString(char delimiter) Return the tuple as a string delimited by the given character.
java.util.Map<java.lang.String,java.lang.Object>	toMapView() Returns a view on this Tuple that implements the Map<String, Object> interface.
java.lang.String	toString(boolean verbose) Return a string representation of this Tuple.
java.lang.String	toString(char delimiter, boolean verbose) Deprecated.
java.lang.String	toString(char delimiter, char quoteChar, boolean verbose) Return a string representation of this Tuple.
java.lang.String	toString(char delimiter, char quoteChar, boolean verbose, boolean showTupleId) Return a string representation of this Tuple.
java.lang.String	toString(char delimiter, char quoteChar, boolean verbose, boolean showTupleId, java.lang.String nullString) Return a string representation of this Tuple.
java.lang.String	toString(char delimiter, char quoteChar, boolean verbose, java.lang.String nullString) Return a string representation of this Tuple.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_TUPLE

public static final Tuple EMPTY_TUPLE

NO_FLAGS

protected static final int NO_FLAGS

no flags

See Also:

Constant Field Values

THROW_ON_NULL

protected static final int THROW_ON_NULL

during a get throw an exception on null

See Also:

Constant Field Values

CREATE_IF_NULL

protected static final int CREATE_IF_NULL

during a get create tuple if it is null

See Also:

Constant Field Values

NULL_STRING

public static final java.lang.String NULL_STRING

The default String representation of a null valued field (value "null")

See Also:

Constant Field Values

Method Detail

isReadOnly

public abstract boolean isReadOnly()

Returns true if this is a read only tuple (read only tuples throw an UnsupportedOperationException when setter methods are called)

Returns:

true if this is a read only tuple

clone

public Tuple clone()
            throws java.lang.CloneNotSupportedException

Clone this tuple, the new tuple will not share any buffers or data with the original

Specified by:

clone in interface com.streambase.sb.internal.CloneableData

Overrides:

clone in class java.lang.Object

Returns:

A copy of this Tuple

Throws:

java.lang.CloneNotSupportedException

getSchema

public final Schema getSchema()

Return the Schema for this Tuple

Returns:

the Schema for this Tuple

clear

public abstract void clear()

Sets all of this tuple's fields to null values.

serialize

public final void serialize(com.streambase.sb.util.ByteOrderedDataOutput output)

Serialize this tuple into a ByteOrderedDataOutput

Parameters:

output - the output stream

serialize

public abstract void serialize(com.streambase.sb.util.ByteOrderedDataOutput output,
                               int tupleId)

Serialize this tuple into a ByteOrderedDataOutput while specifing the tupleId. In general users will want to use Tuple.serialize(ByteOrderedDataOutput)

Parameters:

output - the output stream

tupleId - the tupleId to attach to this tuple

See Also:

Tuple.serialize(ByteOrderedDataOutput)

getBoolean

public final boolean getBoolean(java.lang.String fieldPathName)
                         throws TupleException,
                                NullValueException

Return the value of a named boolean field.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a boolean for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

getBoolean

public final boolean getBoolean(int fieldIndex)
                         throws TupleException,
                                NullValueException

Return the value of the boolean field at a specified field index.

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

a boolean for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

getBoolean

public boolean getBoolean(Schema.Field field)
                   throws TupleException,
                          NullValueException

Return the value of a specified boolean field.

Parameters:

field - the field to get

Returns:

a boolean for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

getDouble

public final double getDouble(java.lang.String fieldPathName)
                       throws TupleException,
                              NullValueException

Return the value of a named double field.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a double for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

getDouble

public final double getDouble(int fieldIndex)
                       throws TupleException,
                              NullValueException

Return the value of the double field at a specified field index.

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

a double for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

getDouble

public double getDouble(Schema.Field field)
                 throws TupleException,
                        NullValueException

Return the value of a specified double field.

Parameters:

field - the double field to get

Returns:

a double for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

getInt

public final int getInt(java.lang.String fieldPathName)
                 throws TupleException,
                        NullValueException

Return the value of a named int field.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

an int for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

getInt

public final int getInt(int fieldIndex)
                 throws TupleException,
                        NullValueException

Return the value of the int field at a specified field index.

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

an int for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

getInt

public int getInt(Schema.Field field)
           throws TupleException,
                  NullValueException

Return the value of a specified int field.

Parameters:

field - the int field to get

Returns:

an int for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

getLong

public final long getLong(java.lang.String fieldPathName)
                   throws TupleException,
                          NullValueException

Return the value of a named long field.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a long for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

getLong

public final long getLong(int fieldIndex)
                   throws TupleException,
                          NullValueException

Return the value of the long field at a specified field index.

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

a long for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

getLong

public long getLong(Schema.Field field)
             throws TupleException,
                    NullValueException

Return the value of a specified long field.

Parameters:

field - the long field to get

Returns:

a long for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

getList

public final java.util.List<?> getList(java.lang.String fieldPathName)
                                throws TupleException,
                                       NullValueException

Return the value of a named list field. The returned list is not a copy and should not be modified. (The effects of such modifications are undefined.)

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a list for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

Since:

6.3

getList

public final java.util.List<?> getList(int fieldIndex)
                                throws TupleException,
                                       NullValueException

Return the value of the list field at a specified field index. The returned list is not a copy and should not be modified. (The effects of such modifications are undefined.)

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

a List for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

Since:

6.3

getList

public java.util.List<?> getList(Schema.Field field)
                          throws TupleException,
                                 NullValueException

Return the value of a specified list field. The returned list is not a copy and should not be modified. (The effects of such modifications are undefined.)

Parameters:

field - the list field to get

Returns:

a list for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

Since:

6.3

getString

public final java.lang.String getString(java.lang.String fieldPathName)
                                 throws TupleException,
                                        NullValueException

Return the value of the named string field. Note that this method is not to be used to retrieve a String value for fields of any type: for that use Tuple.getField(String).

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a String for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

getString

public final java.lang.String getString(int fieldIndex)
                                 throws TupleException,
                                        NullValueException

Return the value of the named string field. Note that this method is not to be used to retrieve a String value for fields of any type: for that use Tuple.getField(String).

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

a String for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

getString

public java.lang.String getString(Schema.Field field)
                           throws TupleException,
                                  NullValueException

Return the value of a specified string field. getString() will only work on String datatypes Use getField() to work on all datatypes

Parameters:

field - the field

Returns:

a String for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

getTimestamp

public final Timestamp getTimestamp(java.lang.String fieldPathName)
                             throws TupleException,
                                    NullValueException

Return the value of a named timestamp field.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a Timestamp for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

getTimestamp

public final Timestamp getTimestamp(int fieldIndex)
                             throws TupleException,
                                    NullValueException

Return the value of the timestamp field at a specified field index.

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

a Timestamp for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

getTimestamp

public Timestamp getTimestamp(Schema.Field field)
                       throws TupleException,
                              NullValueException

Return the value of a specified timestamp field.

Parameters:

field - the Timestamp field to get

Returns:

a Timestamp for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

getBlobBuffer

public final ByteArrayView getBlobBuffer(java.lang.String fieldPathName)
                                  throws TupleException,
                                         NullValueException

Return a ByteArrayView for a given blob field. A copy of the blob is not made.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a ByteArrayView for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

getBlobBuffer

public final ByteArrayView getBlobBuffer(int fieldIndex)
                                  throws TupleException,
                                         NullValueException

Return a ByteArrayView for a given blob field. A copy of the blob is not made.

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

a ByteArrayView for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

getBlobBuffer

public ByteArrayView getBlobBuffer(Schema.Field field)
                            throws TupleException,
                                   NullValueException

Return a ByteArrayView for a given blob field. A copy of the blob is not made.

Parameters:

field - the field to get

Returns:

a ByteArrayView for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

getTuple

public Tuple getTuple(Schema.Field field)
               throws TupleException,
                      NullValueException

Return a reference (not a copy) to the specified nested tuple field. Also consider using {link #getAllocatedTuple(Schema.Field) as an alternative to reduce copying of data without the need for a Tuple.setTuple(Schema.Field, Tuple).

Parameters:

field - the field to get

Returns:

a Tuple for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the Field provided

Since:

6.0

See Also:

Tuple.getAllocatedTuple(Schema.Field)

getAllocatedTuple

public Tuple getAllocatedTuple(Schema.Field field)
                        throws TupleException

Return a reference (not a copy) to the specified nested tuple field. Allocates nested tuples as needed to always return a non-null tuple. The returned Tuple may be modified directly without the need to call Tuple.setTuple(Schema.Field, Tuple) to update the parent tuple.

Parameters:

field - the field to get

Returns:

a Tuple for the given field

Throws:

TupleException - if there was a conversion error

Since:

6.6.12

getTuple

public final Tuple getTuple(java.lang.String fieldPathName)
                     throws TupleException,
                            NullValueException

Return a reference (not a copy) to the specified nested tuple field. Also consider using {link #getAllocatedTuple(String) as an alternative to reduce copying of data without the need for a Tuple.setTuple(String, Tuple).

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a Tuple for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

Since:

6.0

See Also:

Tuple.getAllocatedTuple(String)

getAllocatedTuple

public final Tuple getAllocatedTuple(java.lang.String fieldPathName)
                              throws TupleException

Return a reference (not a copy) to the specified nested tuple field. Allocates nested tuples as needed to always return a non-null tuple. The returned Tuple may be modified directly without the need to call Tuple.setTuple(Schema.Field, Tuple) to update the parent tuple.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

a Tuple for the given field

Throws:

TupleException - if there was a conversion error

Since:

6.6.12

getTuple

public final Tuple getTuple(int fieldIndex)
                     throws TupleException,
                            NullValueException

Return a reference (not a copy) to the specified nested tuple field. Also consider using {link #getAllocatedTuple(int) as an alternative to reduce copying of data without the need for a Tuple.setTuple(int, Tuple).

Parameters:

fieldIndex - the index of a field to get (starting at 0)

Returns:

a Tuple for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null or a null sub-field was encountered while traversing to the field provided

Since:

6.0

See Also:

Tuple.getAllocatedTuple(int)

getAllocatedTuple

public final Tuple getAllocatedTuple(int fieldIndex)
                              throws TupleException

Return a reference (not a copy) to the specified nested tuple field. Allocates nested tuples as needed to always return a non-null tuple. The returned Tuple may be modified directly without the need to call Tuple.setTuple(Schema.Field, Tuple) to update the parent tuple.

Parameters:

fieldIndex - the index of a field to get (starting at 0)

Returns:

a Tuple for the given field

Throws:

TupleException - if there was a conversion error

Since:

6.6.12

getCapture

public final Tuple getCapture(Schema.Field field)
                       throws TupleException

Return the value of the named capture field.

Parameters:

field - the field to get

Returns:

an Tuple containing the fields captured (possibly none)

Throws:

TupleException - on error with the capture field

Since:

7.2

getCapture

public final Tuple getCapture(java.lang.String fieldPathName)
                       throws NullValueException,
                              TupleException

Return the value of the named capture field.

Parameters:

fieldPathName - the field to get

Returns:

an Tuple containing the fields captured (possibly none)

Throws:

TupleException - on error with the capture field

NullValueException - if the value of the field is null

Since:

7.2

getCapture

public final Tuple getCapture(int fieldIndex)
                       throws NullValueException,
                              TupleException

Return the value of the named capture field.

Parameters:

fieldIndex - the index of the field to get

Returns:

an Tuple containing the fields captured (possibly none)

Throws:

TupleException - on error with the capture field

NullValueException - if the value of the field is null

Since:

7.2

getCaptureImpl

protected abstract Tuple getCaptureImpl(Schema.Field field)
                                 throws TupleException

Throws:

TupleException

getField

public final java.lang.Object getField(Schema.Field field)

Return the value of a specified field.

Parameters:

field - the field to get

Returns:

an Object of the proper type for this field. Note that null will be returned if the field's value is null or a null sub-field was encountered while traversing to the field provided

Throws:

java.lang.RuntimeException - if the field doesn't exist

getField

public final java.lang.Object getField(int fieldIndex)
                                throws TupleException

Return the value of the field at a specified field index.

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

an Object of the proper type for this field. Note that null will be returned if the field's value is null.

Throws:

TupleException - if the field doesn't exist

getFieldAsString

public final java.lang.String getFieldAsString(Schema.Field field,
                                               Tuple.TupleFormatter formatter)

Get the current field as a human readable string, using the Tuple.TupleFormatter provided. StreamBase provides a default formatter via Tuple.getTupleFormatter() as a convenience.

Parameters:

field - the field to get

formatter - used to format the field value

Returns:

a string representation of the field

Throws:

java.lang.RuntimeException - if there was a conversion error or if the field doesn't exist (also applies to fields contained in a field of type Tuple whose current value is null)

getField

public final java.lang.Object getField(java.lang.String fieldPathName)
                                throws TupleException

Return the value of a named field. See type-specific getStreamBaseType() methods for information related to the fields of each specific type.

Escaping field names and path segments:

Path name segments may begin with #" (hash, double-quote) and end with " (double-quote) in order to escape normally disallowed characters. When using this syntax, all inner quotes and backslashes must be escaped with backslashes, similar to syntax used for SSQL string literals.

Parameters:

fieldPathName - the path name of the field to get

Returns:

an Object of the proper type for this field. Note that null will be returned if the field's value is null or a null sub-field was encountered while traversing to the field provided

Throws:

TupleException - if the field doesn't exist

isNull

public final boolean isNull(java.lang.String fieldPathName)
                     throws TupleException

Determines whether a field in the tuple is null.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Returns:

true if the field's value is null, false otherwise

Throws:

TupleException - when a field with the given path name does not exist in this Tuple

isNull

public final boolean isNull(int fieldIndex)
                     throws TupleException

Determines whether a field in the tuple is null.

Parameters:

fieldIndex - the index (0-based) of the field to check for a null value

Returns:

true if the field's value is null, false otherwise

Throws:

TupleException - when a field with the given path name does not exist in this Tuple

isNull

public boolean isNull(Schema.Field field)

Determines whether the given field's value in this Tuple is null.

The Field objects used to set and get Tuple field values must be obtained via the Tuple's Schema object. A Field object that has been created by the user or retrieved from a different Schema will not work.

Parameters:

field - the field to check for a null value

Returns:

true if the field's value is null (or a sub-field encountered while traversing to the given field was null), false otherwise

setBoolean

public final void setBoolean(java.lang.String fieldPathName,
                             boolean value)
                      throws TupleException,
                             NullValueException

Set a named boolean field to a specified value.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

setBoolean

public final void setBoolean(int fieldIndex,
                             boolean value)
                      throws TupleException,
                             NullValueException

Set the boolean field at a specified field index to a specified value.

Parameters:

fieldIndex - The index of the field to set (starting at 0)

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

setBoolean

public void setBoolean(Schema.Field field,
                       boolean value)
                throws TupleException

Set a named boolean field to a specified value.

Parameters:

field - the field to set

value - the value to set the field to

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

setDouble

public final void setDouble(java.lang.String fieldPathName,
                            double value)
                     throws TupleException,
                            NullValueException

Set a named double field to a specified value.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

setDouble

public final void setDouble(int fieldIndex,
                            double value)
                     throws TupleException,
                            NullValueException

Set the double field at a specified field index to a specified value.

Parameters:

fieldIndex - The index of the field to set (starting at 0)

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

setDouble

public void setDouble(Schema.Field field,
                      double value)
               throws TupleException

Set a named double field to a specified value.

Parameters:

field - the field to set

value - the value to set the field to

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

setInt

public final void setInt(java.lang.String fieldPathName,
                         int value)
                  throws TupleException,
                         NullValueException

Set the named int field to a specified value.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

setInt

public final void setInt(int fieldIndex,
                         int value)
                  throws TupleException,
                         NullValueException

Set the int field at a specified field index to a specified value.

Parameters:

fieldIndex - The index of the field to set (starting at 0)

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

setInt

public void setInt(Schema.Field field,
                   int value)
            throws TupleException

Set a specified int field to a specified value.

Parameters:

field - the field to set

value - the value to set the field to

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

setBlobBuffer

public final void setBlobBuffer(java.lang.String fieldPathName,
                                ByteArrayView value)
                         throws TupleException

Set a named blob field to a copy of a specified blob.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setBlobBuffer

public final void setBlobBuffer(int fieldIndex,
                                ByteArrayView value)
                         throws TupleException

Set the blob field at a specified field index to a copy of a specified blob.

Parameters:

fieldIndex - The index of the field to set (starting at 0)

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setBlobBuffer

public void setBlobBuffer(Schema.Field field,
                          ByteArrayView value)
                   throws TupleException

Set a specified blob field to a copy of a specified blob.

Parameters:

field - the field to set

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

setLong

public final void setLong(java.lang.String fieldPathName,
                          long value)
                   throws TupleException,
                          NullValueException

Set a named long field to a specified value.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

setLong

public final void setLong(int fieldIndex,
                          long value)
                   throws TupleException,
                          NullValueException

Set the long field at a specified field index to a specified value.

Parameters:

fieldIndex - The index of the field to set (starting at 0)

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

setLong

public void setLong(Schema.Field field,
                    long value)
             throws TupleException

Set a specified long field to a specified value.

Parameters:

field - the field to set

value - the value to set the field to

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

setList

public final void setList(java.lang.String fieldPathName,
                          java.util.List<?> value)
                   throws TupleException,
                          NullValueException

Set a named list field to a copy of a specified value.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

Since:

6.3

setList

public final void setList(int fieldIndex,
                          java.util.List<?> value)
                   throws TupleException,
                          NullValueException

Set the list field at a specified field index to a copy of the specified value.

Parameters:

fieldIndex - The index of the field to set (starting at 0)

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value of the field is null

Since:

6.3

setList

public void setList(Schema.Field field,
                    java.util.List<?> value)
             throws TupleException

Set a specified list field to a copy of a specified value.

Parameters:

field - the field to set

value - the value to set the field to

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

Since:

6.3

setString

public final void setString(java.lang.String fieldPathName,
                            java.lang.CharSequence value)
                     throws TupleException

Set a named field to a specified value. Works only on String types, use setField() to coerce type.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

Since:

6.5 CharSequence version of method added

setString

public final void setString(int fieldIndex,
                            java.lang.CharSequence value)
                     throws TupleException

Set the string field at a specified field index to a specified value.

Parameters:

fieldIndex - The index of the field to set (starting at 0)

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

Since:

6.5 CharSequence version of method added

setString

public final void setString(Schema.Field field,
                            java.lang.CharSequence value)
                     throws TupleException

Set a specified string field to a specified value.

Parameters:

field - The field to set

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

Since:

6.5 CharSequence version of method added

setTimestamp

public final void setTimestamp(java.lang.String fieldPathName,
                               Timestamp value)
                        throws TupleException

Set a named timestamp field to a specified value.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setTimestamp

public final void setTimestamp(int fieldIndex,
                               Timestamp value)
                        throws TupleException

Set the timestamp field at a specified field index to a specified value.

Parameters:

fieldIndex - The index of the field to set (starting at 0)

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setTimestamp

public void setTimestamp(Schema.Field field,
                         Timestamp value)
                  throws TupleException

Set a named timestamp field to a specified value.

Parameters:

field - The field to set

value - the value to set the field to

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

setTuple

public final void setTuple(java.lang.String fieldPathName,
                           Tuple value)
                    throws TupleException

Set a named nested tuple field to a specified tuple.

NOTE: A copy of the tuple may be made to convert the given tuple to the appropriate internal representation. Use Tuple.getAllocatedTuple(String) if you require a reference (not a copy) of the nested tuple to achieve a zero copy setTuple. For example:

    Tuple nestedReference = tuple.getAllocatedTuple("fieldName");
    nestedReference.set...;
    nestedReference.set...;
    // tuple.setTuple("fieldName", nestedReference); is not needed
 

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setTuple

public final void setTuple(int fieldIndex,
                           Tuple value)
                    throws TupleException

Set a specified nested tuple field to that of the specified tuple.

NOTE: A copy of the tuple may be made to convert the given tuple to the appropriate internal representation. Use Tuple.getAllocatedTuple(Schema.Field) if you require a reference (not a copy) of the nested tuple to achieve a zero copy setTuple. For example:

    Tuple nestedReference = tuple.getAllocatedTuple(field);
    nestedReference.set...;
    nestedReference.set...;
    // tuple.setTuple("fieldName", nestedReference); is not needed
 

Parameters:

fieldIndex - the index of the field to set (starting at 0)

value - the value to set the field to

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setTuple

public void setTuple(Schema.Field field,
                     Tuple value)
              throws TupleException

Set a specified nested tuple field to that of the specified tuple NOTE: A copy of the the tuple may be made to convert the given tuple to the appropriate internal representation. Use Tuple.getAllocatedTuple(Schema.Field) if you require a reference (not a copy) of the nested tuple For a zero copy setTuple do the following:

    Tuple nestedReference = tuple.getAllocatedTuple(field);
    nestedReference.set...;
    nestedReference.set...;
    // tuple.setTuple(field, nestedReference); is not needed and
    //  in fact would cause an extra copy
 

Parameters:

field - the field to set

value - the tuple to set the field to

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

getFields

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

Deprecated. use Tuple.toMapView()

Return a Map containing a list of all the field values of the tuple as Objects. The key is the field name as a String.

Returns:

A Map containing all values from the tuple. Note that if the field is null in the tuple, it will not be included in the returned Map.

Since:

6.0

See Also:

Tuple.toMapView()

setFields

public void setFields(java.util.Map<java.lang.String,java.lang.Object> fields)
               throws TupleException

Takes a map of field names and values as Objects and sets the corresponding tuple field with the supplied value. All fields not present in the map are set to null in the tuple.

Parameters:

fields - map of field names and values

Throws:

TupleException - thrown if there was a conversion error

Since:

7.4 no longer throws an error if the input map length does not match this Tuple's fieldcount

setCapture

public final void setCapture(Schema.Field field,
                             Tuple value)
                      throws TupleException

Set a specified capture field to a copy of a specified tuple.

Parameters:

field - the field to set

value - the value to set the field to. Must be of the correct type for this capture field

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

Since:

7.2

setCapture

public final void setCapture(java.lang.String field,
                             Tuple value)
                      throws TupleException

Set a specified capture field to a copy of a specified tuple.

Parameters:

field - the field to set

value - the value to set the field to. Must be of the correct type for this capture field

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

Since:

7.2

setCapture

public final void setCapture(int field,
                             Tuple value)
                      throws TupleException

Set a specified capture field to a copy of a specified tuple.

Parameters:

field - the field to set

value - the value to set the field to. Must be of the correct type for this capture field

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

Since:

7.2

getFunction

public final Function getFunction(int fieldIndex)
                           throws TupleException

Return the value of the function field at a specified field index.

Parameters:

fieldIndex - the index of the field to get (starting at 0)

Returns:

a Function for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

Since:

7.4

getFunction

public final Function getFunction(java.lang.String fieldName)
                           throws TupleException

Return the value of the named function field.

Parameters:

fieldName - the name of the field to get

Returns:

a Function for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

Since:

7.4

getFunction

public final Function getFunction(Schema.Field field)
                           throws TupleException

Return the value of the given function field.

Parameters:

field - the field to get

Returns:

a Function for the given field

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

NullValueException - if the value is null

Since:

7.4

setFunction

public final void setFunction(int field,
                              Function value)
                       throws TupleException

Set a specified function field to the given Function

Parameters:

field - the index of the field to set

value - the value to set the field to. Must be of the correct type for this function field.

Throws:

TupleException - if there was a value conversion error, or the field doesn't exist in this Tuple.

Since:

7.4

setFunction

public final void setFunction(java.lang.String field,
                              Function value)
                       throws TupleException

Set a specified function field to the given Function

Parameters:

field - the name or path of the field to set

value - the value to set the field to. Must be of the correct type for this function field

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

Since:

7.4

setFunction

public final void setFunction(Schema.Field field,
                              Function value)
                       throws TupleException

Set a specified function field to the given Function

Parameters:

field - the field to set

value - the value to set the field to. Must be of the correct type for this function field. This can be null to set this field to null.

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

Since:

7.4

setField

public final void setField(java.lang.String fieldPathName,
                           java.lang.Object value)
                    throws TupleException

Set the named field to a specified value.

See Tuple.setField(Schema.Field, Object) for a discussion of possible conversions of the value.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setField

public final void setField(java.lang.String fieldPathName,
                           java.lang.Object value,
                           com.streambase.sb.util.CSV.FormatInfo format)
                    throws TupleException

Set the field at a specified field name to a specified boxed value.

See Tuple.setField(Schema.Field, Object) for a discussion of possible conversions of the value.

Parameters:

fieldPathName - the name of the field to set

value - the value to set the field to. This can be null to set the field to null.

format - the FormatInfo to use when parsing items, such as timestamp strings, in the value.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setField

public final void setField(int fieldIndex,
                           java.lang.Object value)
                    throws TupleException

Set the field at a specified field index to a specified boxed value.

See Tuple.setField(Schema.Field, Object) for a discussion of possible conversions of the value.

Parameters:

fieldIndex - the index of the field to set (starting at 0)

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setField

public final void setField(Schema.Field field,
                           java.lang.Object value)
                    throws TupleException

Set a specified field to a specified boxed value.

If the value is not a natural type for the type of the specified field, this method attempts to convert the value based on the field's type. (A "natural type" for a field type is the Java type that is acceptable to a type-specific setXxx() method for that field. In the list below, the natural types for each StreamBase type are listed in parentheses after each type.)

Conversions:

int (Integer), double (Double), long (Long)

Numeric value types are converted (possibly with loss of precision) if necessary. For all other values types, the value is converted to a String (with Object.toString()) and an attempt is made to parse the string into a numeric value of the required type.

boolean (Boolean):

The value is converted to a String, turned to lowercase, and then checked for the string values "true", "yes", "1", and "t" (all of which result in the field being set to true) and "false", "no", "0", and "f" (all of which result in the field being set to false).

string (String):

Values of type ByteArrayView and byte[] are assigned by converting the bytes to a string using an internal StreamBase conversion routine. For all other value types, the value is converted to a String with Object.toString().

timestamp (Timestamp):

Values of type Date are converted with Timestamp.Timestamp(java.util.Date). Numeric value types are treated as a number of seconds (time interval).

blob (byte[], ByteArrayView):

If the value is a String, it's converted to an array of bytes, representing the ASCII encoding of the string's characters unless overridden by the setting of the streambase.tuple-charset Java property.

tuple (Tuple):

If the value is a String, it's parsed as a CSV-formatted list of field values (e.g., "1,foo").

list (List):

If the value is a String, it's parsed as a square-bracketed, CSV-formatted list of element values (e.g., "[1,3,5]").

If a conversion is required, this method may run more slowly than if a conversion is not required. Use of the conversion ability of this method in performance-critical code should be avoided.

If a conversion is required but none of the above conversions apply, a TupleException exception is thrown

Note on CSV (comma-separated values) format: In the case of list or tuple fields which themselves contain list or tuple values, care must be taken to properly use double quotes where necessary. (The presence of commas in those nested values in the CSV string requires them to be surrounded by quotes. Further nesting may require increased quoting.) See RFC 4180 for details on CSV format.

Parameters:

field - field to set

value - the value to set the field to. This can be null to set the field to null.

Throws:

TupleException - if there was a value conversion error, the field doesn't exist in this Tuple or while traversing to a sub-field a null value was encountered

Since:

6.0

setField

public final void setField(Schema.Field field,
                           java.lang.Object value,
                           com.streambase.sb.util.CSV.FormatInfo format)
                    throws TupleException

Set the field at a specified field name to a specified boxed value.

See Tuple.setField(Schema.Field, Object) for a discussion of possible conversions of the value.

Parameters:

field - field to set

value - the value to set the field to. This can be null to set the field to null.

format - the FormatInfo to use when parsing items, such as timestamp strings, in the value.

Throws:

TupleException - if there was a conversion error or if the field doesn't exist

setNull

public final void setNull(java.lang.String fieldPathName)
                   throws TupleException

Set a named field to null.

Parameters:

fieldPathName - the path name of the field to get. See Tuple.getField(String) for notes on path segment syntax.

Throws:

TupleException - thrown when the Field cannot be found

setNull

public final void setNull(int fieldIndex)

Set the field at a specified field index to null.

Parameters:

fieldIndex - the index of the field to set to null (starting at 0)

setNull

public void setNull(Schema.Field field)

Set the specified field to null

Parameters:

field - the field to set to null

toString

public java.lang.String toString(boolean verbose)

Return a string representation of this Tuple. The delimiter is a comma and the quote character is a double quote.

Parameters:

verbose - should field names and tuple id (if available) be included?

Returns:

a string representation of this Tuple

toString

public java.lang.String toString(char delimiter,
                                 boolean verbose)

Deprecated.

Deprecated. Returns a string representation of this Tuple.

Parameters:

delimiter - the character to insert between each field

verbose - should field names and tuple id (if available) be included?

Returns:

a string representation of this Tuple

See Also:

Tuple.toString(char,char,boolean)

toString

public java.lang.String toString(char delimiter,
                                 char quoteChar,
                                 boolean verbose)

Return a string representation of this Tuple.

Parameters:

delimiter - the character to insert between each field

quoteChar - the character used to surround string fields

verbose - should field names and tuple id (if available) be included?

Returns:

a string representation of this Tuple

toString

public java.lang.String toString(char delimiter,
                                 char quoteChar,
                                 boolean verbose,
                                 boolean showTupleId)

Return a string representation of this Tuple.

Parameters:

delimiter - the character to insert between each field

quoteChar - the character used to surround string fields

verbose - should field names be included?

showTupleId - should the tuple id, if available, be shown?

Returns:

a string representation of this Tuple

toString

public java.lang.String toString(char delimiter,
                                 char quoteChar,
                                 boolean verbose,
                                 java.lang.String nullString)

Return a string representation of this Tuple.

Parameters:

delimiter - the character to insert between each field

quoteChar - the character used to surround string fields

verbose - should field names and tuple id (if available) be included?

nullString - the string to use for null field values

Returns:

a string representation of this Tuple

toString

public java.lang.String toString(char delimiter,
                                 char quoteChar,
                                 boolean verbose,
                                 boolean showTupleId,
                                 java.lang.String nullString)

Return a string representation of this Tuple.

Parameters:

delimiter - the character to insert between each field

quoteChar - the character used to surround string fields

verbose - should field names be included?

showTupleId - should the tuple id, if available, be shown?

nullString - the string to use for null field values

Returns:

a string representation of this Tuple

equals

public boolean equals(java.lang.Object obj)

Test whether the given object is equal to this one. Tuples are considered equal if all of their fields are equal, and their schemas match exactly (including order of fields).

Overrides:

equals in class java.lang.Object

Parameters:

obj - object to test

Returns:

true if the two objects are equal; false otherwise

hashCode

public int hashCode()

Compute a hashCode for the object.

Overrides:

hashCode in class java.lang.Object

Returns:

integer hashCode for object

toDelimitedString

public java.lang.String toDelimitedString(char delimiter)

Return the tuple as a string delimited by the given character.

Parameters:

delimiter - the delimiter

Returns:

the tuple as a string delimited by the given character.

createWritableTuple

public abstract Tuple createWritableTuple()

Return a new tuple that is guaranteed to be writable

Returns:

a writable tuple

createReadOnlyTuple

public abstract Tuple createReadOnlyTuple()

Return a new tuple that is guaranteed to be read only

Returns:

a read only tuple

Since:

7.0

copyField

public void copyField(Schema.Field sourceField,
                      Tuple destTuple,
                      Schema.Field destField)
               throws TupleException

Copy the field from this tuple to the destination tuple

Parameters:

sourceField - the source field

destTuple - the destination tuple

destField - the destination field

Throws:

TupleException - if type mismatch, missing fields

Since:

6.4.5

toMapView

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

Returns a view on this Tuple that implements the Map<String, Object> interface. Changes to this Tuple will be reflected in the returned Map<String, Object> and vice versa.

The keys of this map are the field names of the schema of this tuple.

The values of this map are the current values of this map. These values are the same as returned by Tuple.getField(String).

Map<String, Object>.get(Object key) will return a null for fields that are null and that do not exist in this Tuple. Use Map<String, Object>.containsKey(Object key) to determine if a key is a valid field in this Tuple.

Repeated calls to Tuple.toMapView() will return the same instance of Map<String, Object>.

This Map<String, Object> does not support any remove operations. This Map is backed by a Tuple with a fixed schema. Any modify operations that attempt to address keys that are not in the fixed schema are not supported.

Returns:

a Map<String, Object> view of this Tuple.

Since:

7.0

getTupleFormatter

public static Tuple.TupleFormatter getTupleFormatter()

Returns a shared instance of the default tuple field formatter that converts each type to String using Java default String conversions. For string formatting rules used by each type, see Tuple.DefaultTupleFormatter.

Returns:

a Tuple.TupleFormatter instance suitable for use in Tuple.getFieldAsString(Schema.Field, TupleFormatter)

Since:

7.0 method added, 7.1 tuples and lists recursively use the formatter for sub-fields and elements

checkTypeAndNonNull

protected int checkTypeAndNonNull(Schema.Field resolvedField,
                                  DataType dataType)
                           throws TupleException

check the type and make sure it is non null

Parameters:

resolvedField - resolved field

dataType - data type

Returns:

field index or other information (depending upon overrides)

Throws:

TupleException - on error

checkType

protected void checkType(Schema.Field resolvedField,
                         DataType dataType)
                  throws TupleException

Throws:

TupleException

copyTuple

protected void copyTuple(Tuple sourceTuple)
                  throws TupleException

copy the source tuple to this tuple

Parameters:

sourceTuple - source tuple to be copied

Throws:

TupleException - on error