sburi

StreamBase URI format — Describes the StreamBase URI format and its shortcut forms.

SYNOPSIS

sburi

DESCRIPTION

A StreamBase URI references an instance of StreamBase Server, or references containers running on the server. Most StreamBase command line utilities address their target server with the –u option, which takes a StreamBase URI. You might also use StreamBase URIs in code, when programming StreamBase client applications.

The format of the StreamBase URI is:

sb://[host][:port][/container][;user=xxx;password=yyy]

The following example uses the StreamBase defaults for host, port, and container:

sb://localhost:10000/default;user=sbuser;password=secret

The following example addresses a container named holdingcell running on a remote server that does not require authentication:

sb://streamhost:9900/holdingcell

When using the –u option to specify a URI for a StreamBase command line utility, a space between the –u and the URI is optional. Exception: When used with the sburi, jsbadmin, jsbc, and jsbclientgen commands, you cannot have a space after the –u (or –p). Thus, the following commands are all in correct form, and produce the same results:

sbc -u sb://localhost:9900/ha list
sbc  -usb://localhost:9900/ha list
jsbc -usb://localhost:9900/ha list

If you have a non-default URI you use often, you can set it in the STREAMBASE_SERVER environment variable in lieu of typing it every time on the command line. See the Environment section below.

Authentication Parameters

The user and password parameters are only necessary if you are communicating with a StreamBase Server instance that has StreamBase authentication enabled. For example:

sb://streamhost:9900/holdingcell;user=rose;password=nuh-UH

When specifying authentication parameters at the UNIX shell prompt, enclose the URI in quotes to escape the shell's interpretation of the semicolon:

"sb://streamhost:9900/holdingcell;user=rose;password=nuh-UH"

URI Shortcuts

StreamBase URIs recognize defaults, which lets you enter a shortcut URI in many cases. Any unspecified portion of the URI defaults to the following:

The default host is localhost.
The default port is 10000.
The default container is named default.
An empty container string selects the default container.
The default authentication parameters are none. This means that, by default, the server is presumed to not require authentication.

Using the sbc list command for illustration, all of the following commands produce the same results for a server with all default settings:

sbc list
sbc -u sb://localhost list
sbc -u sb://localhost:10000 list
sbc -u sb://localhost:10000/ list
sbc -u sb://localhost:10000/default list
sbc -u :10000 list
sbc -u :10000/default list
sbc -u /default list
sbc -u / list

The following examples illustrate various combinations of default and non-default URI sections:

sbc -u :9900 list        (localhost, port 9900, default container)
sbc -u :9999/ha list     (localhost, port 9999, container named ha)
sbc -u /crosseng list    (localhost, port 10000, container named crosseng)

The following examples show several commands to access a remote server running on the default port, 10000. These commands all produce the same results:

sbc -u sb://streamhost:10000/default list
sbc -u sb://streamhost:10000 list
sbc -u sb://streamhost/default list
sbc -u sb://streamhost list

When using authentication parameters, at least one portion of the URI must be present. That is, you cannot specify only the authentication parameters by themselves, relying on all the URI defaults described above. You can, however, rely on partial defaulting when using authentication. For example:

sbc -u :10000;user=rose;password=nuh-UH      (Windows)
sbc -u ":10000;user=rose;password=nuh-UH"    (UNIX)
sbc -u /default;user=rose;password=nuh-UH    (Windows)
sbc -u "/default;user=rose;password=nuh-UH"  (UNIX)
sbc -u /;user=rose;password=nuh-UH           (Windows)
sbc -u "/;user=rose;password=nuh-UH"         (UNIX)

Most StreamBase utilities recognize the –p option in addition to –u. Use –p to specify only the port number, defaulting to host=localhost and the default container. The –p option is not supported for StreamBase applications that have authentication enabled or are using High Availability features. The following commands are equivalent:

sbc -p 9900 list
sbc -u :9900 list
sbc -u sb://localhost:9900 list

Multiple URI Syntax for HA Scenarios

Certain commands that accept StreamBase URIs can also accept a comma-separated list of URIs to address more than one StreamBase Server at the same time. The following example requests status information from two local server instances, one running on port 9900, the other on port 9901:

sbc -u sb://localhost:9900,sb://localhost:9901 status --verbose

You can address multiple servers running on separate hosts. The following example assumes that two server instances both have identical containers named app2 in which the running application has an input stream named InputStream3:

sbc -u sb://primary.example.com:10000,sb://secondary.example.com:10000 enqueue app2.InputStream3

The same command as above, using defaults for the port number:

sbc -u sb://primary.example.com,sb://secondary.example.com enqueue app2.InputStream3

You can use the URI shortcuts described above to specify multiple URIs. For example, to check the status of four server instances running on different ports on localhost, use a command like the following:

sbc -u :9900,:10000,:10099,:11000 status

In general, the multiple URI syntax is accepted by programs based on the StreamBaseClient API, including sbc, sbfeedsim, and any client applications you write. By contrast, programs based on the StreamBaseAdminClient API, including sbadmin, are expected to address a single server at a time for administration purposes, and do not accept the multiple URI syntax. For example, you can issue an sbadmin shutdown command only to one server at a time.

The STREAMBASE_SERVER environment variable supports a list of multiple URIs. When writing client code, use the StreamBaseURI.listFromEnvironment class instead of StreamBaseURI.fromEnvironment to make sure your code supports this feature.

ENVIRONMENT

STREAMBASE_SERVER: Optional. Contains the URI for a StreamBase Server instance, or a comma-separated list of server URIs. Use this variable to set a default StreamBase URI for StreamBase commands that take the –u option. If set, commands use the URI in this variable, overriding their built-in default URI, which is sb://localhost:10000. If this variable is set, you must use the –u option to communicate with any server other than the one specified in this variable.