com.ibm.streams.function.model

Annotation Type Function

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

Declare an SPL Java native function. A method annotated with @Function allows the method to be called as a Java native function from SPL. The annotated method must be public and static. The method may use classes from other libraries specified with the ToolkitLibraries annotation.

A Java method annotated with @Function is automatically created as an SPL native function during toolkit indexing. The resulting function that can be called from SPL:

• Has an SPL namespace defined according to namespace().
• Is a public function.
• Has an SPL name defined according to name().
• Has SPL parameter and return types according to the supported mapping.
• Has immutable parameters.
• Is stateful if stateful() is true.

Supported mapping of Java types to SPL types for native functions is:

SPL Java native function type mapping

Java method parameter or return type	SPL Types	Notes
void	void	Return type only.
boolean	boolean
byte	int8, uint8	When the method has integral Java primitive parameter types or arrays of integral primitive parameter types, then multiple SPL functions are generated to support signed and unsigned integral SPL types. Each resulting function prototype defines that all integral Java primitive types are mapped to either all signed or all unsigned SPL types. For example all int and long parameters and return type must map to int32 and int64, respectively, or to uint32 and uint64, respectively, and similarly for the corresponding list types, and a mix of int32 and uint32 expressions is not allowed in a single SPL Java function invocation. When a Java integral primitive type is used only as the return type for the method, and there are no integral Java primitive parameter types, then the SPL function prototype supports returning only the signed SPL integral. For example a method that returns a short and takes no arguments has a single SPL function prototype returning an int16. When an unsigned integral SPL type is passed to, or returned from, an SPL Java native function, it is mapped to a signed Java type, and so the result might not be correct if a value exceeds the maximum positive value supported by the signed Java type.
short	int16, uint16
int	int32, uint32
long	int64, uint64
float	float32
double	float64
String	rstring, rstring[n], ustring	When the function has String or String[] parameters the prototype for the SPL function uses a single generic <string T> to represent all String and String[] parameters and the return type if it is of type String or String[]. If the method has a return type of String or String[] without any String or String[] parameters then the SPL function has a return type of rstring, or list<rstring> (and list<rstring>[m] if there are other array parameters), respectively.
boolean[]	list<boolean>, list<boolean>[m]
byte[]	list<int8>, list<int8>[m], list<uint8>, list<uint8>[m]	See above note for integral primitive types to see how signed and unsigned SPL types are supported.
short[]	list<int16>, list<int16>[m], list<uint16>, list<uint16>[m]
int[]	list<int32>, list<int32>[m], list<uint32>, list<uint32>[m]
long[]	list<int64>, list<int64>[m], list<uint64>, list<uint64>[m]
float[]	list<float32>, list<float32>[m]
double[]	list<float64>, list<float64>[m]
String[]	list<rstring>, list<rstring>[m], list<rstring[n]>, list<rstring[n]>[m], list<ustring>, list<ustring>[m]	See above note for string types.

When the Java method has String or array parameters, then the prototypes for the automatically generated SPL native functions define that all bounded-length strings have the same upper bound, and all bounded-length lists have the same upper bound. If the Java method returns an array and does not have any array parameters, then the SPL function has a return type of an unbounded array only.

Here's an example which allows the method to be called from SPL code as "res = sum(a, b)":

   @Function
   public static int sum(int a, int b) {
      return a + b;
   }
 

Since:

InfoSphere® Streams Version 3.2

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.String	description Description for the native function.
java.lang.String	name Name of the function.
java.lang.String	namespace SPL namespace of the Java native function.
boolean	stateful Declare the function as stateful or stateless.

Element Detail

namespace

public abstract java.lang.String namespace

SPL namespace of the Java native function. The SPL namespace of the function is:

• The value of this namespace element of the annotation if it is explicitly present.
• Otherwise, the value of the Namespace annotation for the package of the annotated method, if it exists.
• Otherwise, the package name of the annotated method.

Returns:

Namespace for the native function

See Also:

Namespace

Default:

""

name

public abstract java.lang.String name

Name of the function. If this name element is the default value (the empty string) then the name of the function is the name of the annotated method. The name of the function must be a valid SPL identifier.

Returns:

Name of the native function

Default:

""

stateful

public abstract boolean stateful

Declare the function as stateful or stateless. Functions are stateless by default. A stateful function is a function that is not referentially transparent or has side-effects. A function is not referentially transparent if it does not consistently yield the same result each time it is called with the same inputs. A function has side-effects if it modifies state observable outside the function.

Returns:

True if the function is stateful, false if it is stateless.

Default:

false

description

public abstract java.lang.String description

Description for the native function.

Returns:

Description for the native function.

Default:

""