com.ibm.streams.operator.model

Annotation Type Parameter

@Target(value=METHOD)
@Retention(value=RUNTIME)
@Documented
public @interface Parameter

Declare a relationship between an Operator's Java bean property and an SPL operator invocation parameter. This allows Operator implementations to simplify their initialize method by having the SPL runtime automatically set field values using setter methods.

Any Java bean setter methods of an Operator implementation class or its super classes annotated @Parameter are invoked by the SPL runtime when a matching SPL operator invocation parameter is set. The operator invocation parameter name defaults to the Java bean property's name, but may be set explicitly using name().

Setter methods are invoked before Operator.initialize is invoked. Setter methods of the super-class are invoked first starting at the root of the hierarchy. Invocation ordering of setter methods within a class definition is not defined.

Supported mapping of SPL parameter types to Java bean property types are:

SPL parameter type mapping

SPL Parameter Type	Parameter Cardinality	Java Property Types
boolean	1	boolean, Boolean
	> 1	boolean[]
int8	1	byte, Byte
	> 1	byte[]
int16	1	short, Short
	> 1	short[]
int32	1	int, Integer
	> 1	int[]
int64	1	long, Long
	> 1	long[]
float32	1	float, Float
	> 1	float[]
float64	1	double, Double
	> 1	double[]
decimal32,decimal64,decimal128	1	java.math.BigDecimal
	> 1	BigDecimal[], List<BigDecimal>
rstring,ustring	1	String
	> 1	String[], List<String>
CustomLiteral	1	Enum
Attribute	1	TupleAttribute
	> 1	TupleAttribute[], List<TupleAttribute>

Varargs methods are treated as if the method parameter was declared using the underlying array type.

If the SPL parameter is not the expected type then the value will be converted from its character representation into the Java bean property's type. If this conversion fails, an exception will be thrown, causing the operator and its processing element to terminate.
Any instance of List passed to a setter method is read-only.
All rstring parameters assume UTF-8 encoding.

For example, with these annotated Java setter methods

private String id;
private float threshold = 25.0;

// Optional parameter threshold 
@Parameter
public void setThreshold(float threshold) {
    this.threshold = threshold;
}
public float getThreshold() {
    return threshold;
}

// Mandatory parameter sensorTag mapping to the Java bean property id
@Parameter(name="sensorTag", optional=false)
public void setId(String id) {
    this.id = id;
}
public String getId() {
    return id;
}

 

this SPL operator invocation param section:

 
   param
       sensorTag: "295ul67";
       threshold: 55.0;
 
 

would result in setId("295ul67") and setThreshold(55.0) being invoked before Operator.initialize.

Java bean properties of the operator's class and its super-classes are identified using java.beans.BeanInfo.getPropertyDescriptors() with the BeanInfo instance obtained using java.beans.Inspector. The setter method is identified by the getWriteMethod of a class's BeanInfo.

In InfoSphere Streams 4.0, parameters of type CustomLiteral and Attribute are now supported. For example, the code snippet below shows a CustomLiteral parameter output with values {text, binary}:

 
        //enumeration type
        public enum OutputType {
            text,
                binary
        }
        ...
        private OutputType output;
        ...
        @Parameter
        public void setOutput(OutputType o) {
            this.output = o;
        }       
 
 

Similarly, for passing an attribute as a parameter, the object bean property of TupleAttribute type must be used. See example below:

 

        private TupleAttribute<Tuple,Integer> sortBy;
        ...
        @Parameter
        public void setSortBy(TupleAttribute<Tuple,Integer> s) {
                this.sortBy = s;
        }       
 
 

To specify a default attribute to be used with an 'Attribute parameter, specify the attribute name using the com.ibm.streams.operator.model.DefaultAttribute annotation.

If the SPL runtime throws an exception during automatic setting of properties prior to initialization the processing element will terminate.
An IllegalArgumentException is thrown if an operator invocation contains multiple values for a parameter that maps to a single value Java bean property, e.g. a setter that takes an int argument.
An IllegalStateException is thrown if the Java Bean property's type is not supported.
IllegalStateException is thrown if the corresponding parameter definition in the Java primitive's operator model has a different type, cardinality or optional settings.
No action is taken for non-setter methods annotated @Parameter.

The method this annotation is applied to must be:

• public
• an instance method (not static)
• return type of void
• have a single parameter of a supported type.

These restrictions are enforced at Java compilation time using annotation processing from InfoSphere® Streams Version 3.2 onwards.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
int	cardinality The maximum number of values accepted by the operator parameter.
java.lang.String	description Description for the parameter.
java.lang.String	name Name of the operator invocation parameter.
boolean	optional Indicate the setting of the property via an operator invocation parameter is optional.

Element Detail

name

public abstract java.lang.String name

Name of the operator invocation parameter. This must be a valid SPL identifier.

Returns:

The name of the operator invocation parameter or the empty string to indicate the operator parameter name matches the Java bean property name.

Default:

""

description

public abstract java.lang.String description

Description for the parameter.

Returns:

Description for the parameter

Since:

InfoSphere® Streams Version 3.2

Default:

""

cardinality

public abstract int cardinality

The maximum number of values accepted by the operator parameter. If the setter method's parameter type is not an array or List then the cardinality cannot be specified, and the operator parameter can only accept a single value.
For array or List types the value supplied must be a value greater than one to limit the number of values that are accepted by the operator parameter, or -1 to represent unbounded. If not specified, the default is -1. Varargs methods are treated as if the method parameter was declared using the underlying array type.

Returns:

Maximum number of values accepted by the parameter

Since:

InfoSphere® Streams Version 3.2

Default:

-1

optional

public abstract boolean optional

Indicate the setting of the property via an operator invocation parameter is optional.

Returns:

False if operator invocation parameter is required, an IllegalStateException will be raised if the parameter is not present, true if the parameter is optional.

Default:

false