com.ibm.streamsx.topology.context

Interface Placeable<T extends Placeable<T>>

All Superinterfaces:

TopologyElement

All Known Subinterfaces:

SPLStream, TSink, TStream<T>

public interface Placeable<T extends Placeable<T>>
extends TopologyElement

Placement directives for a topology element when executing in a distributed runtime.
Placement directives only apply when the topology is submitted to a DISTRIBUTED, STREAMING_ANALYTICS_SERVICE or DISTRIBUTED_TESTER context.
For all other context types directives are ignored.

Method Summary

Modifier and Type	Method and Description
T	addResourceTags(java.lang.String... tags) Add required resource tags for this topology element for distributed submission.
T	colocate(Placeable<?>... elements) Colocate this element with other topology elements so that at runtime they all execute within the same processing element (PE or operating system process).
default java.lang.String	getInvocationName() Return the invocation name of this element.
java.util.Set<java.lang.String>	getResourceTags() Get the set of resource tags this element requires.
T	invocationName(java.lang.String name) Set the invocation name of this placeable.
boolean	isPlaceable() Can this element have placement directives applied to it.
com.ibm.streamsx.topology.builder.BOperatorInvocation	operator()

Methods inherited from interface com.ibm.streamsx.topology.TopologyElement

builder, topology

Method Detail

isPlaceable

boolean isPlaceable()

Can this element have placement directives applied to it.

Returns:

true if placement directives can be assigned, false if it can not.

colocate

T colocate(Placeable<?>... elements)

Colocate this element with other topology elements so that at runtime they all execute within the same processing element (PE or operating system process). elements may contain any Placeable within the same topology, there is no requirement that the element is connected (by a stream) directly or indirectly to this element.

When a set of colocated elements are completely within a single parallel region then the colocation constraint is limited to that channel. So if elements A and B are colocated then it is guaranteed that A[0],B[0] from channel 0 are in a single PE and A[1],B[1]from channel 1 are in a single PE, but typically a different PE to A[0],B[0].
When a a set of colocated elements are not completely within a single parallel region then the colocation constraint applies to the whole topology. So if A,B are in a parallel region but C is outside then all the replicas of A,B are colocated with C and each other.

Colocation is also referred to as fusing, when topology elements are connected by streams then the communication between them is in-process using direct method calls (instead of a network transport such as TCP).

Parameters:

elements - Elements to colocate with this container.

Returns:

this

Throws:

IllegalStateExeception - Any element including this returns false for isPlaceable().

addResourceTags

T addResourceTags(java.lang.String... tags)

Add required resource tags for this topology element for distributed submission. This topology element and any it has been colocated with will execute on a resource (host) that has all the tags returned by getResourceTags().

Parameters:

tags - Tags to be required at runtime.

Returns:

this

getResourceTags

java.util.Set<java.lang.String> getResourceTags()

Get the set of resource tags this element requires. If this topology element has been colocated with other topology elements then the returned set is the union of all resource tags added to each colocated element.

Returns:

Read-only set of host tags this element requires.

getInvocationName

default java.lang.String getInvocationName()

Return the invocation name of this element. This name is unique within the context of its topology. By default an element has a unique generated invocation name

Returns:

Current invocation name if isPlaceable() is true otherwise null.

Since:

1.7

See Also:

invocationName(String)

invocationName

T invocationName(java.lang.String name)

Set the invocation name of this placeable. Allows an invocation name to be assigned to this placeable. The name is visible in the Streams console for a running job and is associated with the logic for this placeable.

Names must be unique within a topology, if this name is already in use then the 'name_N' will be used where N is a number that makes the name unique within the topology.

For example the invocation for sending alerts as SMS (text) messages could be named as SMSAlerts:

 
 TStream<Alert> alerts = ...
 
 alerts.forEach(Alert::sendAsTextMsg).name("SMSAlerts"); 
 
 

Note that name will eventually resolve into an identifier for an operator name and/or a stream name. Identifiers are limited to ASCII characters, thus name will be modified at code generation time if it cannot be represented as an identifier.

Parameters:

name - Name to assigned.

Returns:

This.

Throws:

java.lang.IllegalStateException - isPlaceable() returns false.

Since:

1.7

See Also:

getInvocationName()

operator

com.ibm.streamsx.topology.builder.BOperatorInvocation operator()