Child pages
  • How to Submit to the StreamBase Component Exchange
Skip to end of metadata
Go to start of metadata

How to Submit to the StreamBase Component Exchange

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

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

The metadata.xml file provides a description of each project in the Component Exchange. The contents of the 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:

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:

AttributeValue
componentida unique id for this component. Suggest use of maven/java style reverse domain ids. Examples: com.tibco.ep.sb.YourComponentName
depends-onthe componentid of another component(s) upon which this component depends. If there is more than one dependency, list space separated.
tagslist 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 Guide, Eclipse Doc Style Guide, or many others.

Java Source Code Character Encoding

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

Using Third-Party Software

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.

If your project is based on open source projects or libraries, pay attention 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. 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.

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.

Example metadata.xml File

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

 

Example README.txt File

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.

  • No labels