Using the StreamBase Java Function Wizard

StreamBase includes many built-in functions, but if you need more you can use the StreamBase API to add your own. The StreamBase Java Function wizard can generate stubs for custom functions, which you can then customize for your specific needs by replacing the // TODO sections in the generated Java source with your implementation code. Optionally, you can also use the wizard to create an alias for your function. You can then call the functions in expressions within a StreamBase application, using either the calljava function or the alias.

Starting the Java Function Wizard

Use this wizard to start defining one or more StreamBase custom Java functions.

To open the wizard, click File → New → StreamBase Java Function.

To define a function, edit the fields as follows:

  1. Type: Choose either simple or aggregate:

    • Simple functions can be used in any StreamBase operator.

    • Aggregate functions are available in the Aggregate operator and Query operator. They are evaluated over groups of arguments (such as the values in a window of an Aggregate operator) and return a single result.

  2. Source folder: The path to an existing folder in which to create your function class. Specify the java-src folder that StreamBase projects have by default, or any other java source folder.

  3. Choose where to create your function. For an aggregate function, you must create a new class. For a simple function, you can either add your function to an existing class, or create a new one from scratch:

    • Existing Class: If you choose this option, click Browse to select the class.

    • New Class: For an aggregate function, this option is preselected and cannot be changed. With this option selected, you must also specify the remaining two fields:

      • Package: While you could use the default package, it is recommended that you specify one, such as com.mycompany.mysbapps.functions. Click Browse to choose an existing one.

      • Name: Enter A name for your new class, such as MyFunctions.

For example:

When you are ready, click Next to proceed to the next page. Depending on your selection, go on to either the Defining Simple Function Properties or Defining Aggregate Function Properties section for details.

Defining Simple Function Properties

The Add/Edit page is the second page of the StreamBase Java wizard for a simple custom function. Use it to define one or more functions.

  1. Click Add. Then, in the StreamBase Simple Function dialog:

    1. Specify the Function Name and Return Type.

    2. If the function will have arguments, add them now: For each argument choose a data type using the Select Type control, then click Add to insert a new entry of the specified type in the Argument List.

      Argument names are automatically assigned in sequential fashion (arg0, arg1, ...). You can edit the names in the Argument List. You can also change the data types if you need to.

      The order of arguments expected in the function is determined by their order in the Argument List. You can use the Up and Down buttons to change the order.

    3. Click OK to save the function.

  2. Click Add again in the Simple Function page to define any additional functions.

  3. Optionally, use the other control buttons to edit, remove, or reorder your functions.

  4. If you checked an option to add the function to an existing class, click the Insertion Point control and indicate where you want the new function to be inserted. Choose one of these options:

    • First method

    • Last method

    • After method, where method is the name of an existing method. The menu contains an option for each method in the class.

    • Current cursor position (if target file was already open)

  5. If you want to use aliases in your function, check the Create Function Aliases box, and click Next. In the Create StreamBase Custom Function Aliases dialog:

    1. Choose the projects to create your aliases in[1].

    2. The Aliases grid shows the currently defined functions and the alias names that will be created. Optionally, you can change the default alias names in the grid.

    3. If you defined any functions with String return types, specify the length to use.

    4. Click Finish.

  6. When you are done, click Finish.

Defining Aggregate Function Properties

In the StreamBase Custom Java Aggregate Function page, the wizard will help you specify arguments for one or more required accumulate() methods; then you will select the return type for calculate() to finish creating the aggregate function.

A brief explanation: All custom Java Aggregate classes extend AggregateWindow. Your subclass must implement an accumulate method that corresponds to the argument number and data types that the calljava expression in the Aggregate operator refers to.

Your subclass must also implement a calculate method. When data is sent from the aggregate window, the calculate method must return a type mapping to a StreamBase data type. The AggregateWindow object is likely to be used several times. At the start of each new use, the init() method will be called. Then accumulate and calculate may be called. Finally, at the end of each use, release will be called.

You can find these elements in the java file generated by the wizard.

In the StreamBase Custom Java Aggregate Function page:

  1. Add one or more accumulate methods. To add a method, click Add. Then in the New Arguments dialog, define one or more method arguments:

    1. For each argument, specify a data type using the Select Type control, and click Add to insert a new entry of the specified type in the Argument List.

    2. Optionally, change the generated argument names in the Argument List.

    3. The order of arguments expected in the function is determined by their order in the Argument List. You can also use the Up and Down buttons to change the order.

    4. When you have defined all the arguments, click OK to close the New Arguments dialog.

  2. Specify the return data type for calculate().

  3. You can click Add again in the Aggregate Function page to add any number of accumulate() methods to the function.

  4. Optionally, use the other control buttons to edit or remove methods. You can also reorder them on the wizard page.

  5. If you want to use aliases in your function, check the Create Function Aliases box, and click Next. In the Create StreamBase Custom Function Aliases dialog:

    1. Choose the projects to create your aliases in[1].

    2. The Aliases grid shows the currently defined functions and the alias names that will be created. Optionally, you can change the default alias names in the grid.

    3. If you defined any functions with String return types, specify the length to use.

    4. Click Finish.

  6. When you are done, click Finish.

Editing the Generated Java Source

When you click Finish, the wizard generates a single java source file containing all the functions you defined, and opens the file in the Java Editor.

Here is a portion of a simple generated java file. As the sample shows, all custom simple functions must be in a public Java class as a public static method. In your file, look for the // TODO comments and complete the coding for your function: 

package com.mycompany.mysbapps.functions;

public class MyFunctions {
   .
   .
   .
    public static int times2(int volume) {
        // TODO Implement function here
        return 0;
    }

Related Topics

  • For the Java API Javadoc, see the StreamBase Application Programming Interfaces topic of the StreamBase Reference Guide.

  • For information about function aliases, see the custom-functions section of the sbd configuration file documentation, StreamBase Server Configuration XML.


[1] The list of projects is limited to those whose build paths include your target project (the project where your function's class file will be created). To make other projects available, see Adding Other Projects to the Java Build Path.