Using the StreamBase Embedded Adapter Wizard

Introduction

The StreamBase Java Client library includes the com.streambase.sb.adapter.InputAdapter and com.streambase.sb.adapter.OutputAdapter classes, which you can extend to define custom embedded adapters for your StreamBase applications. Embedded adapters run in the same StreamBase Server process that is hosting and processing your application's requests. This eliminates the client-server communication overhead seen when using external adapters. Embedded adapters start and stop automatically with the StreamBase application, which simplifies many administration tasks.

The Embedded Adapter wizard helps you get started with the StreamBase Client API for Java by stepping you through the adapter definition process. The Java source file that it generates includes commented TODO sections that you can later edit to add the functionality that implements your adapter.

After you replace these sections with your implementation code, you can use the adapter immediately in applications that you run locally in StreamBase Studio. If you are running your applications on a remote StreamBase Server, you can package your adapter classes as a JAR file and copy it to the remote server, with references to the JAR file in the remote server's configuration file. As an alternative, you can bundle your project including the new adapter into a StreamBase bundle file, and run the bundle on the remote server.

Starting the StreamBase Embedded Adapter Wizard

To open the New Embedded Adapter wizard, run File → New → StreamBase Embedded Adapter.

You can also:

Select StreamBase Embedded Adapter from the New button's drop-down list in the toolbar ().
Click the New button in the toolbar, open the StreamBase Java Wizards folder, select StreamBase Embedded Adapter, and click Next.

Embedded Adapter Wizard First Page

Edit the following fields in the wizard's first page:

Type

Select Input Adapter or Output Adapter.

Input adapters take information from outside of a StreamBase application and provide it in the form of one or more streams to the application.
Output adapters take streams from a StreamBase application and make them available in some form outside of the application.

Source folder

Use the Browse button to select the java-src folder of the Studio project in which you want to create an adapter. Specify the path to an existing java-src folder within a project, or to a referenced folder. The default path entered for you is the java-src folder of the current project.

Package

Specify the name of a Java package to contain your adapter class, such as com.example.sb.adapters, or leave the field empty to specify the default Java package. (If you leave the field blank, the wizard shows a warning message that using the default package is not recommended by Java best practices.)

If the Source folder already contains a Java package, you can use the Browse button to select it. You can also type part of the package name and press Ctrl+Space to use content assistance to fill in the rest of the name.

Name

Specify a name for the Java class that will implement your adapter. By Java convention, class names begin with an uppercase character. The name in this field becomes both the class name and the basename of the Java source files generated by the wizard.

Display Name

Specify a display name to identify your adapter in StreamBase Studio. This becomes the label of the adapter icon that will be placed in the Project Adapters drawer of the Palette view when the wizard is finished (and you have refreshed the project's typecheck environment). If you leave this field blank, the class name in the Name field is used as the display name.

Ports

For input adapters, specify the number of output ports for this adapter.
For output adapters, specify the number of input ports for this adapter.

Client API Library

If the wizard detects that the Java Client library is not yet on the selected project's build path, it displays an informational message and suggests a solution. Click the Click here link to add the Client library to the build path. See Adding StreamBase Client Library to the Project Build Path for details.

The following image illustrates the wizard's first page, filled in to generate a new input adapter with class name Gryphon:

When ready, click Next.

Specifying Adapter Features and Properties

The wizard's second page is labeled Input Adapter or Output Adapter, depending on your selection in the Type control on the first page. The input and output adapter pages are almost identical, with some differences in the defaults, as noted in this section.

Edit the following fields in the wizard's Input Adapter or Output Adapter page:

Adapter Properties

Specify one or more properties that can be set or modified by users of your adapter to control its operation. For each property you specify, the wizard generates code to place a control in the Adapter Properties tab of the Properties view for your adapter's icon. See Adding Adapter Properties for details on using this section.

Use a background thread

When enabled, this option generates code that enqueues or dequeues tuples in a thread separate from the module’s main thread.

Default state for input adapters: enabled.

Default state for output adapters: disabled.

Method stubs to create

The wizard generates stub code for the following methods in the class that implements your adapter:

init()

When enabled, this option generates stub code for an init() method that runs when the adapter is started by its hosting StreamBase Server.

Default state for input adapters: enabled and the control dimmed. (That is, the wizard always generates an init() method for input adapters and you cannot specify otherwise.)

Default state for output adapters: enabled.

resume() and suspend()

When enabled, this option generates stub code for suspend() and resume() methods that allow this adapter to respond to runtime suspend and resume conditions in the StreamBase Server instance that hosts this adapter.

Default state for both input and output adapters: disabled.

shutdown()

When enabled, this option generates stub code for a shutdown() method that allows this adapter to provide processing steps such as closing logs and files when the hosting StreamBase Server begins to shut down.

Default state for both input and output adapters: enabled.

Methods to control enablement of UI widgets

When enabled, this option generates stub code for each property you added in the Adapter Properties section, that allows each property to be enabled or disabled depending on conditions you specify in code. Disabled properties are dimmed in the Adapter Properties tab of the Properties view for your adapter's icon. You might use this feature in a set of related properties, to enable one property only if another property in the group is enabled.

For example, in a set of two properties, one property might provide a check box in which the adapter's user specifies whether or not to filter a stream, while the second property provides a text box in which the user specifies the string to filter against. In this case, you can enable the text box property only if the check box property is enabled first.

Default state for both input and output adapters: enabled. This control is dimmed until you have added at least one property in the Adapter Properties section of this dialog page.

The following image illustrates the wizard's second page, filled in to generate a new input adapter.

Adding Adapter Properties

An adapter property is a Java property for your adapter. For each property you specify, the wizard generates code to place a control in the Adapter Properties tab of the Properties view for your adapter. After you add implementation code to the generated stub code, the end-user of your adapter can use these controls to modify the operation of your adapter.

Property Data Type Determines Generated Control

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 checked (= `true`) or cleared (= `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:
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.

Adapter Properties Buttons

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

Add: Click Add to add a property for this adapter, following the guidelines in Adapter Property Dialog Fields.
Edit: Select an existing property and click Edit to amend its values before code generation. Follow the guidelines in Adapter Property Dialog Fields.
Remove: Select an existing property and click Remove to delete it.
Up, Down: Controls are placed on the Adapter Properties tab of the Properties view in the order specified here in the wizard's Adapter Properties control. Select an existing property and use Up or Down to rearrange the order of properties before code generation.
Deselect All: Click to clear the Optional check box for all properties in the Adapter Properties table.
Select All: Click to select the Optional check box for all properties in the Adapter Properties table.

Adapter Property Dialog Fields

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.

Property

Select a data type for this property from the drop-down list. Remember that the selection of data type determines the GUI control the wizard generates for placement on the Properties view's Adapter Properties tab. For a table of generated GUI controls by data type, see Property Data Type Determines Generated Control.

Name

Enter a name for a Java variable for the wizard to use to identify this property in the generated code.

Display Name

Enter a string to be used as the label for the control generated for this property. The text you enter here is seen by end-users of your adapter as the label for this control in the Adapter Properties tab of the Properties view. In the following example, the two questions and the label Stock symbol to filter against all started life as Display Name entries in this wizard:

Default Value

Does not appear when the Property field specifies String[] or Enum. Enter or select an optional value to serve as the default-entered value for the GUI control generated for this property. For the numeric data types (int, double, and long) an initial default value of 0 or 0.0 is entered for you. For boolean properties, select between true and false in a drop-down list; false is the initial selection. For String and ResourceFile types, the initial default value is an empty string.

Optional property

Select the check box to make this property optional, or leave it cleared, the default, to make this property required. An optional property generates a GUI control that does not need to be filled in by the end-user. A required property must be filled in before an instance of the generated adapter will pass typechecking. Required properties show with an asterisk on the left side of the GUI control's text box or check box.

You can use the Select All or Deselect All buttons later to change this value for all properties at once.

Expression on port

Adapter properties are normally expressed as static values that are determined by the adapter's end-user when configuring the adapter's Properties view. As an alternative to specifying static properties, you can use the Expression on port control to specify an adapter property's value dynamically, based on incoming tuple data. The Expression on port control is an advanced feature that requires you to add supporting code to your adapter class that is not generated by this wizard.

The Expression on port control is enabled only when the Property field is set to one of the simple data types (int, long, double, boolean, or String), and is dimmed for other values of the Property field. Use the Expression on port control to specify that the Properties view control generated for this property appears as a text field that accepts a StreamBase expression that resolves to the data type specified in the Property field.

For example, if you select a boolean data type in the Property field, the generated GUI control is normally a check box, as shown in the table in Property Data Type Determines Generated Control above. However, if you also select Expression on port, the generated GUI control instead becomes a text field that takes a StreamBase expression that resolves to a boolean.

In code terms, when you select a simple data type in the Property field, the wizard generates an SBPropertyDescriptor object for this property. But when you also select Expression on port, the wizard instead generates an SBExpressionPropertyDescriptor object for this property. (See the Javadoc for the StreamBase Client Library for details.)

You, the adapter developer, do not specify the actual expression to use. You are allowing a place on the adapter's Properties page for the adapter's end-user to specify an expression at adapter setup time.

You must also specify an input port whose tuples are to be used in the course of evaluating the end-user's expression, which can optionally refer to fields in the tuple. Input ports are zero-based, so select 0 from the spin control to specify the adapter's first input port. Select 1 to specify the adapter's second input port, and so on. You can specify any input port, independent of the use your adapter makes of the port. This includes input ports on which you expect streams of incoming data, as well as input ports on which you expect only occasional tuples that manage or alter the operation of the adapter as it runs.

At runtime, the adapter evaluates the end-user's specified expression against each tuple arriving on the specified input port, and the adapter is passed the newly computed value for the property via its setter method. Thus, when your adapter is processing each tuple, it should retrieve the latest value for this property simply, by using the property directly, or via its getter method.

The end-user's expression is evaluated against incoming tuples on input ports only. Since input adapters generated with this wizard do not have input ports by default, this means that the Expression on port feature is only appropriate for:

An output adapter you are currently generating with this wizard (which always has one or more input ports).
An input adapter you are currently generating with this wizard, for which you plan to add an input port later by editing the generated code. You might do this, for example, to add a control port to an input adapter.

In this case, you can enable the Expression on port control while running the wizard, in anticipation of having an input port later. Then when the wizard generates the code, open the generated classname.java file, and look for a line like the following:
```
setPortHints(0, n);
```
where n is the number of output ports you specified on the wizard's first page. Change the 0 to 1 to enable one input port, then provide the code that specifies a schema for this input port.

Place property UI widget in tab

By default, all properties you define for your adapter are placed on the same default Adapter Properties tab in the Properties view for your adapter. Use this control to create additional tabs, and to place different properties on different tabs.

For example, when you specify a boolean property, Studio generates a labeled check box. Select custom and fill in the name you want to give for a new tab in the Properties view. Use the case and spelling you want to see in the adapter's Properties view. To add your new boolean check box to a new tab named Debug Settings, select the custom radio button and type Debug Settings in the text field.

Leave the default radio button selected to place this property in the default Adapter Properties tab.

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

Add a Value

Type a value name and click Add. Remember that the values you enter here are visible to your adapter's end users. These values become the labels for a radio button control, or the members of a drop-down list, or the default values for an edit table control.

Entered Values

Shows the values entered for the current Enum or String[] property.

Add Button

Type a value in the Add a value field and click Add.

For an Enum, you must enter at least two values. Two values generates a radio button control. Enter three or more values to generate a drop-down list.

For a string array, enter one or more values, which become the default values for the array. The end-user can edit or replace the values you type here.

Remove Button

Select an existing value and click Remove.

Up and Down Buttons

The order of the values in the Entered Values list becomes the text order in the generated radio button control, drop-down list, or edit table control. Select a value and use Up or Down to rearrange the value order before code generation.

Adapter Property Dialog Examples

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

Boolean and String Examples

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:

Enum Examples

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:

Map Example

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:

Adapter Wizard Final Steps

After completing the second page of the New StreamBase Adapter wizard, complete the process with these steps:

When you are done adding properties on the second page, click Finish.

The wizard generates two Java files: one containing an adapter class, the other, a beaninfo class. You will probably not need to edit the beaninfo class file. However, you must provide implementation code for all places marked // TODO in the generated adapter class file.

The class generated for an input adapter extends com.streambase.sb.adapter.InputAdapter. Input adapters must call sendOutput(int, Tuple) to provide tuples to the application.

The class generated for an output adapter extends com.streambase.sb.adapter.OutputAdapter. Output adapters must override the method processTuple(int, Tuple) to receive tuples from the application.
Click OK to complete the wizard.
The wizard generates Java code for your adapter, opens the primary class file for editing, then prompts you to refresh the project's typecheck environment. The first time you run the wizard, it automatically refreshes the typecheck environment so that the new adapter's icon appears right away in the Palette view.

Tip

You must refresh the typecheck environment again every time you make changes to the adapter's Java code. Do this by pressing Ctrl+F5 (or by right-clicking the project's name in the Package Explorer and selecting StreamBase → Refresh Typecheck Environment from the context menu).
An icon for your new adapter now appears in in the Project Adapters section of the Insert Input Adapter or Insert Output Adapter dialog, as appropriate. Invoke these dialogs by dragging the Input Adapter or Output Adapter icon from the Operators and Adapters drawer of the Palette view to the canvas. Add an instance of your adapter to the canvas by selecting your adapter's icon in the dialog and clicking OK.