com.ibm.streams.operator

Interface StreamingOutput<T>

All Superinterfaces:

StreamingData

public interface StreamingOutput<T>
extends StreamingData

StreamingOutput represents an output port for an Operator.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	StreamingOutput.ExportType Enumeration for how a port exports its stream.

Nested classes/interfaces inherited from interface com.ibm.streams.operator.StreamingData

StreamingData.Punctuation

Method Summary

Modifier and Type	Method and Description
void	addStreamProperties(java.util.Map<java.lang.String,?> properties) Add a collection of stream properties to the set for this output port.
java.util.concurrent.Callable<java.lang.Boolean>	deferredSubmit(T tuple) Return a Callable object that may be used to submit a tuple in the future, typically using the ScheduledExecutorService from OperatorContext.
StreamingOutput.ExportType	getExportType() Return how this port is exported.
java.util.Map<java.lang.String,java.lang.Object>	getStreamProperties() Get the collection of stream properties currently set for this output port.
Tuple	getStreamPropertiesAsTuple() Get the collection of stream properties currently set for this output port.
boolean	isExported() Does this port produce an exported (dynamic) stream.
T	newTuple() Return a new tuple that can be sent using this port.
boolean	punctuate(StreamingData.Punctuation mark) Submit a punctuation mark to this output port.
void	removeStreamProperties(java.lang.String... name) Remove the named stream properties from this output port.
void	setStreamProperties(java.util.Map<java.lang.String,?> properties) Set the value of existing stream properties for this port.
boolean	submit(T tuple) Submit a tuple to this output port.
boolean	submit(Tuple tuple) Submit an immutable tuple to this output port.
boolean	submitAsTuple(java.lang.Object... attributeValues) Submit a tuple using variable list of values for the attributes.
boolean	submitListAsTuple(java.util.List<?> list) Submit a tuple setting attribute values from the supplied list by position The submitted tuple is identical to a tuple obtained from getStreamSchema().getTuple(List<?>).
boolean	submitMapAsTuple(java.util.Map<java.lang.String,?> map) Submit a tuple using Map containing attribute values with the attribute names as keys.

Methods inherited from interface com.ibm.streams.operator.StreamingData

getName, getPEPortNumber, getPortNumber, getStreamSchema, isConnectedToPEPort

Method Detail

getExportType

StreamingOutput.ExportType getExportType()

Return how this port is exported.

isExported

boolean isExported()

Does this port produce an exported (dynamic) stream.

Returns:

True if the port is exported, false otherwise.

newTuple

T newTuple()

Return a new tuple that can be sent using this port. All attributes are are to default values, zero for numeric values, empty strings, etc.

Returns:

A tuple.

submit

boolean submit(T tuple)
        throws java.lang.Exception

Submit a tuple to this output port.

If a FINAL_MARKER has been submitted to this port using punctuate(com.ibm.streams.operator.StreamingData.Punctuation), then the tuple will be discarded.

Parameters:

tuple - Tuple to be sent.

Returns:

false, future versions might indicate flow control with this return.

Throws:

java.lang.IllegalArgumentException - Tuple's schema does not match this port.

java.lang.IllegalStateException - Operator has not completed initialization or has been shutdown.

java.lang.Exception

submit

boolean submit(Tuple tuple)
        throws java.lang.Exception

Submit an immutable tuple to this output port.

If a StreamingData.Punctuation.FINAL_MARKER has been submitted to this port using punctuate(), then the tuple will be discarded.

Parameters:

tuple - Tuple to be sent.

Returns:

false, future versions might indicate flow control with this return.

Throws:

java.lang.IllegalArgumentException - Tuple's schema does not match this port.

java.lang.IllegalStateException - Operator has not completed initialization or has been shutdown.

java.lang.Exception

submitAsTuple

boolean submitAsTuple(java.lang.Object... attributeValues)
               throws java.lang.Exception

Submit a tuple using variable list of values for the attributes. Attributes are set by position, with the first value used for the attribute at index 0.
The submitted tuple is identical to a tuple obtained from
getStreamSchema().getTuple(attributeValues)
with the conversion of attributeValues to an array.

Parameters:

attributeValues - Values to populate submitted tuple.

Returns:

false, future versions might indicate flow control with this return.

Throws:

java.lang.IllegalStateException - Operator has not completed initialization or has been shutdown.

java.lang.Exception

Since:

InfoSphere® Streams Version 3.1

See Also:

StreamSchema.getTuple(Object[]), submit(Tuple)

submitMapAsTuple

boolean submitMapAsTuple(java.util.Map<java.lang.String,?> map)
                  throws java.lang.Exception

Submit a tuple using Map containing attribute values with the attribute names as keys.
The submitted tuple is identical to a tuple obtained from
getStreamSchema().getTuple(Map<String, ?>).

Parameters:

map - Map to set attribute values from.

Returns:

false, future versions might indicate flow control with this return.

Throws:

java.lang.IllegalStateException - Operator has not completed initialization or has been shutdown.

java.lang.Exception

Since:

InfoSphere® Streams Version 3.1

See Also:

StreamSchema.getTuple(Map), submit(Tuple)

submitListAsTuple

boolean submitListAsTuple(java.util.List<?> list)
                   throws java.lang.Exception

Submit a tuple setting attribute values from the supplied list by position
The submitted tuple is identical to a tuple obtained from
getStreamSchema().getTuple(List<?>).

Parameters:

list - List to set attribute values from.

Returns:

false, future versions might indicate flow control with this return.

Throws:

java.lang.IllegalStateException - Operator has not completed initialization or has been shutdown.

java.lang.Exception

Since:

InfoSphere® Streams Version 3.1

See Also:

StreamSchema.getTuple(List), submit(Tuple)

deferredSubmit

java.util.concurrent.Callable<java.lang.Boolean> deferredSubmit(T tuple)

Return a Callable object that may be used to submit a tuple in the future, typically using the ScheduledExecutorService from OperatorContext. The tuple will be submitted to this port when the call() method of the returned object is invoked.

Parameters:

tuple - Tuple to be sent. Caller must not modify the tuple once this call is made, discarding the reference after the call is recommended.

See Also:

OperatorContext.getScheduledExecutorService()

punctuate

boolean punctuate(StreamingData.Punctuation mark)
           throws java.lang.Exception

Submit a punctuation mark to this output port.

If a StreamingData.Punctuation.FINAL_MARKER has previously been submitted, then the punctuation mark will be discarded.

Parameters:

mark - Type of punctuation mark to submit, if the mark is NON_EXISTENT then no punctuation will be submitted to the port.

Returns:

false, future versions might indicate flow control with this return.

Throws:

java.lang.IllegalStateException - Operator has not completed initialization or has been shutdown.

java.lang.Exception

See Also:

StreamingData.Punctuation.NON_EXISTENT

getStreamProperties

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

Get the collection of stream properties currently set for this output port. The returned Map contains simple objects for a property's value. An exported port supports a limited number of SPL types for stream properties, the mapping between SPL types for the properties and Java types is described in the following table.

Stream Property Types

SPL Property Type	Java Property Type in Map
rstring	java.lang.String
int64	java.lang.Long
float64	java.lang.Double
list<rstring>	String[]
list<int64>	long[]
list<float64>	double[]

All rstring values use UTF-8 encoding.

Returns a snapshot of the properties, changes to the returned map are not reflected by the port. An exported stream's properties are explicitly updated using addStreamProperties(Map) and setStreamProperties(Map).

Returns:

A map of stream properties for this exported port.

Throws:

java.lang.IllegalStateException - if the port is not exported BY_PROPERTIES.

java.lang.IllegalStateException - Operator has been shutdown.

getStreamPropertiesAsTuple

Tuple getStreamPropertiesAsTuple()

Get the collection of stream properties currently set for this output port. Returns a snapshot of the properties as a tuple including full meta-data for each property as an Attribute of a Tuple.

Note that number and types of properties for an exported stream is not fixed, thus the schema for the returned tuple just represents the current state of the port. Stream properties only support a subset of SPL types, namely rstring, int64, float64, list<rstring>, list<int64> and list<float64>. All rstring values for stream property use UTF-8 encoding.

Returns:

A tuple of stream properties for this exported port.

Throws:

java.lang.IllegalStateException - if the port is not exported BY_PROPERTIES.

java.lang.IllegalStateException - Operator has been shutdown.

setStreamProperties

void setStreamProperties(java.util.Map<java.lang.String,?> properties)

Set the value of existing stream properties for this port. Updates existing stream properties to the values provided in the given properties object. The given map must only contain properties that are already exist for the port, though it may contain a subset of the properties. This call may be used to update the value and type of a property.

The values contained in the map define the type of a property, following the mapping shown in getStreamProperties().

Throws:

java.lang.IllegalStateException - if the port is not exported BY_PROPERTIES.

java.lang.IllegalStateException - if a property contained in the map does not currently exist on the port.

java.lang.UnsupportedOperationException - if a value in the map is not of a supported object type for a stream property.

java.lang.IllegalStateException - Operator has been shutdown.

addStreamProperties

void addStreamProperties(java.util.Map<java.lang.String,?> properties)

Add a collection of stream properties to the set for this output port. The passed in properties is added to the existing properties for this port. The given properties must only contain new properties, to update existing properties setStreamProperties(Map) is used.

The values contained in the map define the type of a property, following the mapping shown in getStreamProperties().

Throws:

java.lang.IllegalStateException - if this port is not exported BY_PROPERTIES.

java.lang.IllegalStateException - if a property already exists.

java.lang.UnsupportedOperationException - if a value in the map is not of a supported object type for a stream property.

java.lang.IllegalStateException - Operator has been shutdown.

removeStreamProperties

void removeStreamProperties(java.lang.String... name)

Remove the named stream properties from this output port.

Throws:

java.lang.IllegalStateException - if the port is not exported BY_PROPERTIES.

java.lang.IllegalStateException - Operator has been shutdown.