Using the StreamBase Java Function Wizard

Contents

Starting the Java Function Wizard
Defining Simple Functions
Defining Aggregate Functions
Editing the Generated Java Source

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 Functions.

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 in certain contexts of the Query operator. Aggregate functions are evaluated over a group 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. For best compatibility with StreamBase Studio, specify the src/main/java folder of the current StreamBase project.

  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 class 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.example.sbapps.functions. Click Browse to choose an existing package in the current project.

      • 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 Functions or Defining Aggregate Functions section for details.

Defining Simple Functions

Use the second page of the wizard to define one or more functions, and the argument and return data types for each function.

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

    1. Specify the Function Name.

    2. Specify a Return Type from the dropdown list.

    3. 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 grid.

      Argument names are automatically assigned in sequential fashion (arg0, arg1, and so on). You can edit argument names by clicking in the Name column in the Argument List grid. (Click in the Type column to change the data type, if necessary.)

      The order of arguments in the Argument List grid determines the function's argument order. Use the Up and Down buttons to rearrange the argument order.

    4. Click OK to save the function.

  2. Click Add again in the Simple Function page to define any additional functions, or use the other control buttons to edit, remove, or reorder your functions.

  3. If you selected the Existing Class option on the wizard's first page, 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)

  4. The Create Function Aliases checkbox is selected by default. When selected, the wizard generates a configuration file named customFunctions.conf (or edits an existing file of that name), and adds a customFunctions object that defines an alias for your new function. Clear the check box if you do not want aliases created for your functions.

  5. Click Next. In the Create StreamBase Custom Function Aliases page:

    1. Choose the projects in which to create your aliases. The list of projects is limited to those on the Java Build Path of the project where your function's class is to be created.

    2. The Aliases grid shows the currently defined functions and the alias names that will be created. Click in the Alias column to change an alias name.

    3. Click Finish.

  6. When you are done, click Finish.

Defining Aggregate Functions

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.

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 in which to create your aliases.

    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.example.sbapps.functions;

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