How to Submit to the 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.
Attach your archived project folder to email you send to sbx-submit@streambase.com. Include your proposed Component name in the subject line of your email, and 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.
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 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 from this link. 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.
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.
Using Third-Party Software
Before uploading your component submission, be sure to scrub your project of any proprietary or company-specific names used as field names, expression constants, file names, and the project name itself.
If you are submitting Java code as a StreamBase employee or contractor, use a package name beginning with com.streambase.contrib. If you are a StreamBase customer or a student, submit Java code with any appropriate package name. Avoid the Java default package.
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) cannot be accepted for distribution from the Exchange. Any use or inclusion of third-party software components must 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.
Example metadata.xml File
(Display here requires Firefox, Chrome, or IE 9. Users of IE 7 or IE 8, please download any sample from the Component Exchange and inspect its metadata.xml file in a text editor.)
Example README.txt File
By downloading a component, you agree to the terms and conditions of the SBX, which are available for review here.
