Creating Apama projects the non-Designer way
Apama uses the concept of "bundles" to add connectivity such as Kafka or MQTT to a project and also to add EPL capabilities, such as date/time formatting. Until now, the only way to do this was using the Software AG Designer graphical environment supported on Windows®. A new tool called ‘apama_project’ lets you do this from a command line on Linux® as well.
The tool is interoperable with Software AG Designer, so you can move between tools as needed. Projects created with the tool apama_project are also fully compatible with the engine_deploy tool for project deployment.
This diagram shows a comparison between the traditional Software AG Designer application and the newly developed command-line tool apama_project. It illustrates how you can use the tool to manage an Apama project and the bundles inside it.
What you can do with this tool
Create 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.
> apama_project create ApamaProjectwhere, “ApamaProject” is the requested project name.
Now, in order to perform other commands, such as listing bundles or adding/removing bundles, you need to change the shell's current directory to the new project directory.
List bundles
The displayed 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. Further, the second section has groups based on bundle types like standard, adapters, and connectivity.
> apama_project list bundlesAdd bundles
There are a couple of ways to add bundles to a project.
First, you can pass the bundle display name, which gets displayed when you list bundles in the project.
> apama_project add bundle Kafkawhere, ‘Kafka’ is the bundle display name.
Secondly, you can pass the index number of the bundle. In this particular case, you need a fresh listing of all the bundles in the project and then pass the up-to-date index number corresponding to the bundle.
> apama_project list bundles
Bundles that have already been added:
Bundles that can be added:
Connectivity bundles:
.. ...
43 User Connectivity
> apama_project add bundle 43
where index number “43” corresponds to “User Connectivity” bundle in the refreshed listing.
For some bundles, it is possible to add multiple instances. In those cases, to optionally customize the instance name for such bundles, you can use "--instance MyInstance". That also allows you to give them a more logical name. Furthermore, 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.
Remove bundles
To delete a standard EPL bundle, you need to provide the bundle display name. To delete a connectivity bundle, you can either provide the bundle display name or the bundle instance name.
It is worth noting that the default name of the first instance of a connectivity bundle is the display name of the bundle as shown in the list. So, if you request the removal of that particular instance, then only that particular instance will be deleted.
> apama_project remove bundle Kafkawhere, “Kafka” is the bundle display name.
More information about the supported actions and the command formats can be gained by running the partial command along with the help option, i.e., --help or –h. For example:
> apama_project --help
> apama_project create --help
> apama_project add bundle --help
> apama_project remove bundle --help
Deploying a project
With engine_deploy tool, you can deploy a project that is created using the apama_project tool. The same holds true for a project in which bundles are managed using the new tool. The following demonstration shows how to create a project using a connectivity plug-in to allow Apama to act as a simple HTTP server:
First, create an Apama project, naming the project as “HTTPServerDemo,” and then add an HTTP Server bundle:
> apama_project create HTTPServerDemo
Project created successfully at location: \HTTPServerDemo
> cd HTTPServerDemo
> apama_project add bundle "HTTP Server"
Adding bundle "HTTP Server".
"HTTP Server" bundle added successfully.
You may need to configure instance files by editing the following files.
"C:\HTTPServerDemo\config\connectivity\HTTPServer\HTTPServer.properties"
"C:\HTTPServerDemo\config\connectivity\HTTPServer\HTTPServer.yaml"
"C:\HTTPServerDemo\config\connectivity\HTTPServer\swagger_HTTPServer.json"
As suggested during bundle addition, you need to configure the instance files. So, you set up the HTTP Server configuration by editing the file “HTTPServer.yaml”:
connectivityPlugins:
httpServer:
libraryName: connectivity-http-server
class: HTTPServer
dynamicChainManagers:
httpServer:
transport: httpServer
managerConfig:
port: 443
bindAddress: localhost
dynamicChains:
httpServer:
- apama.eventMap:
defaultEventType: HelloWorld
defaultChannel: HelloWorldChannel
- jsonCodec
- stringCodec
- httpServer:
automaticResponses: true
allowedMethods: [PUT]
Next, you need the EPL to do something on receipt of the event generated from HTTP request:
event HelloWorld {}
monitor HelloWorldMonitor
{
action onload()
{
monitor.subscribe("HelloWorldChannel");
on all HelloWorld ()
{
log "Hello World" at INFO;
}
// signal that we are ready to receive events
com.softwareag.connectivity.ConnectivityPlugins.onApplicationInitialized();
}
}
Finally, you use the engine_deploy tool to create a deployment directory from the project:
> engine_deploy --outputDeployDir ..\HTTPServerDemo-Deployment .
> cd ..\HTTPServerDemo-Deployment
> correlator --config .
...
2019-02-22 00:49:00.261 INFO [3364] - Binding to http://localhost:443
Summary
In this article you’ve learned how to use apama_project tool to manage an Apama project and the bundles inside it. For more help, check out our regular blog posts at Apama Community or ask a question on Stack Overflow with the apama tag.