How to Submit to the StreamBase Component Exchange

Last updated:
3:38pm Jun 12, 2020

Overview

The StreamBase Component Exchange contains open-source components that are compatible with TIBCO StreamBase® and that have been created by StreamBase® users and team members.  The open-source components are available under separate software license terms and are not part of the StreamBase product. As such, they are not covered by the terms of any agreement with TIBCO for the StreamBase product, including any terms concerning support, maintenance, warranties, and indemnities. Download and use of these components is solely at your own discretion and subject to the open-source license terms applicable to them.

Read on if you have a component you would like to contribute.

There is a designated operations manager for submitted components.  That individual performs the steps below, but will need cooperation from you, the contributor.

Third Party Software

If your project is based on open source projects or libraries, you must be cognizant to how those projects are licensed. Components you submit to the Exchange must be licensed under a three-clause BSD or similar open source license. Components licensed under any version of the GNU General Public License (GPL) will not be accepted for distribution from the Exchange.  If your component requires a TPS library licensed under GPL, you can still submit your component; however, the instructions for use must include directives for the end user to obtain the TPS and configure it such that the component has access to it.

Any use or inclusion of third-party software components must include a statement of the license terms concerning that software and the use of such software respect the license terms of those components. If your third-party component license requires the inclusion of the text of a license file, include that file at your project's root, named in such a way that its contents are known without opening the file.  For example: ExcellentAPI_license.txt.

We greatly prefer that third-party software not be included in component submissions, but rather if used be referred to by the submission. In particular, for components to be used with TIBCO Streaming products (such as StreamBase, Live Datamart, or Spotfire Data Streams) of version 10 or higher, please use Maven dependencies rather including third-party artifacts in component submissions.

All contributions must be scanned for third party software (TPS).  If any TPS is included, then for each TPS the contributor will have to work with the operations manager to answer these questions:

  1. Is the TPS free, paid, or a TIBCO component
  2. Does this TPS contain encryption or hooks to encryption
  3. Are we entitled to technical support?
  4. Support Provider:
  5. Are we required to pay fees or royalties for the software?
  6. Is the code provided to us in source or machine readable format only?
  7. Do we modify the TPS in any way?
  8. Do we bundle the TPS or embed it into the offering 

Before uploading your component submission, be sure to review your project for the use of any third-party or proprietary contents, including those used as field names, expression constants, file names, and the project name itself.

Contributor Agreement

For any Component contribution received from a non-TIBCO employee, the contributor must complete and execute the TIBCO Contributor License Agreement.   Once a completed Agreement is received from the contributor, the operations manager will send a PDF copy of the executed Agreement to TIBCO Legal Department – IP Team.  Please download the form (it is fillable), rename it to have your name in place of "signable" and return via email to sbase-jira-sbx@tibco.com.  We encourage you to email the agreement separately from the component itself.

Component Submission Process

To submit a Component Exchange project for consideration

  • Create an archive file in zip or gzip format from your complete, runnable StreamBase Studio project folder. Follow the instructions in StreamBase documentation for guidance on exporting your project as an archive file.
    • Be sure to exclude compiled or deployable artifacts from your source archive; for example classes or target directories should not be included in a component exchange submission.
  • Attach your archived project folder to email you send to sbase-jira-sbx@tibco.com.
    • If the archive can't be attached to the email for email security reasons, then put the archive file in online file sharing facility such as GDrive or DropBox, and
      • include the URL of the archive in the body of the email
      • Make sure that the archive file is permissioned so that the operations manager can read the file
  • Include your proposed Component name in the subject line of your email
  • In the body of your email, provide a short description of your project. You can reuse the first paragraph of your README.txt, described below, as the project description.

Component Structure

Project Naming and Numbering

Name your Studio project folder so that other users will recognize your project's general subject matter.

During a component's initial submission phase, there is no need to keep track of version numbers. When first published on the Component Exchange, new components receive the version number you specify in the metadata.xml file. StreamBase recommends that projects begin with version 1.0 and increment for any change.

If you are submitting a revision of a published component, include your proposed revision number in the subject line of your email.

Required Contents of Project Folder

Your component's zip file submission must contain the following metadata files at the root of your project folder (in addition to the files and folders of your project itself):

  • An XML file named metadata.xml, described below.
  • A text file named README.txt, described below.

If you are submitting Java code as a TIBCO employee or contractor, use a package name beginning with com.tibco.streambase.contrib. Otherwise, submit Java code with any appropriate package name. Do not submit Java code that uses the default package.

The metadata.xml File

A master, or top level metadata.xml file is created from all available components.  It provides a description of each project in the Component Exchange. The contents of your component's metadata.xml file end up as the description for your project in the Component Exchange dialog in StreamBase Studio and on the public StreamBase Component Exchange page.

An example metadata.xml file is provided at the bottom of this page. The metadata.xml file conforms to a simple DTD. If you are using an XML-aware editor, you can download the DTD (componentmetadata.zip). As an alternative, you can download two or three components from the Exchange and examine their metadata.xml files to get a feel for the required structure.

The metadata.xml file begins with the following lines:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE metadata SYSTEM "componentmetadata.dtd">

The next line is one long unwrapped line, containing a single element, <component>, with the following attributes and quoted values for each:

Attribute

Value

author

Provide a human name or company name with optional parenthesized email address for the author attribution you want to display for your project.

version

The version number of this project. The suggested initial version number is 1.0, incremented with each submitted change.

sbversion

The StreamBase release number you used to develop your project. Specify the release to the third digit if you are using features found only in that release or later. Otherwise provide a major.minor release number, such as 7.0 or 7.1.

blurb

A single short sentence that summarizes and describes your component.

title

A short public name for your project.

The final portion of the <component> element is a text description of your project, placed between the quote character that ends the title attribute and the closing </component> tag. This must be one long, unwrapped line with unquoted text. It should be no longer than about 500 characters, and should be a simple text paragraph that does not attempt formatting such as bulleted or numbered lists. The description text has no line breaks and no hard tabs.

Think of the description text in the <component> element as advertising. Do not tell how to use the component, only tell what it does and what problems it solves. You can re-use the first paragraph of your README.txt as the description.

Exception: if your component has prerequisites (such as other components in the Exchange or third-party software), list them on the first line of the description preceded by Requires: and followed by a line break.

Optional extended attributes.  Starting in version 7.6.5 of StreamBase, the following attributes are available but not required, within an <extended-attributes> tag:

Attribute

Value

componentid a unique id for this component. Suggest use of maven/java style reverse domain ids. Examples: com.tibco.ep.sb.YourComponentName
depends-on the componentid of another component(s) upon which this component depends. If there is more than one dependency, list space separated.
tags list of no space allowed strings, may be used for searches and user interface filtering.

An example of a metadata.xml with the extended-attributes tag is below.  The use case is exemplified in the FX Trading components.  Each FX component relies on one common component.  That common component exists as a free standing entity and each FX component names it in the metatdata via a depends-on tag.  Within a 7.6.5 or later version of Studio, if pulling in a component with a "depends-on" tag, the dependent component(s) will be attempted to be found and brought into studio along with the selected component.

The README.TXT File

The README.txt file provides primary documentation to your component's users. An example README.txt file is provided at the bottom of this page.

The file should be line-wrapped at 79 characters, must have Windows (CR+LF) line endings, and must be named README.txt. Do not store hard tabs in the file; instead set your editor such that the tab key inserts a small number of spaces instead of a tab character.

Use the first paragraph as a summary of your project. You can reuse a well-worded first paragraph in several ways for your project submission, as described above. Do not try to provide any detail in the first paragraph. Hit only the highlights and strong points as if you are making a sales pitch in 30 seconds.

The rest of the README.txt is free-form, but should pose and answer the following questions:

  • Who is the audience? Who will want to use this component?
  • What exactly will it do for me? What problems does it solve, or what EventFlow roadblock does it overcome? (Write this from the point of view of someone considering downloading your project, not from your point of view as author.)
  • What prerequisites are there, if any?
  • What third-party libraries are required, and exactly where do I go to download them?
  • What EventFlow files are included, and how are they related? What is the top level module to run first?
  • What is the meaning of each parameter, argument, or variable?
  • What non-obvious steps are necessary, if any, to run the provided sample?
  • Optionally, for those with an interest in the underpinnings, what are the technical aspects of this component?

The most successful README.txt files follow standard technical writing rules such as those found in the Fedora Docs Project Style GuideEclipse Doc Style Guide, or many others.

Java Source Code Character Encoding

All .java files in submitted components must have UTF-8 character encoding.

Example metadata.xml File

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE metadata SYSTEM "componentmetadata.dtd" >

<component version="1.2" blurb="Performs calculus operations in Python." sbversion="6.4" author="Adam Diamant (adiamant@tibco.com)" title="Calling Python from StreamBase">

Requires: Python; the NumPy Python library; C compiler to build NumPy

The purpose of this module is to call a process external to StreamBase to handle certain calculations. The module demonstrates calling a Python script that loads the NumPy math library to perform either integration or differentiation of a polynomial. To use this module, you must have a supported version of Python, as described in the API Guide in the StreamBase documentation, and you must obtain and install the NumPy library from http://numpy.scipy.org.

 

</component>

Example README.txt File with dependencies (available after 7.6.5)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE metadata SYSTEM "componentmetadata.dtd" >

<component version="1.0" blurb="UBS Investment Bank Trading Components handlers" sbversion="7.6" author="SBX (sbase-sbx@tibco.com)" title="Trading Components UBS Investment Bank" >

   The UBS Investment Bank trading components handlers simplifies the creation of foreign exchange trading applications by providing a set of EventFlow modules and schemas that include market data handlers and execution handlers. The framework's packaged modules, parameterized properties, and consistent interfaces simplify many of the complexities normally associated with creating FX trading applications

<extended-attributes

componentid="com.tibco.ep.sb.tradingcomponent.ubs" depends-on="com.tibco.ep.sb.tradingcomponent.common" tags="tradingcomponent.executionhandler tradingcomponent.marketdatahandler" />

</component>

 

Example README.txt File

The Python library numpy is an excellent programming tool for scientific and

mathematical computing. In this simple example, we call a Python script from

StreamBase that imports the numpy library in order to perform either

integration or differentiation on a polynomial.

 

Input Stream:

    Integrate    - A boolean variable where "true" represents integrate and

                  "false" represents differentiate.

    Coefficients - A list of polynomial coefficients that start at the term

                   with the highest power and end with the constant term.

 

The tuple is then sent to the the Python module where the desired Calculus

operation is performed. Notice that there are two output streams. The

StreamBase output stream returns a timestamp (representing the time before

processing) and a summary of what was input. The Python output stream returns

the output from the Python function, the time of completion and the approximate

time it took to run the external process.

 

If everything runs smoothly, a list representing the Calculus operation

performed is in the Output field of the output tuple. If an error occurs while

running the external process operator, an error message is placed in the Error

field of the output tuple.

 

This example depends on numpy, which you must obtain and build independently.

Download the numpy package from http://numpy.scipy.org/, and follow the

instructions in the INSTALL.txt and README.txt files at the top level of

the distribution archive. Building and installing numpy requires a supported

C compiler. Make sure numpy is installed as a Python library on your system and

that it is locatable by the Python "import numpy" line. For Windows, StreamBase

supports Python 2.6 from ActiveState or Python.org, as described in the API Guide

in the StreamBase documentation.

 

In the EventFlow application, there is an External Process operator named

CallPython. One of the command arguments for this operator is the path to

the external Python file to execute, Calculus.py. As installed from the

StreamBase Component Exchange, this file is placed in the Extras directory of

the Studio workspace for the SB_Python project. Thus if you installed this

project from the StreamBase Component Exchange, change the second argument in

the Command Arguments tab of the CallPython operator to the following, with double

quotes:

    "Extras\\Calculus.py"

Since the current working directory of the PythonProcess.sbapp application is

the project workspace, the Extras directory is found with a relative path.

If one wishes to run a python script from a different directory, then one must

instead provide the full path to this file.

 

Version History

    1.1 - Updated paths and deleted variables in parameters tab

By downloading a component, you agree to the terms and conditions of the StreamBase Component Exchange, which are available for review TIBCO Component Exchange License.