Developing StreamBase Embedded Adapters

Each property's data type determines the type of GUI control generated by the wizard for placement in the Adapter Properties tab of the Properties view for your adapter. The following table shows the GUI controls generated for each property type.

Property's data type	Control generated for the Properties view	Typecheck considerations
int	Text box that accepts only integer values.	Typechecking rejects non-numeric characters, fractional values, and values larger than the int data type's maximum. Negative values are allowed.
long	Text box that accepts only long values.	Typechecking rejects non-numeric characters, fractional values, and values larger than the long data type's maximum. Negative values are allowed. You can append an uppercase L to the value, but it is not required.
double	Text box that accepts only double values.	Typechecking rejects non-numeric characters and numbers larger than the double data type's maximum. Integer and long values are coerced to doubles. Negative values are allowed.
timestamp	Text box that accepts only timestamp values.	Accepts either absolute or interval timestamps, as defined in timestamp Data Type. For an interval timestamp, typechecking accepts a double value representing a number of seconds. For an absolute timestamp, typechecking accepts a string in the format yyyy-mm-dd[ hh:mm[:ss[.ffff[-tttt]]]], where the brackets show optional portions of the string. ffff represents a fractional seconds value with a maximum precision of milliseconds. tttt is a value representing a time zone. Typechecking rejects any value not meeting these standards.
boolean	check box.	Can only be selected (= true) or cleared (= false). If the StreamBase Studio Authoring preference Hide Control to toggle to/from text fields in Java Operator Properties is not enabled, check boxes have a T icon to their right to toggle them into a text field where the user can enter an expression or module parameter evaluating to true or false.
String	Text box that accepts any valid text.	Typechecking allows any valid character in Studio's current character set.
String[]	Table-like edit control.	A string array control shows as a two-column edit table, with non-editable array index values in the first column and editable String values in the second column. In the Value column's table cells, typechecking allows any valid character in Studio's current character set. Example:
Map<String,String>	Table-like edit control for key-value pairs.	A Map<String, String> control shows as a two-column edit table. You can specify (1) no default values, in which case, the end-user must fill in both key and value for each line; (2) key values, in which case the end-user must fill in the value for each key; or (3) both key and value defaults, in which case the end-user is free to edit either column. Example:
enum	Radio button control or drop-down list.	If you specify two values for an Enum, the wizard generates code for a radio button control. With three or more values, the wizard generates code for a drop-down list. Examples:   If the StreamBase Studio Authoring preference Hide Control to toggle to/from text fields in Java Operator Properties is not enabled, radio buttons and drop-down lists have a T icon to their right that toggles them into a text field in which the user can enter an expression or a module parameter evaluating to a string that names one of the control's choices.
ResourceFile	File selection drop-down list.	The ResourceFile type is a special value for which the wizard generates a file selection drop-down list that shows a list of files in the project's current directory. Use the ResourceFile type to allow users of your adapter to select files such as resource, data, or log files to be used by your adapter at runtime. The file to be selected must exist in the Studio project at selection time.
Schema	Edit Schemas tab	The Properties view for the new adapter or operator is augmented with a standard Edit Schemas tab as used throughout StreamBase. Use this to specify the schema for the field whose name you specify in the Name field of the New Adapter Property dialog. The Properties view tab generated has the title Edit Schemas if you select the default control in that dialog, or you can specify a different tab title with the custom control.
(Expression on port enabled)	Text box that accepts a StreamBase expression that evaluates to one of the simple data types.	See Expression on port for details.

The buttons along the right side of the Adapter Properties grid have the following uses:

The New Adapter Property and Edit Adapter Property dialogs have the same fields for a given property data type. These dialogs take a different form for the Enum and String[] data types.

The following controls only appear on the Add or Edit Adapter Property dialog when the Property field specifies String[] or Enum.

This section shows examples of adapter property dialogs in the New Adapter Wizard, and the Properties view pages that result.

The following Adapter Property dialog creates a property of type boolean:

The following dialog creates a property of type String:

The two properties created with the dialogs above are candidates for the Methods to control enablement of UI widget option on the wizard's first page. They appear in the Adapter Properties tab as shown in the following example:

The following dialog creates a property of type Enum. Since two values are specified, the generated result is a radio button control:

The following dialog creates another Enum property, this time with three values. The generated result is a drop-down list control:

The following fragment of an Adapter Properties tab shows the results generated by the previous two Adapter Property dialogs:

The following dialog creates a property of type Map<String, String>. Notice that three of the keys are entered without default values, while the Source key provides a default.

The following fragment of an Adapter Properties tab shows the results generated by the above Adapter Property dialog:

StreamBase currently supports the property types data types shown in the table in Adding Adapter Properties. Most are simple property types that StreamBase derives automatically by looking at the signatures of the getter and setter methods in the Parameterizable class. These can be specified in the BeanInfo class with SBPropertyDescriptor objects, as in the example above.

Enum properties are string properties that can only take on a specified set of values. ResourceFile properties are similar to Enum properties, but their value must be the name of a resource. In StreamBase Studio, this is enforced by displaying a drop-down list of files available from your project's folder.

Because both Enum and ResourceFile properties are implemented as Strings, their getter and setter methods must return and expect objects of type String, respectively. Thus, these property types cannot be automatically derived by StreamBase. To use these properties, an adapter must have an accompanying BeanInfo class that returns the SBPropertyDescriptor subclasses EnumPropertyDescriptor or ResourceFilePropertyDescriptor in its list of PropertyDescriptors.

The BeanInfo class is defined in the java.beans.BeanInfo API documentation. It can be used by the Parameterizable object to:

If a BeanInfo class is present, only the properties explicitly declared in this class are exposed by StreamBase.

The easiest way to make a BeanInfo class is to extend java.beans.SimpleBeanInfo in a class whose name consists of the name of the Parameterizable class, with BeanInfo appended, residing in the same package as the Parameterizable class. For example, if the Parameterizable class is called MyAdapter, the BeanInfo class should be called MyAdapterBeanInfo.

The following example BeanInfo class makes the Clever property optional:

public class ExampleBeanInfo extends SimpleBeanInfo {
  public PropertyDescriptor [] getPropertyDescriptors() {
    try {
        SBPropertyDescriptor [] p = {
            new SBPropertyDescriptor("StartCount", Example.class),
            new SBPropertyDescriptor("Clever", Example.class).optional(),
            new SBPropertyDescriptor("Name", Example.class)
        };

        return p;
    }
    catch(IntrospectionException e) {
        System.out.println("Exception: " + e);
        e.printStackTrace();
    }
    return null;
  }
}

The optional() method shown in this example marks the descriptor as optional. You should mark as optional any new properties you add to existing adapters to preserve backward compatibility with existing StreamBase applications developed using the old adapter. Be sure to provide a default value for each optional property.

When a running adapter needs to temporarily stop accepting tuples it can be suspended and later its operation can be resumed. The sequence of methods for this process is:

For additional details, see Processing of Tuples During the Suspension of an Adapter.

Input adapters often need to perform operations asynchronously with the StreamBase application they are running in. For example, an input adapter may need to listen for information on a socket, or read input from a file, without interrupting the rest of the application. Though output adapters are called upon by StreamBase whenever a tuple arrives on an input port, there may be other asynchronous tasks an output adapter may wish to perform, such as periodically flushing a buffer.

To facilitate such requirements, the adapter API provides a mechanism for creating threads that are managed along with the rest of the StreamBase application. During the init method, an adapter may call registerRunnable(runnable) to register Runnable objects that will be managed in separate threads by StreamBase. When the application starts running, StreamBase will start all registered Runnables in new threads.

StreamBase-managed threads have the following general structure:

...
  public void run() {
    // Perform thread startup tasks
    while (shouldRun()) {
      // Perform tasks such as calling sendOutput
    }
    // Perform thread shutdown tasks
  }
...

The call to shouldRun ties the thread into StreamBase's thread management in the following ways:

Embedded adapters start, resume and shutdown along with the StreamBase application that contains them. It is also possible to suspend and resume embedded adapters independently of their StreamBase application.

This is accomplished with the same commands that are used to suspend and resume a StreamBase application as a whole. The command sbadmin suspend can be used to suspend an application; similarly, sbadmin resume is used to resume a StreamBase application.

To suspend or resume individual adapters, you can append a list of embedded adapters to the sbadmin suspend or sbadmin resume command. If one or more strings are appended to sbadmin suspend, then the StreamBase application as a whole will not be suspended, rather the individual embedded adapters named by the appended strings will be suspended.

Note that an individual embedded adapter can be suspended or resumed only if the StreamBase application itself is running. An individual embedded adapter can be running only if the application that contains it is also running. Therefore, it is not meaningful to suspend or resume an adapter that is not currently running if the application that contains it is not running.

The sbc status command returns status information about the StreamBase Server.

The sbc status --operators command returns the status of any embedded adapters contained by the server's application. Note that sbc status --operators and sbc status are disjoint commands: sbc status returns information about the server only, not about embedded adapters contained in the server. Similarly, sbc status --operators returns information about contained embedded adapters only, and not any information about the server itself.

In this context, the status of an embedded adapter consists only of its current state. For example, if an embedded adapter has been started and is currently running, its state will be STARTED. If an embedded adapter has yet to be started, its state will be NONE. If an embedded adapter has been suspended, its state will be either SUSPENDED_AND_DROPPING_TUPLES or SUSPENDED_AND_PROCESSING_TUPLES. Lastly, if an adapter has been shut down its state will be SHUTDOWN.

By default, an embedded adapter starts along with the StreamBase application that contains it. In Studio, in the General tab for embedded adapters, there is a drop-down menu labeled Start with application that contains the choices Yes and No. By default, this box is selected, meaning that the embedded adapter will start with the application. Clearing this check box causes the adapter to be left in the NONE state when the application starts.

A Java operator that does not start with its application will stay in the NONE state until it is explicitly started with the sbadmin resume adapterName command. Such an adapter will not start even if the application as a whole is resumed. So for example, the application as a whole may suspend and then resume; this will have no effect on an adapter that has not started with its application.

If an embedded adapter is suspended separately from the application that contains it, tuples might still arrive at the suspended adapter. You can configure the embedded adapter to handle these tuples in two different ways:

These two possibilities are represented by static Strings on the class com.streambase.sb.operator.Operator, SUSPENDED_AND_DROPPING_TUPLES and SUSPENDED_AND_PROCESSING_TUPLES, respectively. An embedded adapter is configured to either drop or process tuples by calling the method setSuspendBehavior on its instance. setSuspendBehavior takes an int argument, the value of which must be either SUSPENDED_AND_DROPPING_TUPLES or SUSPENDED_AND_PROCESSING_TUPLES.