Introducing ‘apama_project’

Apama uses the concept of “bundles” to provide the ability to add connectivity such as Kafka or MQTT to the project, and also for adding EPL capabilities such as date/time formatting. Until now, the only way to create a project and add these bundles was using the Software AG Designer graphical environment, which is only supported on Windows.

However, now we have a new tool called apama_project  that enables all this functionality from the command line, on Linux as well as Windows.

The tool is interoperable with Software AG Designer, allowing the user to move between the tools as required. Projects created with apama_project  are also fully compatible with the engine_deploy  tool for project deployment.

The diagram below shows a comparison between the traditional Software AG Designer application and the newly developed command-line tool apama_project  .

It illustrates how we can use the tool to manage an Apama project and the bundles inside it.

Actions supported by the apama_project tool

Creating a project

The tool creates a new project directory with the specified name below the current directory and adds all the Apama project related files into the project directory.

The created project will be identical to one created within Software AG Designer.

Creates a folder ApamaProject with the following layout:

Once the project is successfully created, change the shell’s current directory to the new project directory before performing other commands such as listing bundles or adding/removing bundles.

Adding bundles

Adding a bundle is very simple, and can be done in a couple of ways. Firstly, we can pass the bundle display name, which gets displayed when we list the bundles (See below) in the project.

Some bundles support adding multiple instances. For example, we can add several instances of the HTTP client to connect to different HTTP servers.

We can supply an instance name for such bundles using --instance  to give a name for the service we’re connecting to. If omitted a default instance name will be used E.G. HTTPClient, HTTPClient2, HTTPClient3 , and so on.

The instance name is used in various places within the connectivity configuration files and in some cases also in the EPL code for interacting with them. It cannot be changed once the bundle instance has been added, so it’s worth thinking about before adding.

Kafka is another bundle which can be used multiple times, above we added it with the default and below we use our own more descriptive name:

We can also add a bundle using the index number that is shown in the bundle list (See Below). Since the index numbers are not fixed for any bundle type, and may change with the addition of new bundles, we should list the bundles before using this command to ensure we are using the correct index number.

Listing bundles

The bundles list consists of two sections. The first section displays the bundles that are already added to the Apama project. The second section displays the available bundles that can be added to the project.

Removing bundles

To delete a standard EPL bundle, we need to provide the bundle display name as shown in the list.

To delete a connectivity bundle, we need to provide the bundle instance name or the bundle display name as shown in the list. The default name of the first instance of a connectivity bundle is the display name of the bundle as shown in the list. 

Consider the earlier scenario where we’ve added two Kafka instances – if we execute apama_project remove bundle Kafka  only the default Kafka instance will be removed, while the other instance TwitterStream will remain unaffected.

To clean up another Kafka instance, we can pass the bundle instance name.

Alternatively, we can simply input the bundle file name to remove the remaining non-matching instances of the Kafka bundle.

Deploying a tool-created project

The engine_deploy tool can deploy a project that’s created using apama_project or SoftwareAG Designer. It works on both windows and linux and we use it below in combination with apama_project to create an application using a connectivity plug-in to allow Apama to act as a simple HTTP server:

Run apama_project add bundlecommand from within the project directory:

make changes to the contents inside the HTTPServer.yaml  file:

Add a new monitor file in the monitors directory, E.G. server.mon :

Now, use the engine_deploy  tool to create a deployment directory from the project:

And run the application using the following command:

You should now be able to attach with a browser to see “Hello World”.