Contents
Java operators and embedded adapters can be managed using the epadmin 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 epadmin 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 epadmin. Each of these is discussed separately below. Keep in mind, though, that these epadmin 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 designation [ in syntax examples is a reminder that this command requires either the global parameter sn|ad]‑‑servicename or the ‑‑adminport and ‑‑hostname combination to identify the node or cluster of interest.
The command,
epadmin [sn|ad] display operatoras 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 following command.
epadmin [sn|ad] display operator --type=javaThe epadmin command, epadmin [sn|ad] display operator --type=java returns the status of any Java operators contained within the StreamBase application. This command has been extended so that it can also return the status of any Java operators contained within the StreamBase application.
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 epadmin
resume operator 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 epadmin suspend
adapter 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 epadmin resume adapter
... 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 epadmin stop
operator ... and epadmin start
operator ... . These commands shut down and then
restart Java operators. The epadmin engine command is used to control the server.
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 epadmin
operator, 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
epadmin 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.
epadmin 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. This is managed using
get/set operator commands.
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 epadmin get operator command that prints out the
set of properties and their values for a Java operator. The command epadmin display
operator 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 epadmin [sn|ad] get operator --path=operatorPath --property="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 epadmin
command that is used to accomplish the same task, epadmin [sn|ad] set operator
--path=operatorPath --property="propertyName" --value="propertyValue".
operatorName), String propertyName),
String 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.