Package com.ibm.streams.operator.model

Annotations to define an SPL Java primitive operator.

See: Description

  • Enum Summary 
    Enum Description
    InputPortSet.WindowMode
    Enumeration containing the types of windowing semantics supported by an operator.
    InputPortSet.WindowPunctuationInputMode
    Enumeration listing the types of punctuation semantics that can be supported by a port.
    OutputPortSet.WindowPunctuationOutputMode
    Enumeration that lists the types of window punctuation semantics supported by an operator.
  • Annotation Types Summary 
    Annotation Type Description
    CustomMetric
    Declare a relationship between an Operator's Java bean property and custom metric.
    DefaultAttribute
    Declare a default attribute to be used as the value for an optional 'Attribute' parameter.
    Icons
    Declare a set of icon files for the operator.
    InputPorts
    Declare a set of input port sets for an operator.
    InputPortSet
    Declare a single input port set.
    Libraries
    Declare a set of Java class libraries to be added to the operator's class loader at execution time.
    Namespace
    Declares a default SPL namespace for SPL artifacts in the annotated package.
    OutputPorts
    Declare a set of output port sets for an operator.
    OutputPortSet
    Declare a single output port set.
    Parameter
    Declare a relationship between an Operator's Java bean property and an SPL operator invocation parameter.
    PrimitiveOperator
    Declares a Java primitive operator.
    SharedLoader
    Declare if the class loader for a Java primitive operator is shared within an processing element.

Package com.ibm.streams.operator.model Description

Annotations to define an SPL Java primitive operator.

The typical steps to create a Java primitive operator model are:

  1. Annotate an operator class (i.e. a class implementing the Operator interface) with the annotations in this package. Each annotation's javadoc describes the usage in detail.
  2. Compile the Java operator class.
  3. Package the class and its nested classes in a jar file in lib or impl/lib within the toolkit.
  4. Index the toolkit.
Details of these steps are covered in the following paragraphs.

Annotations on or within the operator class define the model for the operator in an SPL toolkit. The operator model XML file is created when the toolkit is indexed, which occurs by running spl-make-toolkit. Toolkit indexing may be explicit, by executing spl-make-toolkit, or implicit through the SPL compiler sc or Streams Studio.

Instead of being specified on the operator class itself, it is possible for some annotations to be specified on a super class of the operator class. Such annotations are marked with the Inherited meta-annotation. These annotations will be inherited by the operator class as if they were present on the operator class itself. If the same annotation is specified on the operator class as well, the operator class annotation will take effect and the super class version will be hidden.

For example, the Libraries annotation can be inherited. In the code snippet below, the annotation on the super class will be inherited by the SampleOperator operator class: 

 
   @Libraries("opt/lib1.jar")
   public class BaseOperator extends AbstractOperator {
   ...
   }

   public class SampleOperator extends BaseOperator {
   ...
   }

However, in the code snippet below, the super class annotation will be hidden and the operator class annotation will take effect leading to only the opt/lib2.jar library to be added to the operator model XML file: 

   @Libraries("opt/lib1.jar")
   public class BaseOperator extends AbstractOperator {
   ...
   }

   @Libraries("opt/lib2.jar")
   public class SampleOperator extends BaseOperator {
   ...
   }

A Java operator class (i.e. a class that implements the Operator interface) annotated with at least @PrimitiveOperator will lead to the operator XML file to be generated during toolkit indexing if its class file is in one of these locations relative to the root directory of the toolkit (the value passed as the -i argument to spl-make-toolkit):

  • The class directory impl/java/bin (in its correct package based sub-directory).
  • Contained in a jar file within impl/lib. The jar file must have the suffix .jar or .JAR.
  • Contained in a jar file within lib. The jar file must have the suffix .jar or .JAR.

If the operator class file is present in more than one location listed above then the first instance of the class will be used for the generation of the operator XML file and subsequent instances will be ignored.

The class must have been compiled with annotation processing enabled using the annotation processors defined by the jar file com.ibm.streams.operator.jar. This annotation processing occurs automatically when using a Java compiler or Streams Studio.
The annotation processing creates a nested class for the operator class, with the class name and suffix $StreamsModel. When creating a jar file containing operator classes, these nested classes must be included. Toolkit indexing creates the operator model XML file from these nested classes. This is similar to including nested classes created by anonymous inner classes. Typically creating a jar file includes all classes within a package and thus no special action is required.

Toolkit indexing creates the operator model XML file under the the directory for the SPL namespace of the operator. The namespace for an operator is defined according to PrimitiveOperator.namespace() element or the package annotation Namespace. The generated operator model XML file is read-only and must not be modified.

A single ClassLoader is created for each operator, it contains:

  • Jar files in lib and impl/lib that contain the operator class annotated with @PrimitiveOperator.
  • The class directory impl/java/bin if it contains the operator class annotated with @PrimitiveOperator.
  • The jars or locations specified using the @Libraries annotation.

Operator classes are loaded using this class loader. If additional jars are required in the class path then it is recommended that the class is packaged in a jar file and the jar file has a Class-Path manifest entry that references required jars. These required jars would typically be contained within the toolkit. For example third-party jars may be under opt and a jar file in lib would reference them using a relative path starting with ../opt/.
For any reason, if required jars cannot be specified using the Class-Path mechanism mentioned above, the Libraries annotation on the operator class can be used to specify libraries that are required.

As the example, to define a model using annotations to describe a sample operator with the following properties:

  • A parent SPL namespace - "com.ent.test"
  • An operator specific VM argument that should be passed to the JVM at startup - "-Xmx128m"
  • An input port and one output port. We will assume default values for the attributes of the ports for this example
  • An SPL parameter - "interval" that takes an SPL int32 value
  • A required 3rd party dependency - opt/dep.jar
The following code snippet describes this operator: 

   @PrimitiveOperator(namespace="com.ent.test", vmArgs="-Xmx128m")
   @InputPorts(@InputPortSet)
   @OutputPorts(@OutputPortSet)
   @Libraries("opt/dep.jar")
   public class SampleOperator extends AbstractOperator{
                private int interval;

                @Parameter
                public void setInterval(int intVal) {
                        this.interval = intVal;
                }
   }