Library Articles

Authors: Eddie Galvez, John Smart
StreamBase Systems

Article Updated: 04-April-2007
Toolkit Updated: 10-May-2007 — see Change History

• Introduction
• Eclipse Setup
• Online Assistance
• Checking for Updates in Eclipse
• Switching APIs (Optional)
• Change History
• Related Topics

This article explains how to set up the StreamBase Java Toolkit for Eclipse 3.2 and higher.

The toolkit is designed to accelerate your development work, saving you valuable time as you learn the StreamBase API. After you complete the Eclipse set-up steps described in this article, StreamBase wizards will walk you through the creation process. The results are .java templates for StreamBase clients, embedded adapters, operators, and functions. You can then replace the " // TODO " sections in the source files to implement your specific code, all within the Eclipse IDE. A manifest file generator is also provided to assist when packaging operators and adapters for use in StreamBase Studio and for deployment.

StreamBase Java Toolkit for Eclipse: The current version of the toolkit is 3.7.2.

StreamBase APIs: The current toolkit is compatible with the StreamBase 3.7.x and 3.5.x Java APIs.

Eclipse requirements:

If you are new to StreamBase, here are a few quick definitions. StreamBase clients interact with a running server process that is hosting a StreamBase application, enqueuing data to the application's input streams, or dequeuing processed results by subscribing to output streams. Custom embedded adapters can be used to enqueue/dequeue data to or from a StreamBase application, within the same server process. Custom operators and functions can be used within a StreamBase application to apply business logic to the "in-flight" streaming data. Details about these API components are provided in the StreamBase API Guide and related documents.

Follow these steps in Eclipse 3.2.x. The instructions assume that your machine has an Internet connection. If you have never used Eclipse but are interested in this IDE, find out more at eclipse.org .

1. From the top menu, select "Help > Software Updates > Find and Install..."
2. Enable the option to "Search for new features to install" and click Next.
3. On the "Update Sites to Visit" page, click the "New Remote Site..." button.
4. On the "New Update Site" page, enter a name such as "StreamBase Update Site," and enter the following update-site URL: http://www.streambase.com/eclipse/update-site
   

   Note: Do not go to the URL in a browser; instead, specify it on the Eclipse page. For example:

   

   Click OK, and then click Finish.

5. On the "Search Results" page, check the StreamBase Java Toolkit, or the name you provided in the Name field of the prior dialog. For example:

   

   Then click Next.

6. On the "Feature License" page, if you agree, accept the license agreement and click Next.
7. On the "Installation" page, accept the default installation target directory or specify a different location.

   Windows

   

   Note: One reason to choose a different location is if you do not have privileges to write to the directory where Eclipse is installed, because this will cause the installation to fail in the next step. The next screen shows an Install screen on Linux, where Eclipse is frequently installed in a restricted system directory:

   Linux

   

   You can avoid this problem by installing the toolkit in a location that you are allowed to write to, such as your home directory:

   1. Click the Change Location .
   2. In the New Update Site dialog (shown next), click the Add Location button and navigate to your home directory. Eclipse adds the location you select, with an eclipse subdirectory appended. Click OK ; you should see the changed install location in the Install dialog.

      

   3. Click Finish .
8. Eclipse presents information that the feature has not been digitally signed. If okay, click Install.
9. Click the command button to restart Eclipse; Eclipse will restart automatically.

   At this point, the StreamBase Java Toolkit has been downloaded and installed automatically by Eclipse.

10. In the Eclipse Package Explorer, create a new Java project (unless you already have an existing one that can be used by the StreamBase wizards in subsequent steps).
11. Use the StreamBase Java Toolkit wizards to create templates for clients, embedded adapters, operators, and functions. From Eclipse's top menu, choose:

    "File > New > Other..."

    On the list, expand the "+StreamBase" folder to display the available types. For example:

    

12. When you click Next, the StreamBase wizard page may display a message that the "StreamBase Client API is not on the build path..." of your project. For example, see the warning icon on this page:

    

    To resolve this, click the "Click here" link. On the "Java Build Path" page, expand the StreamBase Client API entry and select the clientapi.jar that was installed along with the StreamBase Java Toolkit. For example:

    

    Once clientapi.jar is on the build path for your Java project, you will not need to set it up again for other StreamBase wizards that are run in this project.

    Click OK. Eclipse returns you to the StreamBase wizard page.

13. If you are generating a template for a new StreamBase Java client or custom embedded adapter, also notice that there is a Target field on the initial wizard dialog. You must choose between the StreamBase 3.7 or 3.5 API. Because there are differences in those APIs, the StreamBase Java Toolkit (as of 3.7) provides both and lets you select the one you need. Make your selection based on the version of StreamBase that this client or adapter will use. The dialog will preselect the Target value with the version of the StreamBase Client API found in your current project build path, or 3.7 if none is yet set.
14. After adding clientapi.jar to your Java project's build path, and after setting the API version (for clients and adapters only), you can complete the dialog. For example:

    

15. Complete the wizard pages and click Finish on the last page to generate a .java template in the Eclipse Java editor. Here's a sample screen of generated code in the editor:

    

That concludes the set-up procedure.

If you need help while using the wizards, click into any of the page's text fields and then press F1 (or Ctrl+F1 on Linux) or click the Help icon in the lower-left corner of the current wizard's page. For example, after clicking that icon on the New StreamBase Client wizard, it displays context-sensitive Help in a new, right-side pane:

Notice that near the bottom of each Help pane there are links to topics in "Using the StreamBase Java Toolkit," which is installed with the toolkit.

Also read the Java topics in the StreamBase API Guide, and refer to the StreamBase API Javadoc that is installed with the full StreamBase product. (The Javadoc link here opens in a new browser window.)

In the "Using the StreamBase Java Toolkit" document, see the topic that explains how you can attach the StreamBase API Javadoc to your Eclipse project.

In addition, here are pointers to specific API Guide topics in the StreamBase documentation. This guide is installed with the full StreamBase kit, and is also available here in the Developer Zone. The following API Guide topics open in a new browser window:

• Creating Java Clients
• Using the Embedded Adapter API
• Using the Java Operator API
• Creating Custom Java Functions

If you need further assistance, please contact us .

  Checking for Updates in Eclipse

Now that you have the StreamBase Java Toolkit installed in your Eclipse project, getting updates is easy. Follow these steps, which again assume that your machine has an Internet connection.

There are a few ways to get updates. Here's option #1:

1. First check that your Eclipse preferences are set so that it can distinguish between updates in 3. 5 .x and 3. 7 .x. From the Eclipse top menu, select Window > Preferences...
2. In the left pane, click Install/Update. Set the Valid Updates option to "compatible". For example:

   

   Click OK.

3. From the Eclipse top menu, now select "Help > Software Updates > Find and Install..."
4. Enable the option to "Search for updates of the currently installed features" and click Finish.
5. The Eclipse Update Manager will search for updates on the StreamBase Update Site.
6. If Eclipse finds that the StreamBase Update Site has a more recent version of the StreamBase Java Toolkit, it will list an entry for it.
7. Select the items you want, click Next, accept the license agreement, then click Finish to install the update(s). You should restart Eclipse before using the updated StreamBase Java Toolkit.

Here is an alternative way to check for updates, without having to change the Install/Update preference from the (default) of "equivalent", to "compatible":

1. From the top menu, select "Help > Software Updates > Find and Install..."
2. This is a bit counter-intuitive, but enable the option to "Search for new features to install" and click Next.
3. On the "Update Sites to Visit" page, select your existing entry from the list, such as "StreamBase Update Site". For example:

   

4. Click Finish.
5. The Eclipse Update Manager will search for updates on the StreamBase Update Site.
6. If Eclipse finds that the StreamBase Update Site has a more recent version of the StreamBase Java Toolkit, it will list an entry for it.
7. Select the items you want, click Next, accept the license agreement, then click Finish to install the update(s). You should restart Eclipse before using the updated StreamBase Java Toolkit.

Switching APIs (Optional) After installing the 3.7 toolkit, you can switch between the 3.7 and 3.5 APIs (if needed) for clients/adapters only. For instance, assume that you already added the 3.7 clientapi.jar on your project's path, and you now need to generate a 3.5 template. Follow these steps - we'll start from the New StreamBase Client page, as an example:

1. On the New StreamBase Client page, toggle the API Target selection from 3.7 to 3.5.
2. The page displays a warning message. For example:

   

3. Click the "Click here" link.
4. On the "Properties for <your-java-project>" page, highlight the StreamBase Client API entry.
5. Click the Edit... button.
6. On the Edit Library page, use the pull-down menu to select the desired API version. In this example, we are selecting 3.5:

   

7. Click Finish to return to the wizard page for the new client/adapter.

Remember that when you switch the API to a different version, such as from 3.7 to 3.5, the client/adapter must connect to a running StreamBase Server process that matches the version.

The table shows the change history of the StreamBase Java Toolkit for Eclipse, with the most recent release listed first.