This topic explains how to use the StreamBase Embedded Adapter wizard to generate the base code for a custom embedded adapter.
The StreamBase Java Client library includes the
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.
To open the New Embedded Adapter wizard, run→ → .
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 .
Edit the following fields in the wizard's first page:
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 thebutton to select the
java-srcfolder of the Studio project in which you want to create an adapter. Specify the path to an existing
java-srcfolder within a project, or to a referenced folder. The default path entered for you is the
java-srcfolder of the current project.
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 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.
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.
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 Adding StreamBase Client Library to the Project Build Path for details.link to add the Client library to the build path. See
The following image illustrates the wizard's first page, filled in to generate a new input adapter with class name Gryphon:
When ready, click.
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:
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
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.
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.
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.
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
Can only be checked (=
|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
|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.
|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.
|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:
Select an existing property and click Adapter Property Dialog Fields.to amend its values before code generation. Follow the guidelines in
Select an existing property and clickto 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 useor 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.
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.
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.
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 againstall 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 theor 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
SBPropertyDescriptorobject for this property. But when you also select Expression on port, the wizard instead generates an
SBExpressionPropertyDescriptorobject 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
file, and look for a line like the following:
nis 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 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. 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 .
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.
- 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 or to rearrange the value order before code generation.
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:
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.
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
// TODOin the generated adapter class file.
The class generated for an input adapter extends
com.streambase.sb.adapter.InputAdapter. Input adapters must call
sendOutput(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(to receive tuples from the application.
Clickto 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.
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 → 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.