The Developer Zone article Using the StreamBase Java Toolkit to Create an Embedded Input Adapter presented a basic overview of the process used to write a custom embedded input adapter. Although this example was quite simple, StreamBase applications frequently have a need for such a simple input adapter that can be used to ensure that something always happens once and only once when the application starts. For example, to update some dynamic variables or to trigger a database read in order to populate a Query Table.
This article, which illustrates how the prior example can be converted into a useful StreamBase component, was developed using StreamBase 3.7 and the StreamBase Java Toolkit for Eclipse, v3.72, which supports development of enqueuer and dequeuer clients, custom Java operators, Java functions, and embedded adapters that are compatible with StreamBase 3.5 or 3.7.
Follow these steps to create an Eclipse project in which to build a StreamBase Custom Embedded Input Adapter.
- In Eclipse, create a new Java project by selecting the File > New > Project menu item, or right-click in the Package Explorer view and select New > Project from the popup menu.
In the New Project, Select a Wizard window, select Java Project and click the Next command button.
In the New Project, Create a Java Project window, enter a Project name and click the Next command button.
- Use the New Java Project, Java Settings window to add the StreamBase client libraries to the project.
Select the Libraries tab and click the Add Library command button, which opens the Add Library window.
Highlight the StreamBase Client API entry and click the Next command button.
Complete the process by clicking the Finish command button.
Follow these steps to generate starting point code using the StreamBase Java Toolkit.
- Highlight the icon corresponding to the Java project, right-click and select New > Other from the popup menu. Alternatively, highlight the project and select the File > New > Other menu entry.
The New, Select a Wizard window opens; expand the options under the StreamBase entry, highlight the StreamBase Embedded Adapter selection and click the Next command button.
- In the New StreamBase Embedded Adapter, StreamBase Embedded Adapter window, select the Input Adapter radio button in the Type grouping, confirm that the Source folder text box references the project directory, enter a package name into the Package text box and a name for the adapter class into the Name text box. Use the controls associated with the Number of output ports label to specify the number of output ports required by the adapter. (You can enter any package and class name you want.) Finally, select the radio button in the Target grouping that corresponds to the version of StreamBase for which you are writing this adapter; then click the Next command button.
- In the New StreamBase Embedded Adapter, Input Adapter window add the class variables that will become the configurable parameters of the custom adapter. To add a variable, click the Add command button; the New Adpater Property window opens.
From the Property dropdown list box, select the String data type. After selecting the variable type, give the variable a name (OutputField), a display name (Output Field Name), and a default value (time); check the Optional property check box, which will allow developers to optionally override the name (time) of this field in the emitted tuple.
Finally, check the Use a background thread check box.
Now, click the Finish command button to generate the starting point code.
The toolkit will generate two Java classes: an input adapter class and a bean info class. You will need to add code to the adapter class and edit the code in the bean info class.
The Input Adapter Class
The Instance Variables
Three instance variables have been defined; one for the Schema associated with the tuple emitted by this adapter, one for the adapter's display name, and one for the name of the field in the emitted tuple.
The Constructor Method
The code within this method has three responsibilities: it invokes the superclass' constructor; it sets the number of output ports; and it sets the default value for each of the configurable properties.
The typecheck Method
Use this method to define the schema associated with the emitted tuple. Add the following JDK 1.4 compliant code before the statement that sets the output schema.
public void typecheck() throws TypecheckException {
if ((getOutputField() == null) || (getOutputField().length() <= 0)) {
throw new TypecheckException("Invalid Output field name");
}
// Output schema has a single timestamp field
ArrayList fields = new ArrayList();
fields.add(new Schema.Field(getOutputField(), DataType.TIMESTAMP, 8));
Schema mySchema =
new Schema("schema:"+getName() + "_out_0", fields, false);
setSchema0(mySchema);
setOutputSchema(0, schema0);
}
If you are using JDK 5 to compile your Java applications, declaration of the ArrayList is more correctly coded as:
ArrayList<Schema.Field> fields = new ArrayList<Schema.Field>();
The fillAndOutputTuple Method
Add the following two lines of code to the body of the fillAndOutputTuple method.
protected void fillAndOutputTuple() {
try {
while (shouldRun()) {
int portCount = getOutputPortCount();
for (int i = 0; i < portCount; i++) {
Tuple tuple = getOutputSchema(i).createTuple();
try {
// Clear the tuple so it can be reused
tuple.clear();
tuple.setTimestamp(getOutputField(), Timestamp.now());
} catch (TupleException e) {
System.err.println("Exception creating tuple");
System.err.println(e);
continue;
}
try {
// Output the tuple
sendOutput(i, tuple);
} catch (StreamBaseException e) {
System.err.println("Exception sending output");
System.err.println(e);
return;
}
try {
Thread.sleep(250);
} catch (InterruptedException e) {
}
}
break;
}
} finally {
try {
// TODO Be sure to close the resource
} catch (Exception e) {
}
}
}
This code sets the value of the Timestamp field in the emitted tuple to the current time (Timestamp.now()). The break statement limits the output of the adapter to a single tuple.
The Bean Info Class
The getPropertiesDescriptor Method
Within the try block, remove the code that adds an SBPropertyDescriptor for the emitted tuple's schema from the PropertyDescriptor[] array returned by the method. In the following code fragment, delete the code identified in bold font.
PropertyDescriptor[] p = {
new SBPropertyDescriptor("OutputField", Once.class)
.displayName("Output Field Name").description("")
.optional(),
new SBPropertyDescriptor("schema0", Once.class), };
Once you edit the contents of the PropertyDescriptor[] array, only those properties explicitly included in the array are available for editing from within the Properties view.
The manifest file that is included in the JAR file with a custom adapter must contain entries that identify the adapter class as a StreamBase adapter. Therefore, you must add a manifest file containing the desired text to this project. Both the content and syntax of the manifest file is very specific. Fortunately, the toolkit will assist you in this task.
- In the Package Explorer, highlight the file that represents the custom input adapter class, right-click, and select StreamBase > Generate StreamBase Manifest from the popup menu.
- In the Generate StreamBase Manifest window, the entry corresponding to your input adapter class should already be identified. Select the Workspace radio button within the Destination grouping, click the Browse command button, and in the Save As window, pick a location into which the file should be written and give the file a name.
Cick the OK button twice and a manifest file, with the required content, is generated.
Before you can use your input adapter in a StreamBase application, you need to prepare a JAR file that contains the .class files and the manifest.
- In the Package Explorer, highlight the icon that represents your project and select File > Export menu item. Alternatively, you can right-click and select Export from the popup menu. In the Export window, select the JAR file entry under the Java category and click the Next command button.
- In the JAR Export, JAR File Specification window, check the checkbox corresponding to the package(s) you want to include in the JAR file and in the JAR file text box, provide the path and name of the JAR file that will be created by this process.
- Then click the Next command button twice to move to the JAR Export, JAR Manifest Specification window.
Select the Use existing manifest from workspace radio button and then enter (or browse to) the path and name of the manifest file written by the toolkit.
Complete the process by clicking the Finish command button. The JAR file will be given the specified name and written to the location provided in the JAR Export, JAR File Specification window.
Follow these steps to incorporate the custom input adapter into a StreamBase application.
- Start StreamBase Studio and create a new project that includes an Application Diagram.
- Import the JAR file (see Creating a JAR File).
- Next drag the Input Adapter icon from the palette onto the canvas. The Select Adapter window opens immediately and your input adapter class is listed in the drop down list.
- Select the adapter class and click the OK command button. The canvas now includes an Input Adapter icon. If desired, use the contols on the Adapter Settings tab of the Properties view to change the name of the field in the emitted tuple; note that since you edited the code generated into the
getProperyDescriptors method in the bean info class, there are no controls on the Edit Schema tab of the Properties view. Now connect the adapter to the downstream component in the application.
If your application includes multiple instances of this 'One Shot' adapter, or other embedded input adapters, there is no guarantee of the order in which the adapters will run during the application startup. If the order in which these adapters run is important, you should deselect the Start with application check box on the Properties view, General tab of each embedded adapter. Then use the sbadmin resume adapter_name command to start the adapters in the desired sequence.
Back to Top ^