Contents
Java operators and embedded adapters can be managed using the sbadmin client. There are two aspects to managing Java operators and embedded adapters: managing their lifecycle, and managing their properties.
Java operators and embedded adapters are distinct entities in StreamBase. Each is managed using sbadmin in the same way without fail, however. During this discussion, the phrase [Java operators] is typically used, but everything said about Java operators applies equally to embedded adapters.
Both the lifecycle and properties of a Java operator can be managed using sbadmin. Each of these is discussed separately below. Keep in mind, though, that these sbadmin commands might typically be used together to accomplish a task. As an example, a Java operator might be shut down, then one of its properties changed, and then restarted. In this way the behavior of the operator can be changed without stopping and restarting the StreamBase application.
In general, Java operators undergo the same life cycle events as the StreamBase application that contains them. When the application starts, its Java operators start. When the application suspends or resumes, its Java operators also suspend and resume. And when a StreamBase application shuts down, its Java operators shut down.
In addition to this kind of life cycle management, the life cycle of an individual Java operator can be managed separately from the application that contains it. So, for example, an embedded input adapter could be suspended while the application around it continues to run. This would effectively shut off input from that individual adapter while the application continues processing.
A custom operator or embedded adapter will generally call a typecheck method and may do so quite frequently. It is therefore important that the method be as clean and efficient as possible. For more information, see Typecheck Method Considerations.
When discussing the management of Java operators, its helpful to understand how
operators are named. Each Java operator in a StreamBase application has a name.
This name can be specified in Studio, and appears along with the operator in
Studio. Consider a Java operator that was given a name MyJavaOperator in Studio.
This name, which will be referred to as the unqualified name, may not be the full name of the Java Operator, however. The name of a Java operator may be qualified with any combination of a node name, a container name, and module names.
In this case, the qualified name of the Java operator might be something like
MyNode.MyContainer.MyModule.MyJavaOperator.
Also, each Java operator necessarily runs in a container. In order for a Java
operator to be located, its container must be known. However, it may often be the
case that the operator is running in the default container. In this case, the name
of the container may be omitted. The default container is named default. So the operator names default.MyModule.MyJavaOperator and MyModule.MyJavaOperator are equivalent. The operator names
default.MyModule.MyJavaOperator and MyContainer.MyModule.MyJavaOperator are not equivalent, however.
Java operators can also be contained in StreamBase Modules. A StreamBase
application can contain more than one module, each of which might contain a Java
operator with the same name. In this example, the Java operator named MyJavaOperator is contained in a module named MyModule. There might also be a Java operator named AnotherModule.MyJavaOperator in the same StreamBase application,
but these operators are not the same.
In StreamBase, modules can be nested, so that a Java operator might have a name
like ParentModule.ChildModule.MyJavaOperator.
The command sbc status --operators, described next, prints the qualified names of the Java operators in a StreamBase application. If you are in doubt, you can determine the qualified names of Java operators in an application by using the status command.
The sbc subcommand, sbc status returns status information about the StreamBase Server. This command has been extended so that it can also return the status of any Java operators contained within the StreamBase application.
The command sbc status --operators returns the status of any Java operators contained by the server's application. Note that this command is disjoint from the sbc status command, meaning that sbc status returns information about the server only and not any operators contained in the server. Similarly, sbc status --operators returns information about contained Java operators only, and not any information about the server itself.
In this context, the status of a Java operator consists only of its current state,
or where it is in its life cycle. The possible states include NONE, STARTED, SUSPENDED_AND_DROPPING_TUPLES, SUSPENDED_AND_PROCESSING_TUPLES and SHUTDOWN. These states are discussed further below.
During its lifetime, a StreamBase application undergoes life cycle changes. This means that the application is started and then eventually shuts down. However, an application can also be suspended and resumed any of times before it is shut down.
By default, a Java operator will undergo the same life cycle changes as the
StreamBase application that contains it. Additionally, however, a Java operator can
be suspended and resumed independently of its application. Also, a Java operator
can be shut down and then restarted independently of its application. Finally, it
is possibly for Java operators to be left in a NONE,
or unstarted state when the StreamBase application starts up. Each of these state
changes is described below.
By default, a Java operator starts along with the StreamBase application that
contains it. In Studio, in the General tab for Java operators, there is a
checkbox labeled Start with application. By
default, this box is checked, meaning that the Java operator will start with the
application. Deselecting this box will cause the given adapter to be left in the
NONE state when the application starts.
A Java operator that does not start with its application will stay in the
NONE state until it is explicitly started with the
sbadmin resume operatorName command. Such an
adapter will not start even the whole application is resumed. So for example, the
application as a whole may suspend and then resume. This will have no effect on
an operator that has not started with its application.
Executing the command sbadmin suspendOperators
operatorName [...] will
suspend one or more Java operators without suspending the application as a whole.
This command makes sense only if the Java operator, and by implication the
StreamBase application, is already running.
When a Java operator is suspended, it may be that tuples will still arrive at the operator. This could be true of standard Java operators and embedded output adapters, but not embedded input adapters. Its possible to configure the Java operator to handle these tuples in two different ways:
-
A suspended Java operator can choose to drop tuples that are delivered to it.
-
Conversely, the operator can choose to process these tuples.
These two possibilities are represented by static Strings on the class
com.streambase.sb.operator.Operator: SUSPENDED_AND_DROPPING_TUPLES and SUSPENDED_AND_PROCESSING_TUPLES respectively. A Java operator is
configured to either drop or process tuples by calling the method setSuspendBehavior on its instance. setSuspendBehavior takes an int
argument, the value of which must be either SUSPENDED_AND_DROPPING_TUPLES or SUSPENDED_AND_PROCESSING_TUPLES.
Executing the command sbadmin resumeOperators
operatorName ... will
resume one or more Java operators. In order to resume an Operator, the
application containing it needs to be running. In other words, its not sensible
for a Java operator to run if the application containing it is not running.
It is possible to run the commands sbadmin
shutdownOperators operatorName
... and sbadmin
restartOperators operatorName
... . These commands shut down and then restart Java
operators. There are no analogous sbadmin commands that apply to the server as a
whole.
Shutting down and restarting a Java operator is different from suspending and
resuming it. SHUTDOWN is a terminal state; once an
Operator has been shut down nothing more can be done with it. When an operator is
restarted, a new instance of the Operator is created, it is reinitialized, and so
on. In constrast, when an Operator is suspended and resumed, it is not destroyed
and then recreated; rather it stops processing incoming messages.
The shutdown and restart operations might be needed under various circumstances,
for example when a Java operator is misconfigured. In this case, the operator can
be shut down, its configuration changed using sbadmin operatorCommand, and then
restarted. In this case, the operator would be reinstantiated and reinitialized,
meaning that its constructor and its init method would be invoked. If it is
necessary to run the constructor or init method of an Operator, then the operator
needs to be shut down and restarted rather than suspended and resumed.
A Java Operator can register threads using a method registerRunnable on the Operator class. When an Operator has not yet started its
managed threads will also have not yet started. Similarly, when an Operator is
running its managed threads are actively running, and when an Operator is
suspended its managed threads are also suspended.
Its also the case, however, that the state of an Operator's managed threads can effect the state of an Operator as a whole. In particular, if an Operator registers one or more threads, and each of these threads ends execution (by leaving its run method), then the Operator as a whole will be shut down.
A Java operator may have a set of properties. These are available on the operator's Parameters tab in StreamBase Studio. For input and output adapters, these properties are available on the Adapter Settings tab. These properties can be altered in StreamBase Studio, and they will be read when the application is started.
This set of properties can also be accessed through the public programming interface
available on com.streambase.sb.client.StreamBaseAdminClient. Similarly, these
properties can be accessed from the StreamBase provided implementation of this API,
the sbadmin command line client. In all
cases, a property is referred to by its name, which is the same as the name that is
displayed in StreamBase Studio for that property.
sbadmin, or any implementation of
StreamBaseAdminClient, can be used to alter a property
of a Java operator while the StreamBase application that contains it is running. So
the properties of a Java operator can be managed dynamically while the operator runs.
Three distinct operations can be carried out on the properties of a Java operator:
-
Its set of properties, and their current values, can be retrieved.
-
A property can be retrieved individually.
-
A property can be set to a new value.
The method getOperatorProperties(String , on operatorName)StreamBaseAdminClient, returns the set of properties and their
current values. getOperatorProperties returns an
array of Strings, where each String is a name-value pair. The name and the value of
the property are delimited with a colon.
Similarly, there is an sbadmin command
that prints out the set of properties and their values for a Java operator. The
command sbadmin getOperatorProperties operatorName prints the properties
and their values for the given operator.
The method getOperatorProperty(String on operatorName), String propertyName)StreamBaseAdminClient returns the value of the given property on
the given operator. The value is represented as a String.
Similarly, the command sbadmin getOperatorProperty
operatorName propertyName prints the String
representation of the given property.
Lastly, the method setOperatorProperty(String is used to set the given property on
the given operator to the given value. Again, there is an analogous sbadmin command that is used to accomplish the same
task, sbadmin setOperatorProperty operatorName), String propertyName), String value)operatorName propertyName value .
In the StreamBaseAdminClient interface, each
property of a Java operator is represented as a String. Consider also that the
properties of Java operators are restricted to a limited set of types. Each of
these types can be converted easily to and from Strings, so that this does not
prove to be a limitation.
A new value for a property can be set while an operator is running. Typically, a Java operator processes incoming tuples when its processTuple method is invoked. An embedded input adapter might begin processing when it receives a call back or in a loop.
Setting a given property on a Java operator will take effect immediately only if that property is read in the code that processes an incoming tuple or message.
So, essentially, the effect of setting a given property on an operator depends on
how and where that property is accessed. Some properties may 'take effect'
immediately. Others may require that the operator be suspended and resumed before
taking effect. This would be the case if the given property is read, and acted on,
in the suspend and resume callbacks, the methods suspend, suspended,
resume, and resumed. Finally, some properties may take effect only when the
operator has been shutdown and restarted.