Contents
The HA FSM sample shows the use of a Finite State Machine (FSM) to deal with state transitions in an HA design pattern. The behavior of the sample is similar to the behavior of the HA Sample, but the implementation of the HA FSM sample is more powerful and complex. Also, unlike the HA sample, leadership status is not based on a setting in the startup script. The server that starts first is designated as the leader, and any server that starts next is the nonleader.
HA FSM is designed to maximize flexibility — it can be extended or modified to handle Hot/Hot, Hot/Warm, and Hot/Cold HA configurations. By default, the sample is configured for a Hot/Warm setup.
HA FSM runs the same simple application, app.ssql, on
each of two StreamBase Server instances. At any given time, one server is
designated as primary, and the other is designated as secondary. The servers
coordinate their behavior to provide high-availability access to the sample
application's output.
As with the HA Sample there are two StreamBase Server instances in a Hot/Warm high-availability cluster. Both servers receive all input and perform all calculations, and application logic is identical on both servers, except that that one of the servers (the server that is not the leader) does not send output downstream. On failure of the leader, the nonleader takes over and begins sending output.
NOTE: The server that starts first is designated as the leader even though one is designated primary and the other is designated secondary. When you run the sample you can run the script that starts the server designated as secondary first to see this behavior.
There are two important applications for handling high availability: one
specifies the HA logic and the other specifies the application logic. These files
are specified in the configuration file for HA FSM (ha-fsm.sbconf) as follows:
<application file="${APPSDIR}/HaController.sbapp" container="ha_custom">
...
<application file="${HA_CONTROL_APP}" container="ha_control_${APP_CONTAINER}">
The first application (HaController.sbapp) is the
monitoring and detection module: it monitors state changes and detects the
failure of the primary server. It runs in the ha_custom container. The HA logic uses a Java operator (defined
in PingOperator.java) to determine the leadership
status of a server.
To modify the behavior of this application you can either change the application
or modify the values in the ha_ftc.fsm.config file.
(This configuration file is read by a CSV File Reader Input adapter as part of
FaultToleranceControllerFsm.sbapp.)
The second application (specified as the value of HA_CONTROL_APP) is the application handler: it specifies the
change in application behavior to occur when there is a change in leadership
status. If the server is not the leader, or if it stops being the leader, this
application causes app.ssql to disable dequeuing.
The common.cmd (common
on UNIX) script sets the value of the HA_CONTROL_APP environment variable as
hacontrolcontainer.sbapp and the value of
APP_CONTAINER as app.
To modify the behavior to meet your particular requirements, modify or replace the applications (and possibly rename their containers).
The top-level application and configuration files delivered with the HA FSM sample are described in the following table.
| File | Description |
|---|---|
app.sql
|
|
HaController.sbapp
|
|
hacontrolcontainer.sbapp
|
|
ha-fsm.sbconf
|
|
sbd.sbconf
|
|
Trace flags in the configuration files allow the use of tracing to explore the workings of the sample in detail.
Additional files in the project support the custom Java operator and the lower level operations of the HA logic.
The scripts delivered with the HA FSM sample are described in the following table.
| Windows script | UNIX script | Purpose |
|---|---|---|
buildhajar.cmd
|
--
|
|
| -- |
hastatus
|
|
startprimary.cmd
|
startprimary
|
|
startsecondary.cmd
|
startsecondary
|
|
startfeedsim.cmd
|
startfeedsim
|
|
startdequeue.cmd
|
startdequeue
|
|
common.cmd
|
common
|
|
StreamBase Studio can run only one server instance at a time, and the HA FSM sample does not make much sense unless both server instances are running. For this reason, you must run the sample in terminal or StreamBase Command Prompt windows.
However, you are encouraged to load each EventFlow application into StreamBase Studio to see how each is assembled.
Note
This sample makes use of environment variables and configuration file global
parameters set with the <operator-parameter>
element of the server configuration file. See Using Global Parameters in the
Authoring Guide for more information.
Global parameters can be used by operators or adapters so that values are not hard-coded in the application. Global parameters that are referenced within an operator must be defined in the configuration file. In the configuration file, you can set the value of a global parameter by means of an environment variable. Putting these two features together allows you to define an global parameter value at runtime.
If you run this sample with the provided scripts, the environment variables are set
for you. When experimenting with the sample in StreamBase Studio, or when running
the sample without the provided scripts, see the comments in ha-fsm.sbconf for information on the environment variables that
must be set.
To get the sample up and running, you use scripts that do the following:
-
Start the servers.
-
Start a feed simulation to all streams.
-
Start a dequeue from all streams.
The scripts to run HA FSM are in the scripts folder.
Dequeuing from the sample application (app.ssql) is
initially disabled on both servers. Shortly after startup, hacontrolcontainer.sbapp on the leader enables dequeuing for
app.ssql.
You can start the sample by running either the startprimary or the startsecondary
script first, and then running the other one. The server that starts first is
designated as the leader, and the server that starts next is the nonleader. This is
an important difference between the HA sample and the HA FSM sample.
Note
When you run the HA FSM sample, you may see warnings in the console for primary or secondary, such as:
2014-091-15 11:19:06.620-0400 [Thread- ThreadPool - 2] WARN com.streambase.sb.s d.net.HTTPServer - Connection /127.0.0.1:4666: I/O exception: An established connection was aborted by the software in your host machine
Such warnings are not unusual and can be safely ignored.
To see the high availability features, stop the leader and observe the status of the other server.
Note
The detailed steps for the HA FSM sample are very similar to those for the HA Sample.
In StreamBase Studio, import this sample with the following steps:
-
From the top menu, select → .
-
Select the
hafsmsample from the High Availability category. -
Click OK.
StreamBase Studio creates a single project containing the sample files. The default
project name is sample_hafsm.
When you load the sample into StreamBase Studio, Studio copies the sample project's files to your Studio workspace, which is normally part of your home directory, with full access rights.
Important
Load this sample in StreamBase Studio, and thereafter use the Studio workspace copy of the sample to run and test it, even when running from the command prompt.
Using the workspace copy of the sample avoids the permission problems that can occur when trying to work with the initially installed location of the sample. The default workspace location for this sample is:
studio-workspace/sample_hafsm
See Default Installation
Directories for the location of studio-workspace on your system.
In the default TIBCO StreamBase installation, this sample's files are initially installed in:
streambase-install-dir/sample/hafsm
See Default Installation
Directories for the location of streambase-install-dir on your system. This location
may require administrator privileges for write access, depending on your platform.