IBM Streams 4.3.0

Catch annotation

The SPL annotation @catch indicates that exceptions of a specified type that are thrown by an operator while processing tuples are caught.


>>-@catch--(--exception--=--+-none----+------------------------->
                            +-streams-+   
                            +-std-----+   
                            '-all-----'   

>--+--------------------------------+--------------------------->
   '-,--tupleTrace -=--+-false-+--]-'   
                       '-true--'        

>--+-----------------------------+--)--------------------------><
   '-,--stackTrace -=--+-true--+-'      
                       '-false-'

When applied to a primitive operator, the @catch annotation indicates that exceptions of the specified type that are thrown by the operator while processing a tuple are caught. Exceptions that are thrown as a result of a tuple submission for downstream processing still cause processing elements (PEs) to fail. Causes for exceptions during a submit operation can include a tuple submission to an invalid output port and exceptions that are thrown by downstream operators. If the PE must not fail as a result of a downstream operator exception, you must also place an @catch annotation on the downstream operator. The @catch annotation is valid only for the annotated operator and is independent of the PE threading model, such as threaded ports.

When applied to a composite operator, the annotation applies to every operator in the composite. If an inner operator already has an annotation applied to it, the configuration of the operator instance overrides the configuration of the composite instance. To disable the @catch annotation on a specific operator instance, apply the annotation with the exception element set to none.

You cannot use the @catch annotation on an operator without input ports. When using the @catch annotation, operator instances maintain an additional metric per input port. The metric is named nExceptionsCaughtPortZ, where Z is the index of the input port. The metric value increments every time that an exception is caught by the run time environment.

Required elements

exception

Indicates the type of exceptions to be caught by the run time environment. Supported options include:

none: No exceptions of any type are caught.
streams: Only IBM® Streams exceptions are caught. This includes exceptions that are thrown by SPL native functions from the standard toolkit, other exceptions that extend from the C++ SPL::SPLRuntimeException, and exceptions that extend from the Java™ com.ibm.streams.operator.DataException (extending from java.lang.RuntimeException).
std: Both IBM Streams and standard exceptions are caught. For C++, standard exception means std::exception. For Java, standard exception means all checked exceptions that inherit from java.lang.Exception.
all: In C++, any thrown exception is caught. For Java, any checked and unchecked exception that inherits from java.lang.Exception is caught.

Optional elements

tupleTrace

Enables or disables the tracing of tuple data. Tracing of data can be enabled when tuples do not contain sensitive data and the data can show up into PE logs. Tuples are logged to the trace facility with the ERROR trace level. Tracing of tuple data is disabled by default. Supported values:

false: Disables tracing (default)
true: Enables tracing

stackTrace

Enables or disables the printout of the stack trace to the Streams trace facility. Stack traces are printed to the Streams trace facility with the trace level ERROR. Stack traces are enabled by default. Supported values:

true: Enables tracing (default)
false: Disables tracing

Examples

Example 1: Using the @catch annotation with a custom operator

A custom operator uses the @catch annotation to catch failures during fast type conversions to cast a string to an int32 type. If a failure does occur, because the value of attribute b is an invalid integer, for example, an exception stack trace is logged to the trace facility by default. The affected tuple is not logged.

stream<int32 a, rstring b> Beat = Beacon() {
  output Beat: a = (int32) IterationCount(), b = “100”;
}
@catch(exception=streams)
stream<int32 a, int32 b> Casted = Custom(Beat) {
  logic
    onTuple Beat: {
      submit({a = a, b = (int32) b}, Casted);
    }
}

Example 2: Using the @catch annotation on a custom operator to log exceptions

Tuples that fail to process are logged in the PE logs but the exception stack trace is not logged.

@catch(exception=streams, tupleTrace=true, stackTrace=false)
(stream<int32 a, int32 b> Casted) = Custom(Beat) {
  logic
    onTuple Beat: {
      submit({a = a, b = (int32) b}, Casted);
    }
}