com.ibm.streamsx.topology.spl

Class SPL

java.lang.Object

com.ibm.streamsx.topology.spl.SPL

public class SPL
extends java.lang.Object

Integration between Java topologies and SPL operator invocations. If the SPL operator to be invoked is an SPL Java primitive operator then the methods of JavaPrimitive must be used.
An operator's kind is its namespace followed by the operator name separated with '::'. For example the FileSource operator from the SPL Standard toolkit must be specified as spl.adapter::FileSource.

When necessary use createValue(T, MetaType), or createNullValue(), to create parameter values for SPL types. For example:

 Map<String,Object> params = ...
 params.put("aInt32", 13);
 params.put("aUInt32", SPL.createValue(13, MetaType.UINT32));
 params.put("aRString", "some string value");
 params.put("aUString", SPL.createValue("some ustring value", MetaType.USTRING));
 ... = SPLPrimitive.invokeOperator(..., params);
 

In addition to the usual Java types used for operator parameter values, a Supplier<T> parameter value may be specified. Submission time parameters are passed in this manner. See createSubmissionParameter(Topology, String, Object, boolean). For example:

 Map<String,Object> params = ...
 params.put("aInt32", topology.createSubmissionParameter("int32Param", 13);
 params.put("aUInt32", SPL.createSubmissionParameter(topology, "uint32Param", SPL.createValue(13, MetaType.UINT32), true);
 params.put("aRString", topology.createSubmissionParameter("rstrParam", "some string value");
 params.put("aUString", SPL.createSubmissionParameter(topology, "ustrParam", SPL.createValue("some ustring value", MetaType.USTRING), true);
 params.put("aUInt8", SPL.createSubmissionParameter(topology, "uint8Param", SPL.createValue((byte)13, MetaType.UINT8), true);
 ... = SPLPrimitive.invokeOperator(..., params);
 

Note: Invoking an SPL composite operator with internal config placement clauses can cause logical topology constraints declared by isolate, lowLatency or colocate to be violated. This is due to the config placement clause within the composite definition overriding the invocation clauses generated for the logical constraints.

Constructor Summary

Constructors

Constructor and Description
SPL()

Method Summary

Modifier and Type	Method and Description
static void	addToolkit(TopologyElement te, java.io.File toolkitRoot) Add a dependency on an SPL toolkit.
static void	addToolkitDependency(TopologyElement te, java.lang.String name, java.lang.String version) Add a logical dependency on an SPL toolkit.
static java.lang.Object	createNullValue() Create an SPL value wrapper object for an SPL null value.
static <T> Supplier<T>	createSubmissionParameter(Topology top, java.lang.String name, java.lang.Object paramValue, boolean withDefault) Create a submission parameter with or without a default value.
static <T> java.lang.Object	createValue(T value, com.ibm.streams.operator.Type.MetaType metaType) Create an SPL value wrapper object for the specified SPL MetaType.
static SPLStream	invokeOperator(java.lang.String kind, SPLInput input, com.ibm.streams.operator.StreamSchema outputSchema, java.util.Map<java.lang.String,? extends java.lang.Object> params) Create an SPLStream from the invocation of an SPL operator that consumes a stream.
static SPLStream	invokeOperator(java.lang.String name, java.lang.String kind, SPLInput input, com.ibm.streams.operator.StreamSchema outputSchema, java.util.Map<java.lang.String,? extends java.lang.Object> params) Create an SPLStream from the invocation of an SPL operator that consumes a stream and produces a stream.
static java.util.List<SPLStream>	invokeOperator(TopologyElement te, java.lang.String name, java.lang.String kind, java.util.List<? extends SPLInput> inputs, java.util.List<com.ibm.streams.operator.StreamSchema> outputSchemas, java.util.Map<java.lang.String,? extends java.lang.Object> params) Invoke an SPL operator with an arbitrary number of input and output ports.
static TSink	invokeSink(java.lang.String kind, SPLInput input, java.util.Map<java.lang.String,? extends java.lang.Object> params) Invocation an SPL operator that consumes a Stream.
static TSink	invokeSink(java.lang.String name, java.lang.String kind, SPLInput input, java.util.Map<java.lang.String,? extends java.lang.Object> params) Invocation an SPL operator that consumes a Stream.
static SPLStream	invokeSource(TopologyElement te, java.lang.String kind, java.util.Map<java.lang.String,java.lang.Object> params, com.ibm.streams.operator.StreamSchema schema) Invocation an SPL source operator to produce a Stream.
static void	tagOpAsJavaPrimitive(com.ibm.streamsx.topology.builder.BOperatorInvocation op, java.lang.String kind, java.lang.String className) Internal method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SPL

public SPL()

Method Detail

createValue

public static <T> java.lang.Object createValue(T value,
                                               com.ibm.streams.operator.Type.MetaType metaType)

Create an SPL value wrapper object for the specified SPL MetaType.

Use of this is required to construct an SPL operator parameter value whose SPL type is not implied from simple Java type. e.g., a String value is interpreted as an SPL rstring, and Byte,Short,Integer,Long are interpreted as SPL signed integers.

Parameters:

value - the value to wrap

metaType - the SPL meta type

Returns:

the wrapper object

Throws:

java.lang.IllegalArgumentException - if value is null or its class is not appropriate for metaType

createNullValue

public static java.lang.Object createNullValue()

Create an SPL value wrapper object for an SPL null value.

Use of this is required to construct an SPL operator parameter null value for an optional type.

Returns:

the wrapper object

Since:

1.10

createSubmissionParameter

public static <T> Supplier<T> createSubmissionParameter(Topology top,
                                                        java.lang.String name,
                                                        java.lang.Object paramValue,
                                                        boolean withDefault)

Create a submission parameter with or without a default value.

Use of this is required to construct a submission parameter for an SPL operator parameter whose SPL type requires the use of createValue(Object, MetaType).

See Topology.createSubmissionParameter(String, Class) for general information about submission parameters.

Parameters:

top - the topology

name - the submission parameter name

paramValue - a value from createValue()

withDefault - true to create a submission parameter with a default value, false to create one without a default value When false, the paramValue's wrapped value's value in ignored.

Returns:

the Supplier<T> for the submission parameter

Throws:

java.lang.IllegalArgumentException - if paramValue is not a value from createValue().

invokeOperator

public static SPLStream invokeOperator(java.lang.String kind,
                                       SPLInput input,
                                       com.ibm.streams.operator.StreamSchema outputSchema,
                                       java.util.Map<java.lang.String,? extends java.lang.Object> params)

Create an SPLStream from the invocation of an SPL operator that consumes a stream.

Parameters:

kind - SPL kind of the operator to be invoked.

input - Stream that will be connected to the only input port of the operator

outputSchema - SPL schema of the operator's only output port.

params - Parameters for the SPL operator, ignored if it is null.

Returns:

SPLStream the represents the output of the operator.

invokeOperator

public static SPLStream invokeOperator(java.lang.String name,
                                       java.lang.String kind,
                                       SPLInput input,
                                       com.ibm.streams.operator.StreamSchema outputSchema,
                                       java.util.Map<java.lang.String,? extends java.lang.Object> params)

Create an SPLStream from the invocation of an SPL operator that consumes a stream and produces a stream.

Parameters:

name - Name for the operator invocation.

kind - SPL kind of the operator to be invoked.

input - Stream that will be connected to the only input port of the operator

outputSchema - SPL schema of the operator's only output port.

params - Parameters for the SPL operator, ignored if it is null.

Returns:

SPLStream the represents the output of the operator.

invokeOperator

public static java.util.List<SPLStream> invokeOperator(TopologyElement te,
                                                       java.lang.String name,
                                                       java.lang.String kind,
                                                       java.util.List<? extends SPLInput> inputs,
                                                       java.util.List<com.ibm.streams.operator.StreamSchema> outputSchemas,
                                                       java.util.Map<java.lang.String,? extends java.lang.Object> params)

Invoke an SPL operator with an arbitrary number of input and output ports.
Each input stream or window in inputs results in a input port for the operator with the input port index matching the position of the input in inputs. If inputs is null or empty then the operator will not have any input ports.
Each SPL schema in outputSchemas an output port for the operator with the output port index matching the position of the schema in outputSchemas. If outputSchemas is null or empty then the operator will not have any output ports.

Parameters:

te - Reference to Topology the operator will be in.

name - Name for the operator invocation.

kind - SPL kind of the operator to be invoked.

inputs - Input streams to be connected to the operator. May be null if no input streams are required.

outputSchemas - Schemas of the output streams. May be null if no output streams are required.

params - Parameters for the SPL Java Primitive operator, ignored if null.

Returns:

List of SPLStream instances that represent the outputs of the operator.

invokeSink

public static TSink invokeSink(java.lang.String kind,
                               SPLInput input,
                               java.util.Map<java.lang.String,? extends java.lang.Object> params)

Invocation an SPL operator that consumes a Stream.

Parameters:

kind - SPL kind of the operator to be invoked.

input - Stream that will be connected to the only input port of the operator

params - Parameters for the SPL operator, ignored if it is null.

Returns:

the sink element

invokeSink

public static TSink invokeSink(java.lang.String name,
                               java.lang.String kind,
                               SPLInput input,
                               java.util.Map<java.lang.String,? extends java.lang.Object> params)

Invocation an SPL operator that consumes a Stream.

Parameters:

name - Name of the operator

kind - SPL kind of the operator to be invoked.

input - Stream that will be connected to the only input port of the operator

params - Parameters for the SPL operator, ignored if it is null.

Returns:

the sink element

invokeSource

public static SPLStream invokeSource(TopologyElement te,
                                     java.lang.String kind,
                                     java.util.Map<java.lang.String,java.lang.Object> params,
                                     com.ibm.streams.operator.StreamSchema schema)

Invocation an SPL source operator to produce a Stream.

Parameters:

te - Reference to Topology the operator will be in.

kind - SPL kind of the operator to be invoked.

params - Parameters for the SPL operator.

schema - Schema of the output port.

Returns:

SPLStream the represents the output of the operator.

addToolkit

public static void addToolkit(TopologyElement te,
                              java.io.File toolkitRoot)
                       throws java.io.IOException

Add a dependency on an SPL toolkit.

Parameters:

te - Element within the topology.

toolkitRoot - Root directory of the toolkit.

Throws:

java.io.IOException - toolkitRoot is not a valid path.

addToolkitDependency

public static void addToolkitDependency(TopologyElement te,
                                        java.lang.String name,
                                        java.lang.String version)

Add a logical dependency on an SPL toolkit.

Parameters:

te - Element within the topology.

name - Name of the toolkit.

version - Version dependency string.

tagOpAsJavaPrimitive

public static void tagOpAsJavaPrimitive(com.ibm.streamsx.topology.builder.BOperatorInvocation op,
                                        java.lang.String kind,
                                        java.lang.String className)

Internal method.
Not intended to be called by applications, may be removed at any time.
This is in lieu of a "kind" based JavaPrimitive.invoke*() methods.

Parameters:

op - the operator invocation

kind - SPL kind of the operator to be invoked.

className - the Java primitive operator's class name.