Library Articles
Using the StreamBase Studio Java Operator Wizard
Authors: Eddie Galvez, Bingfang Song, Dr. John Lifter
StreamBase Systems
Date: 01-September-2007
Applicable To: Streambase 5.0
Topics
You can use StreamBase Studio to write code to implement a custom Java operator. A wizard will collect basic information about your operator, for example, the number of input and output ports or the names and types of the operator's configurable parameters, and then generate starting point code for your implementation. In many cases, your only task will be to flush out the code within the operator's methods; in more involved situations, you may need to include code for helper classes or integrate your operator with external resources.
This article overviews the code generated by the wizard and describes the basic implementation tasks. The description is specific to StreamBase 5 and later point releases. If you are using StreamBase 3.5 or 3.7, refer to the discussions in Using the StreamBase Java Toolkit to Write a Custom Java Operator.
Create a StreamBase or standard Java project. If you choose to create a StreamBase project, the New StreamBase Project, StreamBase Project window will give you the opportunity to add the StreamBase Client API to the Java build path. If you choose to create a standard Java project, the New Java Project, Java Settings window will give you an opportunity to add the StreamBase Client API to the project.
A best practice would be to create your custom Java operator in a dedicated project, which may then be included on the build path of any StreamBase project that uses this operator. Since the project will only include the .java files related to your operator, there is no need to include .sbapp, .ssql, or a StreamBase configuration file in this project.
In the Package Explorer, highlight the project, right-click, and select New > Other... from the popup menu. Alternatively, select the File > New > Other... menu item. In the New, Select a Wizard window, expand the selections under the StreamBase Java Wizards listing and highlight the StreamBase Java Operator entry. Click the Next command button to start the New StreamBase Java Operator wizard.
After the wizard starts, the New StreamBase Java Operator, StreamBase Java Operator window opens. Confirm that the Source folder: text box references the java-src directory under a StreamBase project (as illustrated in the following figure) or the project directory in a Java project, then enter a package and class name into the appropriate text boxes.
Finally, use the spinner controls to set the number of input and output ports required by your operator; then click the Next command button.
In the New StreamBase Java Operator, Java Operator window add the class variables that will become the configurable parameters of the custom operator. To add a variable, click the Add command button; the New Operator Property window opens.
From the Property: dropdown list box, select the data type of the variable (note that you must scroll down the listing to see the String[] and Enum entries). After selecting the variable type, give the variable a name, a display name, and a default value. If it is optional that developers set a value for this variable, check the Optional property check box.
If the operator class has more than one configurable parameter, click the Add command button and add additional variables to the class definition. In this exercise, add a variable of each type, as illustrated in the following figure.
When adding the multiple entries in a String[] or Enum type, enter one of the valid entries into the Default Value: text box and then click the Add command button. This moves the entry to the Entered Values: listing. Repeat until all desired values have been entered.
Check the desired checkboxes under the Which method stubs would you like to create? label and then click the Finish command button to generate the starting point code.
The toolkit will generate two Java classes: an operator class and a bean info class. You will not need to edit the content of the bean info class, but you do need to provide implementations for the typecheck and processTuple methods, and optionally for the init and/or shutdown methods in the operator class; you will need to edit the body of the constructor method if you have an Enum type as a configurable parameter.
The Instance Variables
Review the code in the operator class. Note how the names assigned to the instance variables (and their corresponding getter and setter methods) are derived from the field name entries made in the New StreamBase Java Operator, Java Operator window.
The Constructor Method
The code within this method has three responsibilities: it invokes the superclass' constructor; it sets the number of input and output ports; and it sets the default value for each of the configurable parameters. Note that a default value is not set for Enum configurable parameters and consequently an initialized control corresponding to this configuration field will not be included on the operator's Properties view, Parameters tab. To complete the coding within the constructor method, add the following line to the generated code.
public MyOperator() {
super();
setPortHints(1, 1);
setAnInt(0);
setALong(0);
setADouble(0.0);
setABool(false);
setAString("hello");
setAStringArray(new String[] { "one", "two", "three" });
setAnEnum("UPPER");
}
The Typecheck Method
The generated code iterates over each input port and retrieves and stores the schema associated with that port. The next statement iterates over the output ports and sets the schema of each output port to the same schema for the correspondingly numbered input port. This simple coding is suitable as a starting point, but in an actual implementation, you will want to do some additional testing to be certain that the developer has properly configured the operator. For example, you might examine an input schema and confirm that it contains fields of the required type, or you might check that the developer has supplied a value for a configuration variable that did not have a preset default value. Also, it is likely that the schema of the emitted tuple will not be identical to the schema of the incoming tuple, and you will need to replace the generated code.
In the operator developed in this example, it is important that the first field in the incoming tuple is a string type. The following code, added after the TO DO: Ensure that all the properties have valid values comment, confirms that this restriction is satisfied.
Schema inSchema = getInputSchema(0);
Field[] fields = inSchema.getFields();
boolean hasStringField = false;
DataType dt = fields[0].getDataType();
if(DataType.STRING.equals(dt)) {
hasStringField = true;
}
if(!hasStringField)
throw new TypecheckException
("The first field must be a string type");
The Process Tuple Method
Within this method you write the processing logic for the operator.
In this example, the first field in the tuple received by the operator will be a string field. You will simply transfer the value from the operator's Enum instance variable into the corresponding string field in the emitted tuple.
Replace the for loop with the following line of code and then save the file. In the StreamBase Java API documentation, review the other methods through which a tuple field value may be set.
tuple.setField(0,getAnEnum());
Follow these steps to incorporate the custom Java operator into a StreamBase application.
- Create a new StreamBase project that includes an Application Diagram. (Custom operators may also be used within a StreamSQL document; refer to the discussion of the
APPLY statement for details.)
- Include the project in which you developed the custom Java operator on the new project's build path.
- Next drag the Java Operator icon from the Project Operators grouping in the Palette view onto the canvas.
- Complete the application by adding an input and output stream. In the StreamBase Properties view, Edit Schema tab of the input stream, define any schema you want, just be certain that the first field is of type string and at least 5 characters in size (this field will be set to the value held in the
AnEnum variable, which is a string of length 5 characters).
- Highlight the Java Operator icon and in the StreamBase Properties view select the Parameters tab. Note how each configurable instance variable can be set from a control within the Parameters tab.
Run the application and observe that whatever value is currently set in the variable AnEnum will be transferred to the first field in the emitted tuple. To confirm that your implementation of the typecheck method will identify incorrect incoming schemas, change the schema associated with the input stream so that its first field is a non-string type. You should see the error message coded in the typecheck method displayed on the StreamBase Properties view.
While working within StreamBase Studio, there is no requirement that the custom operator code be packaged into a JAR file with a manifest that identifies the operator class. To use this operator in a deployed application it is, however, convenient to package the operator's files into a JAR file. StreamBase Studio will create the required manifest and JAR files.
In the Package Explorer, highlight the file that extends the superclass com.streambase.sb.operator.Operator, right-click, and select the StreamBase > Generate StreamBase Manifest... menu item from the popup menu.
In the Generate StreamBase Manifest window, confirm that the correct class is selected in the Class Name listing, then click the Browse command button to open the Save As window.
In the Save As window, specify the directory location and name under which the manifest file will be saved. It is a good practice to name the file manifest.mf and to save it in the same project directory as the operator's source code files. In the Package Explorer, double click on the manifest file and review its contents; note how Studio has provided the required content and formatting.
Once you have the manifest file, you can use the built-in Eclipse functionality to create and export a JAR file. In the Package Explorer, highlight the project containing your operator code and manifest file and either select the File > Export... menu item, or right-click and select Export... from the popup menu.
In the Export, Select window, expand the listing under the Java icon and select the JAR file entry, then click the Next command button. Your selections in the JAR Export, JAR File Specification window may initially seem a little strange, but it will be clearer once you have worked through the process.
Note how only the operator's source code files are selected through the entries in the left-hand panel. A subsequent window will let you add the manifest file to the JAR; the .project, .classpath, and .sbapp files are not part of the custom operator code and should not be included in the JAR file. Click the Browse command button and in the Save As window select the directory location and name for the JAR file; alternatively, enter the path and name of the JAR file directly into the JAR file: text box. Click the Next command button.
In the JAR Export, JAR Packaging Options window select the desired options. Note that the default entries will create a JAR file containing files with compilation warnings and errors. While you are developing your operator, it is useful to accept files with compilation warnings as these may simply be indications that you have not completed your coding and your code contains unused variables and/or class imports. Click the Next command button to move to the JAR Export, JAR Manifest Specification window.
In the JAR Manifest Specification window, select the Use existing manifest from workspace radio button then click the associated Browse command button and, in the Manifest Selection window, select the manifest file you previously saved in your operator project directory. Click the OK and Finish command buttons to complete the process. The JAR file will be written to the directory location specified earlier.
When you want to use this custom operator in other StreamBase applications, simply add this JAR file to the new project's build path as described in the article New Features in StreamBase Studio.
New Features in StreamBase Studio
Using the StreamBase Studio Custom Function Wizard
Using the StreamBase Studio Client Wizard