Deploying EventFlow Fragments

Node Cycle Overview

The lifecycle of a StreamBase Runtime node is: install, start, stop, remove.

You must install a node containing your EventFlow fragment in order to run it. When you run a fragment within StreamBase Studio, Studio handles the installation and starting of your fragment into a node. When you stop your fragment, Studio stops but does not remove the node. This allows Studio to reuse the same node for the next in-Studio run.

To deploy an EventFlow fragment outside of Studio, use the epadmin command to install, then start a node containing your fragment. HOCON configuration files can specify the engines and fragments to run in a node.

Once the node is installed, you can issue an epadmin start node command, which starts running the application fragments in that node. StreamBase EventFlow fragments cannot accept tuples on its Input Streams until its containing node has been both installed and started.

To halt or pause a node, you can issue an epadmin stop node command. This stops the EventFlow fragment from receiving or processing tuples.

The final stage in each node's lifecycle is to remove the node. On shutdown, StreamBase Studio automatically removes any nodes it has installed and used. To remove a node installed at the command line, issue an epadmin remove node command.

Creating a Deployment Application Project

A StreamBase EventFlow fragment is one part of a StreamBase Runtime application, which can ultimately be distributed among many nodes and machines. To run an EventFlow fragment at the command line outside of Studio, you must create a separate Studio project for a Deployment Application. Then, add your EventFlow fragment's archive to the Deployment Application, and create a new archive.

Use the following steps:

  1. First, when your EventFlow fragment is in a known working and tested state, create a fragment archive for it. Do this by selecting the project name in Studio's Project Explorer, and selecting Run AsMaven install from the context menu. This Maven goal produces a zip file in the project's target directory.

    Note

    If Maven Install results in a BUILD FAILURE message, try again with Run AsMaven build... In the resulting dialog, type clean install in the Goals field, and select the Skip Tests check box. Click Apply, then Run.

  2. Next, create a new StreamBase project, this time selecting Deployment Application as the project type. TIBCO suggests choosing a name for this project that starts with "deploy" to distinguish it from EventFlow fragment projects.

  3. Click Next.

    Tip

    At the second panel, click Next instead of Finish. This opens a third panel named Archetype Properties. To cut down on the number of test instances created, edit the testnodes line from its default A,B,C to just A.

  4. Select the project name in the Project Explorer view. Right-click and select MavenAdd Dependency from the context menu.

  5. In the Add Dependency dialog, in the Enter groupid field, type the initial letters of your organization's group ID, typing enough letters to show the projects whose package name begins with those letters. For StreamBase samples, type com.ex to show all projects whose package name begins with com.example.

  6. Select the EventFlow fragment project for which you built a fragment archive in step 1. Then click OK. The pom.xml file is automatically saved.

  7. In the Project Explorer view, right-click your new Deployment Application project folder and select Run AsMaven install from the context menu. This builds a Deployment Application archive file and installs it both in the project's target folder, and in the local Maven repository (usually $HOME/.m2)

    Note

    As in step 1, if this step results in a BUILD FAILURE message, try again with Run AsMaven build... Enter clean install in the Goals field and select the Skip Tests check box.

Installing a Node with epadmin

To run a Deployment Application archive at the command line, use an epadmin install node command with certain arguments, like the following example. (This command is shown on multiple lines, but must be entered as one long command.)

epadmin install node 
  application=target/deploy_firstapp-0.0.1-SNAPSHOT-ep-application.zip 
  nodename=B.sbuser nodedirectory=/tmp/DTMout

This example command is shown on two lines, but must be typed as a single command.

The following arguments are required:

application=

The application argument specifies the full or relative path to the Deployment Application zip file you created in the previous section. This is the zip file that contains your deployment application's archive, not just the StreamBase fragment's zip file.

TIBCO recommends opening a StreamBase Command Prompt or a Terminal window in your Studio workspace and navigating directly to the deployment project's folder. This cuts down on the length of the path you must type. You can use the StreamBaseOpen Command Prompt Here option from an EventFlow fragment project's context menu, then navigate up and over to the Deployment Archive's project folder.

The example command above shows the relative path target/deploy_firstapp-0.0.1-SNAPSHOT-ep-application.zip because the command is run from the deploy_firstapp folder in the Studio workspace.

nodename=

The nodename argument must be included. Specify a name for the node you are installing in nodename.clusterName format. Do not re-use the A nodename used by default for Studio node launches. The cluster name is usually your system login name, but can be any string. The example above specifies a nodename of B.sbuser.

The following argument is optional but strongly recommended:

nodedirectory=

Use the nodedirectory argument to specify a directory into which the StreamBase Deployment Runtime can write its log files and other tracking information. Specify a container directory; the Runtime creates a subfolder under the directory you specify to hold this node's files. The directory created is named the same as the nodename. You can use a full or absolute path to any location. The example above specifies the system location /tmp/DTMout. On Windows, you can specify paths such as C:\tmp\DTMout.

If you do not specify a nodedirectory argument, epadmin uses its current directory, and creates a subfolder there.

The node directory can grow quite large, and is usually the size of the memory specified at node installation time. The default value is 512 megabytes, but you can specify a larger value with the memorysize option.

You can specify other node install parameters. Run epadmin help node at a shell prompt to see the available options, or consult the extensive DTM documentation page for the epadmin command options.

Starting a Node

When the node is installed, start it running with a command like the following. The servicename= argument identifies the nodename you specified in the install command.

epadmin servicename=B.sbuser start node

Stopping a Node

Stopping a node means to stop processing tuples sent to the running EventFlow fragment's Input Streams. Stop a running EventFlow Fragment node with a command like the following:

epadmin servicename=B.sbuser stop node

Stopped nodes can be restarted with another start node command. This resumes processing of incoming tuples.

Nodes installed and started at the command line show up in the Clusters view of StreamBase Studio. You can also use the stop and remove buttons at the top right of the Clusters view to stop and remove nodes started at the command line.

Removing a Node

To remove a stopped node from the StreamBase Runtime fabric, run a command like the following:

epadmin servicename=B.sbuser remove node