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 when specifying container connections, or when programming StreamBase client applications.

Important

For StreamBase clients that communicate over an SSL connection, instead of sb:// use the sbs:// protocol, which requires authentication via certificates.

The format of the StreamBase URI is: 

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

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

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

The simplest version of the default URI is used as a default in StreamBase Studio and for all StreamBase utilities: 

sb://localhost

See URI Shortcuts for a list of the default values assumed if not specified.

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 jsbc and jsbadmin 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"

Remote Container Connection Parameters

When using a StreamBase URI as part of a stream-to-stream container connection string to specify that one side of the container connection is on a remote StreamBase Server, you can optionally specify parameters as part of the remote URI.

For example, you might specify a container connection with the source end of the connection on a remote server, and at the same time specify a reconnection interval of 30 seconds, using a container connection specification like the following: 

boxA.instream1=("sb://remotehost:9900/boxB.outstr4;reconnect-interval=30000")

For more on the parameters usable with remote container connections, see Remote Container Connection Parameters.

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. 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 instream3: 

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

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

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

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. Use this variable to set a default StreamBase URI for certain StreamBase commands that take the -u option. For example, sbc status honors the variable, but sbc list does not. If set, commands use the URI in this variable. If this variable is set, you must use the -u option to communicate with any server other than the one specified in this variable. You can set a comma-separated list of URIs in the variable, and commands such as sbc status returns status for all listed servers. However, sbc list returns information only for the first listed server. See the sburi(5) page in the Reference Guide for more on StreamBase URIs.