com.ibm.streams.operator

Interface Tuple

All Known Subinterfaces:

OutputTuple

public interface Tuple

A representation of a stream's tuple. The order of the attributes match the corresponding StreamSchema for the Stream that generated the tuple.
The type of the object for an attribute is defined by its type and the mapping between SPL and Java is shown by Type.MetaType.

Instances of Tuple implement java.io.Serializable. Serializing a tuple will also serialize its StreamSchema reference.

See Also:

StreamingData, StreamSchema, Type.MetaType

Method Summary

Modifier and Type	Method and Description
Tuple	asReadOnlyTuple() Get an immutable version of this tuple.
java.math.BigDecimal	getBigDecimal(int attributeIndex) Get an attribute as a BigDecimal.
java.math.BigDecimal	getBigDecimal(java.lang.String attributeName) Get the attribute as an BigDecimal using the attribute's name.
Blob	getBlob(int attributeIndex) Get an attribute as a Blob.
Blob	getBlob(java.lang.String attributeName) Get the attribute as a Blob using the attribute's name.
boolean	getBoolean(int attributeIndex) Get an attribute as a primitive boolean.
boolean	getBoolean(java.lang.String attributeName) Get the attribute as a boolean using the attribute's name.
java.nio.Buffer	getBuffer(int attributeIndex) Get an attribute as a read-only java.nio.Buffer.
<T extends java.nio.Buffer> T	getBuffer(int attributeIndex, java.lang.Class<T> type) Get the attribute as a buffer of type T using the attribute's index.
java.nio.Buffer	getBuffer(java.lang.String attributeName) Get the attribute as a java.nio.Buffer using the attribute's name.
<T extends java.nio.Buffer> T	getBuffer(java.lang.String attributeName, java.lang.Class<T> type) Get the attribute as a buffer of type T using the attribute's name.
byte	getByte(int attributeIndex) Get an attribute as a primitive byte.
byte	getByte(java.lang.String attributeName) Get the attribute as a byte using the attribute's name.
double	getDouble(int attributeIndex) Get an attribute as a primitive double.
double	getDouble(java.lang.String attributeName) Get the attribute as a double using the attribute's name.
<E extends java.lang.Enum<E>> E	getEnum(java.lang.Class<E> enumType, int attributeIndex) Get an attribute as an enumeration.
<E extends java.lang.Enum<E>> E	getEnum(java.lang.Class<E> enumType, java.lang.String attributeName) Get the attribute as an enumeration using the attribute's name.
float	getFloat(int attributeIndex) Get an attribute as a primitive float.
float	getFloat(java.lang.String attributeName) Get the attribute as a float using the attribute's name.
int	getInt(int attributeIndex) Get an attribute as a primitive int.
int	getInt(java.lang.String attributeName) Get the attribute as an int using the attribute's name.
java.util.List<?>	getList(int attributeIndex) Get an attribute as a List.
java.util.List<?>	getList(java.lang.String attributeName) Get the attribute as a java.util.List using the attribute's name.
long	getLong(int attributeIndex) Get an attribute as a primitive long.
long	getLong(java.lang.String attributeName) Get the attribute as a long using the attribute's name.
java.util.Map<?,?>	getMap(int attributeIndex) Get an attribute as a Map.
java.util.Map<?,?>	getMap(java.lang.String attributeName) Get the attribute as a java.util.Map using the attribute's name.
java.lang.Object	getObject(int attributeIndex) Get the object representing the attribute's value at given index.
<T> T	getObject(int attributeIndex, java.lang.Class<T> type) Get an object of type T representing the attribute's value at given index.
java.lang.Object	getObject(java.lang.String attributeName) Get the attribute as an Object using the attribute's name.
<T> T	getObject(java.lang.String attributeName, java.lang.Class<T> type) Get the attribute as an object of type T using the attribute's name.
java.util.Set<?>	getSet(int attributeIndex) Get an attribute as a Set.
java.util.Set<?>	getSet(java.lang.String attributeName) Get the attribute as a java.util.Set using the attribute's name.
short	getShort(int attributeIndex) Get an attribute as a primitive short.
short	getShort(java.lang.String attributeName) Get the attribute as a short using the attribute's name.
StreamSchema	getStreamSchema() Get the StreamSchema for this Tuple.
java.lang.String	getString(int attributeIndex) Get an attribute as a String.
java.lang.String	getString(java.lang.String attributeName) Get the attribute as a String using the attribute's name.
Timestamp	getTimestamp(int attributeIndex) Get an attribute as a Timestamp.
Timestamp	getTimestamp(java.lang.String attributeName) Get the attribute as a Timestamp using the attribute's name.
Tuple	getTuple(int attributeIndex) Get an attribute as a Tuple.
Tuple	getTuple(java.lang.String attributeName) Get the attribute as a Tuple using the attribute's name.
XML	getXML(int attributeIndex) Get an attribute as an XML.
XML	getXML(java.lang.String attributeName) Get the attribute as an XML using the attribute's name.

Method Detail

getStreamSchema

StreamSchema getStreamSchema()

Get the StreamSchema for this Tuple.

Returns:

The schema for the tuple.

getObject

java.lang.Object getObject(int attributeIndex)

Get the object representing the attribute's value at given index. The class of the returned object is equal to the return of Type.getObjectType() for the attribute's type.

If the returned object is mutable (such as Java arrays) then modifying the returned object will not modify the state of this tuple as getObject() will return a copy of its internal state.
To avoid such a copy, getBuffer() may be used for most List types.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The attribute's value for this tuple as an object.

See Also:

getBuffer(int)

getObject

<T> T getObject(int attributeIndex,
                java.lang.Class<T> type)

Get an object of type T representing the attribute's value at given index. The type T must match the class type of the attribute's object type. This method does not perform any type conversion.

If the returned object is mutable (such as Java arrays) then modifying the returned object will not modify the state of this tuple as getObject() will return a copy of its internal state.
To avoid such a copy, getBuffer() may be used for most List types.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

type - Class for the type to be returned

Returns:

The attribute's value for this tuple as an object.

Throws:

java.lang.ClassCastException - Attribute's object type does not match type.

Since:

InfoSphere® Streams Version 3.1

See Also:

getObject(int), getBuffer(int)

getBoolean

boolean getBoolean(int attributeIndex)

Get an attribute as a primitive boolean. Only supported for attributes of type BOOLEAN.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a boolean.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java primitive boolean

getByte

byte getByte(int attributeIndex)

Get an attribute as a primitive byte. Only supported for attributes of type INT8 and UINT8.
UINT8 attributes are returned as a 8-bit signed two's complement integer, getInt may be used to to obtain a true representation of the unsigned value.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a byte.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java primitive byte

getShort

short getShort(int attributeIndex)

Get an attribute as a primitive short. Only supported for attributes of type INT16, INT8, UINT16 and UINT8.
UINT16 attributes are returned as a 16-bit signed two's complement integer, getInt may be used to to obtain a true representation of the unsigned value.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a short.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java primitive short

getInt

int getInt(int attributeIndex)

Get an attribute as a primitive int. Only supported for attributes of type INT32, INT16, INT8, UINT32, UINT16 and UINT8.
UINT32 attributes are returned as a 32-bit signed two's complement integer, getLong may be used to to obtain a true representation of the unsigned value at the cost of using an 8-byte value.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a int.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java primitive int

getLong

long getLong(int attributeIndex)

Get an attribute as a primitive long. Only supported for attributes of type INT64, INT32, INT16, INT8, UINT64 UINT32, UINT16 and UINT8.
UINT64 attributes are returned as a 64-bit signed two's complement integer, getBigDecimal may be used to to obtain a true representation of the unsigned value at the cost of using a BigDecimal object.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a long.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java primitive long

getFloat

float getFloat(int attributeIndex)

Get an attribute as a primitive float. Only supported for attributes of type FLOAT32.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a float.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java primitive float

getDouble

double getDouble(int attributeIndex)

Get an attribute as a primitive double. Only supported for attributes of type FLOAT64, and FLOAT32.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a double.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java primitive double

getBigDecimal

java.math.BigDecimal getBigDecimal(int attributeIndex)

Get an attribute as a BigDecimal. Only supported for attributes of type INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT32, FLOAT64, DECIMAL32, DECIMAL64 and DECIMAL128.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a BigDecimal.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java BigDecimal

getString

java.lang.String getString(int attributeIndex)

Get an attribute as a String. Returns a string that "textually represents" the attribute's value, typically using Object.toString() of the Java object class corresponding to the attribute's SPL type. The returned value is not always the same as SPL character encoding for the type, specifically:

• USTRING and RSTRING attributes return the corresponding Java String value, not an SPL string literal with escaped values.
• XML attributes return the corresponding Java String value, not an SPL XML literal with escaped values and suffix x.
• LIST, MAP, SET attributes return the value of toString() against the Java collection object.
• TUPLE attributes return the value of Tuple.toString().

All attributes are supported in InfoSphere® Streams Version 4.0: USTRING, RSTRING (using UTF-8 encoding), BOOLEAN (since InfoSphere® Streams Version 3.0), BLOB (using Blob.toString(), since 4.0), COMPLEX32 (see newComplex32(), since 4.0), COMPLEX64 (see newComplex64(), since 4.0), ENUM (since 3.0), INT64, INT32, INT16, INT8, LIST (using List.toString() since 4.0), MAP (using Map.toString() since 4.0), SET (using Set.toString() since 4.0), TUPLE (using Tuple.toString() since 4.0), UINT64, UINT32, UINT16, UINT8, FLOAT32, FLOAT64, TIMESTAMP (using Timestamp.toString(), since 4.0), XML (since 3.0)

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a String.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java String

getTimestamp

Timestamp getTimestamp(int attributeIndex)

Get an attribute as a Timestamp. Only supported for attributes of type TIMESTAMP

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a Timestamp.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Timestamp

getBuffer

java.nio.Buffer getBuffer(int attributeIndex)

Get an attribute as a read-only java.nio.Buffer. Only supported for the following types and each type returns a specific Buffer sub-class. Type.MetaType

java.nio.Buffer sub-class
BLOB	java.nio.ByteBuffer
LIST (list<float32>)	java.nio.FloatBuffer
LIST (list<float64>)	java.nio.DoubleBuffer
LIST (list<int8>)	java.nio.ByteBuffer
LIST (list<int16>)	java.nio.ShortBuffer
LIST (list<int32>)	java.nio.IntegerBuffer
LIST (list<int64>)	java.nio.LongBuffer
RSTRING	java.nio.ByteBuffer
LIST (list<uint8>)	java.nio.ByteBuffer (since InfoSphere Streams 3.1)
LIST (list<uint16>)	java.nio.ShortBuffer (since InfoSphere Streams 3.1)
LIST (list<uint32>)	java.nio.IntegerBuffer (since InfoSphere Streams 3.1)
LIST (list<uint64>)	java.nio.LongBuffer (since InfoSphere Streams 3.1)

This call provides a read-only view of the attribute's value without having to make a copy of the underlying data, as getObject() will do.

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a read-only Buffer.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java Buffer

getBuffer

<T extends java.nio.Buffer> T getBuffer(int attributeIndex,
                                        java.lang.Class<T> type)

Get the attribute as a buffer of type T using the attribute's index. The type T must match the buffer type of the attribute as described in getBuffer(int). This method does not perform any type conversion.

Type Parameters:

T - Sub-class of java.nio.Buffer

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

type - Class for the buffer type to be returned.

Returns:

The value as a read-only Buffer.

Since:

InfoSphere® Streams Version 3.1

See Also:

getBuffer(int)

getBlob

Blob getBlob(int attributeIndex)

Get an attribute as a Blob. Only supported for attributes of type BLOB

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a Blob.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Blob

getList

java.util.List<?> getList(int attributeIndex)

Get an attribute as a List. Only supported for attributes of type LIST

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a read-only List.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java List

getSet

java.util.Set<?> getSet(int attributeIndex)

Get an attribute as a Set. Only supported for attributes of type SET,

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a read-only Set.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java Set

getMap

java.util.Map<?,?> getMap(int attributeIndex)

Get an attribute as a Map. Only supported for attributes of type MAP,

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a read-only Map.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to a Java Map

getTuple

Tuple getTuple(int attributeIndex)

Get an attribute as a Tuple. Only supported for attributes of type TUPLE,

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as a Tuple.

Throws:

java.lang.UnsupportedOperationException - Attribute is not a tuple type.

getBoolean

boolean getBoolean(java.lang.String attributeName)

Get the attribute as a boolean using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a boolean.

See Also:

getBoolean(int)

getByte

byte getByte(java.lang.String attributeName)

Get the attribute as a byte using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a byte.

See Also:

getByte(int)

getShort

short getShort(java.lang.String attributeName)

Get the attribute as a short using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a short.

See Also:

getShort(int)

getInt

int getInt(java.lang.String attributeName)

Get the attribute as an int using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a int.

See Also:

getInt(int)

getLong

long getLong(java.lang.String attributeName)

Get the attribute as a long using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a long.

See Also:

getLong(int)

getFloat

float getFloat(java.lang.String attributeName)

Get the attribute as a float using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a float.

See Also:

getFloat(int)

getDouble

double getDouble(java.lang.String attributeName)

Get the attribute as a double using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a double.

See Also:

getDouble(int)

getBigDecimal

java.math.BigDecimal getBigDecimal(java.lang.String attributeName)

Get the attribute as an BigDecimal using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a BigDecimal.

See Also:

getBigDecimal(int)

getString

java.lang.String getString(java.lang.String attributeName)

Get the attribute as a String using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a String.

See Also:

getString(int)

getTimestamp

Timestamp getTimestamp(java.lang.String attributeName)

Get the attribute as a Timestamp using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a Timestamp.

See Also:

getTimestamp(int)

getBuffer

java.nio.Buffer getBuffer(java.lang.String attributeName)

Get the attribute as a java.nio.Buffer using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a java.nio.Buffer.

See Also:

getBuffer(int)

getBuffer

<T extends java.nio.Buffer> T getBuffer(java.lang.String attributeName,
                                        java.lang.Class<T> type)

Get the attribute as a buffer of type T using the attribute's name.

Type Parameters:

T - Sub-class of java.nio.Buffer

Parameters:

attributeName - Name of attribute to be returned.

type - Class for the buffer type to be returned.

Returns:

The value as a typed buffer.

Since:

InfoSphere® Streams Version 3.1

See Also:

getObject(int, Class)

getBlob

Blob getBlob(java.lang.String attributeName)

Get the attribute as a Blob using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a Blob.

See Also:

getBlob(int)

getList

java.util.List<?> getList(java.lang.String attributeName)

Get the attribute as a java.util.List using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a java.util.List.

See Also:

getList(int)

getSet

java.util.Set<?> getSet(java.lang.String attributeName)

Get the attribute as a java.util.Set using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a java.util.Set.

See Also:

getSet(int)

getMap

java.util.Map<?,?> getMap(java.lang.String attributeName)

Get the attribute as a java.util.Map using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a java.util.Map.

See Also:

getMap(int)

getTuple

Tuple getTuple(java.lang.String attributeName)

Get the attribute as a Tuple using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as a Tuple.

See Also:

getTuple(int)

getObject

java.lang.Object getObject(java.lang.String attributeName)

Get the attribute as an Object using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as an Object.

See Also:

getObject(int)

getObject

<T> T getObject(java.lang.String attributeName,
                java.lang.Class<T> type)

Get the attribute as an object of type T using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

type - Class for the type to be returned.

Returns:

The value as an Object.

Since:

InfoSphere® Streams Version 3.1

See Also:

getObject(int, Class)

getXML

XML getXML(int attributeIndex)

Get an attribute as an XML. Only supported for attributes of type XML

Parameters:

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as an XML.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to an XML

Since:

InfoSphere® Streams Version 3.0

getXML

XML getXML(java.lang.String attributeName)

Get the attribute as an XML using the attribute's name.

Parameters:

attributeName - Name of attribute to be returned.

Returns:

The value as an XML .

Since:

InfoSphere® Streams Version 3.0

See Also:

getXML(int)

getEnum

<E extends java.lang.Enum<E>> E getEnum(java.lang.Class<E> enumType,
                                        int attributeIndex)

Get an attribute as an enumeration. Only supported for attributes of type ENUM

Type Parameters:

E - Enumeration type

Parameters:

enumType - Class of the enumeration type E.

attributeIndex - Index of attribute to be returned, zero is the tuple's first attribute.

Returns:

The value as an enumeration.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to an enumeration

java.lang.IllegalArgumentException - Identifier for the enum attribute is not a constant for E

Since:

InfoSphere® Streams Version 3.0

See Also:

EnumType

getEnum

<E extends java.lang.Enum<E>> E getEnum(java.lang.Class<E> enumType,
                                        java.lang.String attributeName)

Get the attribute as an enumeration using the attribute's name.

Type Parameters:

E - Enumeration type

Parameters:

enumType - Class of the enumeration type E.

attributeName - Name of attribute to be returned.

Returns:

The value as an enumeration.

Throws:

java.lang.UnsupportedOperationException - Attribute cannot be converted to an enumeration

java.lang.IllegalArgumentException - Identifier for the enum attribute is not a constant for E

Since:

InfoSphere® Streams Version 3.0

See Also:

getEnum(Class, int), EnumType

asReadOnlyTuple

Tuple asReadOnlyTuple()

Get an immutable version of this tuple. If this Tuple is immutable then this will be returned.

Returns:

An immutable version of this tuple

Since:

InfoSphere® Streams Version 3.0