Multiple version toolkit support with Java operators

Java™ primitive operators can be developed to work on multiple versions of IBM® Streams. A lowest common denominator approach is currently recommended for supporting multiple IBM Streams versions. It is further recommended that the lowest supported version is IBM Streams 3.2, which is where annotations were introduced to define a Java class implementing Operator as a Java primitive operator, visible to SPL.

The lowest common denominator approach means that the operator only utilizes functionality available at the lowest level the operator must support, for example if the operator must support 3.2 and 4.0 then this approach means the operator does not use any 4.0 feature. Specifically this means the operator must not use any class, interface, method or field that does not exist in IBM Streams 3.2. The Javadoc for the Java Operator API has @since tags that document when the class, interface, method or field was introduced. Any item without an @since tag has been present in the API since the beginning (in this case IBM Streams 2.0 for the Java Operator API in the com.ibm.streams.operator packages). For example, the @SharedLoader annotation was added in IBM Streams 3.2.1, the Javadoc has this:

  Since:
    InfoSphere Streams Version 3.2.1

The Java operator API overview also has a 'What's New' sections, so you can use that to determine what is the lowest level you want your operator to support.

The easiest way to enforce that an operator only uses features from a specific level is to compile the Java source against the Java Operator API jar files from that IBM Streams release. Assuming you package the resultant classes into a jar file, then that jar file will work with that IBM Streams release or any later release. You can also compile against a later version of IBM Streams, as long as you manually ensure that your code does not use any feature not in the lowest release you want to support.

IBM Streams Version 4.0 and later provide a product version API that can query the product version at runtime from Java primitive operators. Use this API to check the product version before making API calls that are not available in a version of IBM Streams. By using the guidelines for multiple version toolkit support and the product version API, you can write operators that support different versions of Streams.

In addition the operator must not use any deprecated class, interface, method or field. Deprecated items are marked as deprecated and will cause compile warnings if they are used; they are also tagged as deprecated in the Javadoc.

There are however a number of situations to handle: