Using the StreamBase Java Toolkit to Write a Custom Java Simple Function

You implement a custom Java simple function by writing a Java class that has one, or more, public static methods. The parameters and return value of these methods must be a Java primitive or object type corresponding to a StreamBase type, as summarized in the following table.

A Java class used as the source of a custom simple function must be contained within a package, and once you have written the class you include it in a JAR file that you then make available to the StreamBase application that uses the function. When working within StreamBase Studio, import the JAR file into the Custom Libraries directory under your project. In a deployed application, the location and name of the JAR file are included as an entry in the application's configuration file.

To call a custom simple function, you use the calljava function, providing the full package and class name, the target method, and method parameters as arguments to the invocation.

As an alternative to writing your own class, any public static method of a Java class that is already in the CLASSPATH of the application may be called. Using the java.lang.Math class as an example, the public static int abs (int value) method would be called as illustrated in the following code fragment.

  calljava('java.lang.Math', 'abs', value)

When used in a StreamBase expression, value references an integer tuple field and the calljava function returns a value that is either used further within a StreamBase expression or becomes the value of a tuple field, as illustrated in this reproduction of the Output Settings tab in a Map operator's Properties view.

This article was developed using the StreamBase Java Toolkit for Eclipse, v3.7.2, which supports development of enqueuer and dequeuer clients, custom Java operators, Java functions, and embedded adapters that are compatible with StreamBase 3.5.x or 3.7.x.

Follow these steps to create an Eclipse project in which to build a StreamBase Custom Java Simple Function.

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

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

   In the Add Library, StreamBase Client API Library window, select the version of StreamBase against which this dequeuer client will run and click the Finish command button.

   

   Complete the process by clicking the Finish command button.

   

   If you already have a Java project to which you want to add StreamBase Java client coding, you can add the StreamBase Client Library to the project by right-clicking on the project icon and selecting Build Path > Add Libraries... from the popup menu, which opens the Add Library window. Follow the preceding instructions to add the StreamBase Client Library to your existing project.

   Alternatively, you could right-click on the project icon and select Properties from the popup menu. In the Properties window, select the Java Build Path entry and then the Libraries tab. Click the Add Library... command button and continue as described previously.

Follow these steps to generate starting point code using the StreamBase Java Toolkit.

1. 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 Java Function selection and click the Next command button.

2. In the New StreamBase Java Function, StreamBase Custom Java Function window, check the Simple Function and New Class: controls then enter a package name into the Package: text box and the name of your class into the Name: text box.

   

3. Click the Next command button to move to the New StreamBase Java Function, StreamBase Custom Java Simple Function window.
   

   To add a method to your class, click the Add command button and in the Create StreamBase Simple Function window enter a name and return type for the function.

   If the function requires parameters, select the parameter type from the Select Type: dropdown list and click the Add command button to add the entry to the Argument List: listing; repeat if additional parameters are required. Once a parameter is listed in the Argument List: listing, you can highlight and edit the text in the Name column.

   

   Define two methods with the signatures:

     byte[] toUpper (byte[] clause)
     byte[] toLower (byte[] clause)
   		 

4. Once the method signatures have been defined, click the Next command button to return to the StreamBase Custom Java Simple Function window and then click the Finish command button.

   

   The starting point code is generated.

The starting point code includes the following class declaration and method implementations.

   public class CaseConverter {

     public static byte[] toUpper (byte[] clause) {
       // TODO Implement function here
       return null;
     }
     public static byte[] toLower (byte[] clause) {
       // TODO Implement function here
       return null;
     }
   }
   

You can optionally change the method signatures to use String objects rather than byte[], which makes the coding a little easier.

   package com.training;
   
   public class CaseConverter {

     public static String toUpper (String clause) {
       // TODO Implement function here
       return null;
     }
     public static String toLower (String clause) {
       // TODO Implement function here
       return null;
     }
   }
   

In each method, you need to replace the return null; statement with the desired processing logic. In this example, you can use the String class toUpperCase and toLowerCase methods.

1. For the methods that use primitive types, you could use the following code.
   return new String(clause).toLowerCase().getBytes();
   return new String(clause).toUpperCase().getBytes();

2. For the methods that use object types, you could use the following code.
   return clause.toLowerCase();
   return clause.toUpperCase();

Before you can use your custom function in a StreamBase application, you need to prepare a JAR file that contains the .class file and a generic manifest.

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

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

3. Then click the Next command button twice to move to the JAR Export, JAR Manifest Specification window. Select the Generate the manifest radio button.

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

As described in the Introduction, simply refer to your class (com.training.CaseConverter), the name of the desired method (toUpper or toLower), and the tuple field containing the string you want to convert as the parameters to the calljava function.

Although you can use the calljava function within an EventFlow or StreamSQL application in the same way as any other StreamBase function, there is one complexity when the function returns a string value.

When a custom method returns a string value (either as a String object or byte[]), it is not possible for StreamBase to determine the number of characters in the string from the method signature. However, this value must be known so that the size of the tuple field that will hold the return value can be specified in the schema for the emitted tuple. Therefore, you must specify the size of the return value; the StreamBase function strresize is available for this purpose. Therefore, you must pass the return from the calljava function to the strresize function.

  strresize
  (
    calljava('com.training.CaseConverter', 'toUpper', clause), size
  )

The second argument to strresize is used to set the size of the return string to the original size of the field clause.

• Installation of the StreamBase Java Toolkit for Eclipse is detailed in Getting Started with the StreamBase Java Toolkit for Eclipse.
• A description of using the StreamBase Java Toolkit to write an dequeuer (consumer) client is described in Using the StreamBase Java Toolkit to Write a Dequeuer Client.
• A description of using the StreamBase Java Toolkit to write an enqueuer (producer) client is described in Using the StreamBase Java Toolkit to Write an Enqueuer Client.
• A description of using the StreamBase Java Toolkit to write a Custom Java Operator is described in Using the StreamBase Java Toolkit to Write a Custom Java Operator.
• A description of using the StreamBase Java Toolkit to write a Custom Java Aggregate Function is described in Using the StreamBase Java Toolkit to Write a Custom Java Aggregate Function.

Back to Top ^