SPL (Java Application API for IBM Streams)
Date: 2020-08-07

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

    All Methods Static Methods Concrete Methods
    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.