Package com.streambase.sb

Class Tuple

    • Field Detail

      • EMPTY_TUPLE

        public static final Tuple EMPTY_TUPLE
        An empty tuple

      • 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 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

      • 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​(ByteOrderedDataOutput output)
        Serialize this tuple into a ByteOrderedDataOutput
        Parameters:
        output - the output stream

      • 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

      • 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(String)

      • 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(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 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

      • 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​(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

        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:
        toMapView()

      • 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

      • 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,
                           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,
                           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

      • 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

      • 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