Package com.streambase.sb

Class Tuple

java.lang.Object
com.streambase.sb.Tuple
All Implemented Interfaces:
com.streambase.sb.internal.CloneableData, Serializable, Cloneable
Direct Known Subclasses:
CompiledTuple
public abstract class Tuple extends Object implements Cloneable, com.streambase.sb.internal.CloneableData, 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 getDouble(Schema.Field) & setDouble(Schema.Field, double) methods work only on double fields. The 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 (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.

Note: The Serialization feature is DEPRECATED and will be removed in a future release.

See Also:

  • Field Details

    • EMPTY_TUPLE

      public static final Tuple EMPTY_TUPLE
      An empty tuple

    • NO_FLAGS

      protected static final int NO_FLAGS
      no flags
      See Also:

    • THROW_ON_NULL

      protected static final int THROW_ON_NULL
      during a get throw an exception on null
      See Also:

    • CREATE_IF_NULL

      protected static final int CREATE_IF_NULL
      during a get create tuple if it is null
      See Also:

    • NULL_STRING

      public static final String NULL_STRING
      The default String representation of a null valued field (value "null")
      See Also:

  • Method Details

    • 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 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 Object
      Returns:
      A copy of this Tuple
      Throws:
      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 serialize(ByteOrderedDataOutput)
      Parameters:
      output - the output stream
      tupleId - the tupleId to attach to this tuple
      See Also:

    • getBoolean

      public final boolean getBoolean(String fieldPathName) throws TupleException, NullValueException
      Return the value of a named boolean field.
      Parameters:
      fieldPathName - the path name of the field to get. See 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(String fieldPathName) throws TupleException, NullValueException
      Return the value of a named double field.
      Parameters:
      fieldPathName - the path name of the field to get. See 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(String fieldPathName) throws TupleException, NullValueException
      Return the value of a named int field.
      Parameters:
      fieldPathName - the path name of the field to get. See 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(String fieldPathName) throws TupleException, NullValueException
      Return the value of a named long field.
      Parameters:
      fieldPathName - the path name of the field to get. See 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 List<?> getList(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 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 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 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 String getString(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 getField(String).
      Parameters:
      fieldPathName - the path name of the field to get. See 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 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 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 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(String fieldPathName) throws TupleException, NullValueException
      Return the value of a named timestamp field.
      Parameters:
      fieldPathName - the path name of the field to get. See 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(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 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 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:

    • 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 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(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 setTuple(String, Tuple).
      Parameters:
      fieldPathName - the path name of the field to get. See 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:

    • getAllocatedTuple

      public final Tuple getAllocatedTuple(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 setTuple(Schema.Field, Tuple) to update the parent tuple.
      Parameters:
      fieldPathName - the path name of the field to get. See 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 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:

    • 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 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(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
      Get capture field
      Parameters:
      field - Field
      Returns:
      Capture field tuple
      Throws:
      TupleException - Error access capture field

    • getField

      public final 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:
      RuntimeException - if the field doesn't exist

    • getField

      public final 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 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 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:
      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 Object getField(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(String fieldPathName) throws TupleException
      Determines whether a field in the tuple is null.
      Parameters:
      fieldPathName - the path name of the field to get. See 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
      IllegalArgumentException - If the field is not part of the Tuple's schema
      Error - If there was an error accessing a nested 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
      IllegalArgumentException - If the field is not part of the Tuple's schema
      Error - If there was an error accessing a nested 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 and will throw an exception.

      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
      Throws:
      IllegalArgumentException - If the field is not part of the Tuple's schema
      Error - If there was an error accessing a nested Tuple

    • setBoolean

      public final void setBoolean(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 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(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 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(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 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(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 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(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 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(String fieldPathName, 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 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, 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, 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(String fieldPathName, 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 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, 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, 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(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 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(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 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 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 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 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

      @Deprecated public Map<String,Object> getFields()
      Deprecated.
      use 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:

    • setFields

      public void setFields(Map<String,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(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(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(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(String fieldPathName, Object value) throws TupleException
      Set the named field to a specified value.

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

      Parameters:
      fieldPathName - the path name of the field to get. See 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(String fieldPathName, 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 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, Object value) throws TupleException
      Set the field at a specified field index to a specified boxed value.

      See 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, 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(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, 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 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(String fieldPathName) throws TupleException
      Set a named field to null.
      Parameters:
      fieldPathName - the path name of the field to get. See 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 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 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 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 String toString(char delimiter, char quoteChar, boolean verbose, 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 String toString(char delimiter, char quoteChar, boolean verbose, boolean showTupleId, 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(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 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 Object
      Returns:
      integer hashCode for object

    • toDelimitedString

      public 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 Map<String,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 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 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 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
      Check type
      Parameters:
      resolvedField - Field
      dataType - Data type
      Throws:
      TupleException - Invalid type

    • 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