Library Articles
Using the StreamBase Studio Client Wizard
Authors: Eddie Galvez, Bingfang Song, Dr. John Lifter
StreamBase Systems
Date: 01-September-2007
Applicable To: StreamBase 5.0
You can use StreamBase Studio to write code that implements a network client to a StreamBase application. A wizard will collect basic information about your client, for example, the URI of the target StreamBase application or the names of the input or output streams, and then generate starting point code for your implementation. In many cases, your only task will be to flush out the code within the processTuple method of a dequeuer client or the fillTupleValues method of an enqueuer client. In more involved situations, you may also want to include code that will run in parallel with the StreamBase dependent processing.
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 Writing a Java Enqueuer Client and Writing a Java Dequeuer Client.
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 network client(s) in a dedicated project. Since the project will only include the .java files related to your network client application, 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 Client entry. Click the Next command button to start the New StreamBase Client wizard.
After the wizard starts, the New StreamBase Client, StreamBase Client window opens. Select the Dequeuer radio button in the Type: grouping. If you created a StreamBase project, confirm that the Source folder: text box references the java-src directory; with a standard Java project, the Source folder: entry will simply include the project directory as shown in the following figure. Next, enter a package and class name into the appropriate text boxes then click the Next command button to move to the New StreamBase Client, New StreamBase Client Dequeuer window.
If you want this client to dequeue tuples from all output streams in the target StreamBase application, select the All Streams radio button in the Dequeue From: grouping. If you select this choice, the generated code will obtain a listing of all output streams from its proxy to the StreamBase application. Alternatively, you can select the Specified Streams radio button, which enables the Add a Stream: text box and associated command buttons. Enter the name of an output stream from which you want to dequeue tuples and then click on the Add command button to add the stream name to the Streams: listing. If appropriate, you can specify a fully qualified stream name, that is, containerName.streamName. After a stream name has been added to the Streams: listing, you may select the entry and edit the Predicate, which will be used to filter the tuples received on this stream.
Enter the computer where the StreamBase application is hosted and the TCP/IP port it is using in the Host: and Port: text boxes. As appropriate to your requirements, check the Use background thread checkbox (circled), then click the Finish command button to complete the process.
Understanding the Generated Code
Most of the generated code is boiler plate, which you will not need to edit. This code creates a proxy to the target application and then subscribes (or filter subscribes) to each of the output streams. You may, however, want to edit two of the instance variables: SB_URI and streamNames. You would edit SB_URI if you want to include the container name as part of the URI; the wizard does not provide a means to specify a container other than default. You would edit the streamNames variable if you want to change the listing of specified streams. For example, you may have initially only listed one stream and now you want the client to dequeue from two streams; you cannot accomplish this objective by simply rerunning the wizard.
For example, change
private final static String SB_URI = "sb://localhost:10000";
private String[] streamNames = { "OutputStream1"};
to
private final static String SB_URI = "sb://localhost:10000/containerName";
private String[] streamNames = { "OutputStream1", "OutputStream2" };
Your primary responsibility is to implement the processTuple method. The generated code simply converts the contents of each tuple to a string, which it then displays.
private void processTuple(StreamProperties streamProperties, Tuple tuple) {
System.out.println("Tuple dequeued: " + tuple.toString()
+ " from streamProperties: "
+ streamProperties.getQualifiedName());
}
You should remove the generated code and add the code that actually consumes the tuple fields in some meaningful way.
If you selected the option to use a background thread, the generated code will dequeue and process the tuples in a separate thread from the main application. This design allows your network client to perform other processing in parallel with the tuple processing. In this situation, you will need to add code for the parallel processing within the while loop in the run method.
while (running) {
try {
Thread.sleep(1000);
// TODO: Do work here, if any, while the background dequeuer thread runs
} catch (InterruptedException e) {
throw new StreamBaseException(
"Exception during Thread.sleep", e);
}
}
If you did not select threading, the generated code will not include the while loop.
After the wizard starts, the New StreamBase Client, StreamBase Client window opens. Select the Enqueuer radio button in the Type: grouping; confirm that the Source folder: text box identifies the desired project directory (or subdirectory); then enter a package and class name into the appropriate text boxes then click the Next command button to move to the New StreamBase Client, New StreamBase Client Enqueuer window.
If you want this client to enqueue tuples to all input streams in the target StreamBase application, select the All Streams radio button in the Enqueue To: grouping. If you select this choice, the generated code will obtain a listing of all input streams from its proxy to the StreamBase application. Alternatively, you can select the Specified Streams radio button, which enables the Add a Stream: text box and associated command buttons. Enter the name of an input stream to which you want to enqueue tuples and then click on the Add command button to add the stream name to the Streams: listing. If appropriate, you can specify a fully qualified stream name, that is, containerName.streamName.
Enter the computer where the StreamBase application is hosted and the TCP/IP port it is using in the Host: and Port: text boxes. As appropriate to your requirements, check the Use background thread, Enable buffering, and/or Enable batching checkboxes (circled), then click the Finish command button to complete the process.
Understanding the Generated Code
Which combination of the Use background thread, Enable buffering, and Enable batching checkboxes you select affects the content of the generated code. If you do not select any of these checkboxes, the wizard generates a basic enqueuer client that includes:
- A
main method that:
- Creates a StreamBase URI
- Calls the enqueuer class'
constructor
- Calls the
run method on the enqueuer class
- A
constructor method that creates an instance of the proxy class — StreamBaseClient
- A
run method that:
- Iterates through the input streams
- Calls the
fillTupleValues method on the enqueuer class
- Calls the
enqueue method on the StreamBase proxy
- A
fillTupleValues method that sets values into each tuple field
When this application runs, it repeatedly initializes and enqueues a tuple for each input stream. Note that the run and fillTupleValues methods pass a collection of tuples back-and-forth even though only one tuple is being added to the collection and enqueued by the proxy. The code generated when you select the Enable batching checkbox will make fuller use of this coding paradigm.
Selecting the Enable batching checkbox modifies the code within the fillTupleValues method so that each invocation adds multiple tuples to the collection passed between the fillTupleValues and run methods. Within the run method, the entire collection is enqueued through a single call to the proxy's enqueue method.
If you select the Enable buffering checkbox, the code generator adds an additional line of code, which invokes the enableBuffering method on the StreamBase client proxy, to the constructor method.
If you select both the Enable batching and Enable buffering checkboxes, the proxy will not actually send tuples to the StreamBase application until the buffering specification is satisfied. For example, if batching results in each invocation of the fillTupleValues method adding five tuples to the collection, and buffering is configured to transmit groups of twenty tuples to the StreamBase application, tuples will not be sent to the target application until the fillTupleValues method has been invoked four times (or the flush interval has expired).
Finally, if you select the Use background thread checkbox, the generated code includes two additional methods – startBackgroundEnqueuerThread and generateTuples – that create a separate thread responsible for enqueuing tuples to the StreamBase application. The main thread is still responsible for creating and initializing the collection of tuples that are sent to the StreamBase application. By using multiple threads, the network client can perform other processing in parallel with the enqueuing process.
Regardless of which combination of code generation options you select, the fillTupleValues method simply places a null value into each tuple field; you will need to edit this method so that meaningful values are set into each tuple field.
New Features in StreamBase Studio
Using the StreamBase Studio Custom Function Wizard
Using the StreamBase Studio Java Operator Wizard