StreamBase Path Notation

< Previous		Next >

StreamBase Path Introduction

StreamBase's formal path notation is designed to avoid naming conflicts when you run multiple EventFlow or LiveView modules in the same fragment in different StreamBase containers. The notation also allows you to avoid conflicts when operators are run in separate parallel regions.

Use StreamBase path notation to address individual StreamBase containers, streams, or operators when using certain epadmin commands or when using the legacy sbadmin and sbc commands. For example, the following commands show information about the default.BestAsks stream in a running instance of the Best Bids and Asks sample:

epadmin --ad=adminport --path default.BestAsks --detailed
sbc describe default.BestAsks

For both commands, if the container is default, it does not have to be stated:

epadmin --ad=adminport --path BestAsks --detailed
sbc describe BestAsks

Path notation is used when configuring StreamBase container connections in a StreamBaseEngine configuration file.

In addition, StreamBase path notation can be seen in the output of many epadmin display commands in the Path = line, and in the StreamBase Manager Operators and Queues Views.

StreamBase Path Syntax

StreamBase path notation has the following syntax, with a period separator between each element:

[containerName.][moduleRefName[[.moduleRef2Name].[..]]entityName

containerName

The name of the StreamBase container hosting the application. Container names are either system, default, or a name you assign when creating a container. The following examples address two operators with the same name in separate containers:

container1.ReadOrders
default.ReadOrders

When containerName is omitted, the StreamBase container named default is assumed. Every EventFlow fragment has a default container named default, which contains the application's top-level module unless you explicitly create a non-default container. This means you can often omit the containerName portion of the address. For example, the following commands are equivalent when the server is running the Best Bids and Asks sample in the default StreamBase container:

epadmin --ad=adminport enqueue stream --path default.NYSE_Feed
epadmin --ad=adminport enqueue stream --path NYSE_Feed
sbc -p sbport enqueue default.NYSE_Feed
sbc -p sbport enqueue NYSE_Feed

Use the containerName portion of the address when you are addressing a non-default container, or when a name conflict would otherwise occur.

moduleRefName

The name of a module that is either referenced explicitly in the fragment, or referenced implicitly by StreamBase. Implicit references occur when a component runs in separate or multiple parallel regions. In this case, StreamBase automatically creates a module for each running instance. There can be multiple moduleRefName levels in the address syntax.

The following line addresses an operator named SumOrders within a module reference named MWindowModuleRef1:

MWindowModuleRef1.SumOrders

The next example addresses a group of entities associated with an operator that you have configured, using the Concurrency tab of the operator's Properties view, to run in a parallel region. In each entity, the prefix references the module that StreamBase creates for the operator's parallel region.

MyOperator.InputStream1              (input stream)
MyOperator.out:MyOperator_1          (output stream)
MyOperator.schema:RetrieveLastOrders (schema)
MyOperator.MyOperator                (operator)

Finally, If you set a component to run in multiple parallel regions, you can address each region separately. The following example addresses two instances for the same operator, each running in its own parallel region.

default.Filter:0.Filter
default.Filter:1.Filter

entityName

The name of an individual stream, operator, schema, or queue.

In StreamBase Manager, you might also see a parallel region instance number appended to the entityName in the form entityName[:instanceNumber], using zero-based instance numbers. For example: Update_Bids_and_Asks:0, Update_Bids_and_Asks:1, and so on.

Top-level Module Name Not in the Path

The container name is an alias for the top-level EventFlow module name. Top-level module names are never included in a path.

Other than the top-level container name, all path elements must be specified from the most significant element to the least significant element. It is illegal to omit more significant elements. For example:

//
//  Fully scoped path to myOperator
//
default.childModule.grandChildModule.myOperator

//
//  Illegal path specifier for myOperator
//
grandChildModule.myOperator

//
//  Legal path specifier for myOperator
//
childModule.grandChildModule.myOperator

Scoped Names and Resource Resolution

Module and interface scoped names consist of an optional package name, followed by an identifier:

scoped-name = [<package-name>.]<identifier>

A <package-name>consists of a list of identifiers separated by a dot:

package-name = <identifier>[.<identifier>]*

Examples of valid scoped names are:

MyModule
com.tibco.ep.sb.MyModule

There is explicitly no visibility implied by the scope of a name. All modules and interfaces are globally visible.

The file that contains the implementation of the referenced module or interface is resolved by appending a suffix to the scoped name. The supported suffixes are:

.sbapp
.ssql (For internal use only in Streaming 10 and later)
.sbint

Resource resolution for modules and interfaces uses the same conventions as Java, each dot in the scoped name is converted to a directory. For example a scoped name of a.b.MyModule would require the module or interface file in <search-root>/a/b/MyModule.sbapp, <search-root>/a/b/MyModule.ssql, or <search-root>/a/b/MyModule.sbint to be successfully resolved.

The use of multiple suffixes can cause ambiguity during resource resolution. When ambiguity is detected, a resource not found failure is reported that contains the scoped name and all file names with the same base identifier.

For example using a scoped name of a.b.MyModule, resource resolution would fail if these files were on the file system:

    //
    //  Ambiguous
    //
    <search-root>/a/b/MyModule.sbapp
    <search-root>/a/b/MyModule.sbint

Ambiguous resource resolution requires pre-Streaming 10 projects to be changed to resolve the ambiguity.