Using Error Ports and Error Streams

By default, an error encountered at runtime interrupts the processing of data for the current tuple that caused the error. StreamBase Server reacts to the error according to the type of problem encountered. Some errors are fatal and request the Server to shut down. Other errors are logged while processing continues. The table in Processing Error Tuple Data shows the default response for different types of error conditions.

Starting with StreamBase 5.1.1, you can add error handling to your EventFlow and StreamSQL applications with three features:

Errors are reported as a tuple in a standardized error tuple format, which can be manipulated as data. You can apply local logic to error processing just as when processing normal tuples.

Error tuples flow from an inner module to its containing module or application, and eventually to the StreamBase Server instance running the application.

Your StreamBase installation includes an Error Streams sample and an Eclipse Cheat Sheet that interactively walks you through several error handling scenarios. See Error Streams Sample for instructions on running this sample.

An Error Port is a special purpose output port that you can optionally enable for all operators, adapters, and module references. The Error Port emits an error tuple for every processing error that occurs inside this operator or adapter, including Java Exceptions that are thrown in custom operators or adapters.

In EventFlow applications, enable Error Ports on the General tab of the Properties view for operators, adapters, and module references. Mark the checkbox next to Enable Error Output Port. This places a red output port on the component's icon in the palette. The red port is a visual reminder that this port is a special case, and that the schema for this port is the standard StreamBase error tuple. The Error Port is always the last output port of each operator or adapter.

In StreamSQL applications, enable error handling with the ERROR INTO stream-identifier clause. You can place this clause just before the closing semicolon of any of the StreamSQL data manipulation statements, as listed on StreamSQL DML.

An Error Input Stream is a special purpose Input Stream that serves as the error catch mechanism for all otherwise unhandled errors in the containing module or application. There can be only one Error Input Stream in each module or application. Error Input Streams have a predefined schema, which is the schema of the StreamBase error tuple described below.

In EventFlow applications, add an Error Input Stream to a module by dragging the Error Input Stream icon from the Streams drawer of the Palette view to the canvas. The Error Input Stream icon has a single red output port, which is a reminder that the schema for this port is the standard StreamBase error tuple. In StreamSQL applications, add an Error Input Stream with the CREATE ERROR INPUT STREAM statement.

The output port of an Error Input Stream must be connected to another component. The simplest use of an Error Input Stream is to connect its output to a Map or Filter operator, whose output is then connected to an Error Output Stream. This configuration of three components can remain in the canvas alongside the other operators of your application or module. This configuration, illustrated in the following figure, means: enqueue all otherwise unhandled errors in this module at ErrorInput_A, and map its output unchanged to the input of ErrorOutput_B. Error tuples received at ErrorOutput_B are sent to the containing module or application's Error Input Stream.

An Error Output Stream is a special purpose Output Stream that serves as an error throw mechanism for the containing module or application. There can be more than one Error Output Stream per application or module, but the streams of all Error Output Streams in the application or module are sent to the same error output of the module.

In EventFlow applications, add an Error Output Stream to a module by dragging the Error Output Stream icon from the Streams drawer of the Palette view to the canvas. In StreamSQL applications, add an Error Output Stream with the CREATE ERROR OUTPUT STREAM statement.

It is important to distinguish between:

These cases are illustrated in the following figures. In Case 1, the Output Stream named LoggingOutputStream is not an Error Output Stream. It does have the standard StreamBase error tuple schema as its schema, but that is because it is connected to an Error Port. Connecting a stream to an operator's Error Port does not create an Error Output Stream. That is, such a port does not participate in the throw mechanism for the containing module or application. It is only a standard stream to which you are directing error tuples from the operator or adapter with the Error Port, perhaps for processing farther downstream.

By contrast, the stream named ErrorOutputThrow in Case 2 is a true Error Output Stream. Error tuples from the Astonisher operator are passed on to the next error handler.

A module's Error Output Stream, if any, flows to the containing module or application. This process continues up the chain of modules to the top-level StreamBase application, and then to the StreamBase Server instance running the application. It is the Server that performs the action designated in the action field of each error tuple.

All unhandled errors in a Module Reference go to the same place, regardless of whether they come from an Error Output Stream or are simply unhandled errors. Errors from a Module Reference appear in the same manner as errors from an operator:

The standard StreamBase error tuple has the schema shown in the following table.

The following is an example of an error tuple generated when running the dividemodule.sbapp application from the Error Streams sample delivered with your StreamBase installation. The error tuple is shown for clarity with its fields on separate lines, but the error tuple itself is normally one long comma-separated string.

description=Evaluation exception: Division by zero, 
originalTuple=(dividend=7568, divisor=0), 
operatorName=default.DoDivision, 
inputPort=0, 
nodeName=cerberus, 
type=eval-error, 
action=shutdown, 
time=2008-01-18 00:24:20.225-0500

Your error handling code can read the fields in each error tuple, extracting certain fields for logging purposes. But your code can also manipulate the error tuple data, which can dramatically change how your application operates. The following sections contain a starting point collection of ideas for managing error tuple data. You are by no means restricted to the ideas presented here.