Multiple version toolkit support with Java™ operators

Java™ primitive operators can be developed to work on multiple versions of Teracloud® Streams. A lowest common denominator approach is currently recommended for supporting multiple Teracloud® Streams versions. It is further recommended that the lowest supported version is Teracloud® 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 Teracloud® 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 Teracloud® Streams 2.0 for the Java™ Operator API in the com.ibm.streams.operator packages). For example, the @SharedLoader annotation was added in Teracloud® 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 Teracloud® Streams release. Assuming you package the resultant classes into a jar file, then that jar file will work with that Teracloud® Streams release or any later release. You can also compile against a later version of Teracloud® Streams, as long as you manually ensure that your code does not use any feature not in the lowest release you want to support.

Teracloud® 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 Teracloud® 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: