Working with Projects

Creating Apama projects

In addition to using Apama Plugin for Eclipse to create an Apama project as described below, you can also do this using the apama_project command-line tool. See Creating and managing an Apama project from the command line for more information.

To create an Apama project

1. From the Apama Plugin for Eclipse menu, select File > New > Apama Project. If you are using the Apama Workbench perspective, you can also click the New Project button in top right of the Workbench Project view.

2. In the New Apama Project dialog, specify information for the following fields:

   1. In the Project Name field, enter the name of your new project. Project names typically use title case capitalization and may contain spaces, for example “My Project”.

   2. If you want to store the project in a directory other than the default location, clear the Use default location checkbox, click Browse, and navigate to and select the location for storing your new project.

3. In the Configure the new project wizard, add checkmarks to the bundles that are appropriate to the type of application you are developing. For example, if your application is a DataView application, select the DataView Service bundle. When you create a new project, the settings for the selected bundles remain same as they were for the last time you created a new project. You can change these settings and specify other bundles for your application. Click Next.

   Bundles package service monitors, event definitions and other files associated with the standard Apama adapters that are required for the type of application you are building. For example, applications that use DataViews need the DataView Service bundle. If your application requires an adapter, select the associated bundle from this list.

   If you want to use connectivity plug-ins in your project, you can add one or more connectivity bundles to the project from this wizard. An instance of User Connectivity can be selected if you want to make use of any user-defined connectivity plug-ins.

   If you are creating a project for an EPL application, click Finish.

   If you are creating a project for a JMon application or developing Java connectivity plug-ins, select Add Apama Java support. If you want to apply standard Eclipse Java support, select Add Java support. See Adding the Java nature to an Apama project for detailed information on these options. Click Next.

4. If you have selected Add Apama Java support, the Configure the new Apama Java application dialog appears. Fill in the fields as desired. Click Finish.

   Info

   Apama’s in-process API for Java (JMon) is deprecated and will be removed in a future release.

5. If you are not currently in an Apama perspective, the Open Associated Perspective? dialog appears. Select Remember my decision if you want Apama to remember your choice. Click Yes or No.

If you are in the Apama Developer perspective, Apama Plugin for Eclipse displays the name of your new project in the Project Explorer view. If this is your first project, the other panes are blank.

Adding resources to Apama projects

You specify the Apama resources that make up your application by adding them to the Apama project. Apama Plugin for Eclipse recognizes and provides editing features for the following files:

• EPL files (.mon)

• Event files (.evt)

• JMon monitor and event files (.java)

  Info

  Apama’s in-process API for Java (JMon) is deprecated and will be removed in a future release.

However, you can add any type of file to an Apama project and Eclipse uses the correct editor to open it.

Creating new monitor files for EPL applications

EPL files define monitors and/or event types.

Monitor definitions and event type definitions are in .mon files.

For more information about EPL, see Getting started with Apama EPL. For more information on the editing features available when writing EPL code, see Editing Apama files.

To add a new monitor file to an Apama project

1. In the Project Explorer view or the Workbench Project View, right-click the monitors folder of the project where you want to add the monitor file and select New > EPL Monitor.

2. In the New EPL Monitor dialog, enter information in the following fields:

   1. The Containing folder field is the folder where the file will be saved. By default, this is the folder of the currently selected project, but you can select another folder using the Browse button.

   2. In the Monitor name field, specify the name of the new monitor. This name is also used as the file name. It is recommended that you use TitleCase with the monitor name. The monitor name must not contain special characters, except for the dollar ($) and underscore (_) characters.

      Specifying the .mon file extension is optional as Apama Plugin for Eclipse will add the .mon file extension. Apama Plugin for Eclipse will not let you specify anything except .mon as a file extension.

   3. The Package field is optional. Information in this field is an EPL package name.

3. Click Finish.

   The new file now appears in the Project Explorer view or the Workbench Project View under the project that contains it, and the EPL file opens in the EPL editor. The EPL editor provides a monitor template with the specified monitor name.

4. In the EPL editor, add the desired EPL code and save the file.

Creating new event definition files for EPL applications

• Creating event definitions by adding EPL code
• Creating event definitions from XML files
• Creating event definitions from XSD files

You can select one of the following ways to create the new event definition for an Apama project.:

• EPL Editor — Create an event definition by adding EPL code.
• XML File — Create an event definition based on the structure of an XML file.
• XSD File — Create an event definition based on the schema defined in an XSD file.

Creating event definitions by adding EPL code

To create an event definition by adding EPL code

1. In the Project Explorer view, right-click the eventdefinitions folder of the project where you want to add the event definition and select New > EPL Event Definition.

2. In the New EPL Event Definition dialog, select EPL Editor and click Next.

3. Enter information in the following fields:

   1. The Containing folder field is the folder where the file will be saved. By default, this is the currently selected folder of the current project, but you can select another folder or project using the Browse button.

   2. In the Event definition name field, specify the name of the new event definition. This name is also used as the file name. It is recommended that you use TitleCase with the name. The name must not contain special characters, except for the dollar ($) and underscore (_) characters.

      Specifying the .mon file extension is optional as Apama Plugin for Eclipse will add the .mon file extension. Apama Plugin for Eclipse will not let you specify anything except .mon as a file extension.

   3. The Package field is optional. Information in this field is an EPL package name.

4. Click Finish.

   The new event definition file is added to the specified folder in the project, and the EPL file opens in the EPL editor. The EPL editor provides an event template with the specified event definition name.

5. In the EPL editor, add the desired EPL code and save the file.

Creating event definitions from XML files

You can create an event definition that is based on the structure of an XML document. The generated event definition is based on the following:

• All fields are treated as string.
• All prefixes are ignored, in other words, event definitions will be generated even if inner elements have different namespaces.
• Namespace attributes (attributes having an xmlns prefix) are ignored.
• All inner event names are prefixed with Element_.
• Generated event definitions will have an xmlTextNode field if the XML element contains a text value and also contains an attribute.

To create an event definition from an XML file

1. In the Project Explorer view, right-click the eventdefinitions folder in the project in which you want to create the event definitions and select New > EPL Event Definition.

2. In the New EPL Event Definition dialog, select XML File and click Next.

3. Enter information in the following fields:

   1. The Containing folder field is the folder where the file will be saved. By default, this is the currently selected folder of the current project, but you can select another folder or project using the Browse button.

   2. In the File name field, specify the name of the file. It is recommended that you use TitleCase with the name and that the name does not contain special characters, except for the dollar ($) and underscore (_) characters.

      Specifying the .mon file extension is optional as Apama Plugin for Eclipse will add the .mon file extension. Apama Plugin for Eclipse will not let you specify anything except .mon as a file extension.

   3. The Package field is optional. Information in this field is an EPL package name.

4. Click Next.

5. In the XML file field, specify the name of the XML file on which you want to base the event. You can use the browse (…) button to navigate to the desired file. The drop-down arrow switches the scope between the workspace and the file system.

6. In the Event definition name field, specify the name you want to assign to the root level event.

7. Click Finish.

   An EPL file is created that defines the root level event along with associated nested events.

Creating event definitions from XSD files

You can create event definitions that are based on the structures of elements defined in XSD schema files.

To create an event definition from an XSD file

1. In the Project Explorer view, right-click the eventdefinitions folder in the project in which you want to create the event definitions and select New > EPL Event Definition.

2. In the New EPL Event Definition dialog, select XSD File and click Next.

3. Enter information in the following fields:

   1. The Containing folder field is the folder where the file will be saved. By default, this is the currently selected folder of the current project, but you can select another folder or project using the Browse button.

   2. In the File name field, specify the name of the new file. It is recommended that you use TitleCase with the name and that the name does not contain special characters, except for the dollar ($) and underscore (_) characters.

      Specifying the .mon file extension is optional as Apama Plugin for Eclipse will add the .mon file extension. Apama Plugin for Eclipse will not let you specify anything except .mon as a file extension.

   3. The Package field is optional. Information in this field is an EPL package name.

4. Click Next.

5. On the Select XSD File page of the New EPL Event Definition dialog, click the Browse button to the right of the Schema element/type field. This displays the Type Chooser dialog.

6. In the Type Chooser dialog, specify the file that contains schema’s global element that you want to use as the root element on which to base the event definition. Click the browse (…) button to navigate to the file. The drop-down arrow lets you change scope among recent files, local file system, workspace, remote URL, and XML Schema. Select a file and click OK. The Select XSD File page now shows the root element you selected in the Schema element/type field.

7. In the Event definition name field, specify the name you want to assign to the root level event.

8. Click Finish.

   An EPL file is created that defines the root level event along with associated nested events.

Creating new files for JMon applications

• Adding a new JMon application
• Adding a JMon monitor
• Adding a JMon event

For Apama projects that use JMon applications, you can add new JMon applications, JMon monitors, and JMon events. In Apama applications written in Java, monitors and event types are implemented as Java classes.

Adding a new JMon application

To add a new JMon application to an Apama project

1. In the Project Explorer view or the Workbench Project view, right-click the name of the project where you want to add the monitor and select New > Java Application. The New Java Application wizard appears.

2. In the New Java Application wizard, in the Configuration field specify the name of the application and click Finish. The application is added to the project and its configuration opens in the Apama Java configuration editor.

3. In the Apama Java configuration editor, specify the application’s meta-data and add classes and contents as required. For more information on editing the configuration, see Adding resources to JMon projects.

Adding a JMon monitor

To add a new JMon monitor to an Apama project

1. In the Project Explorer view or the Workbench Project view, right-click the name of the project where you want to add the monitor and select New > Java Monitor. You can also select File > New > Other from the menu and then select Apama > Java Monitor from the Select a wizard dialog.

2. In the New Apama Java Monitor wizard, enter information in the following fields:

   1. The Application field is the application to which you are adding the monitor.

   2. In the Monitor name field, specify the name of the new monitor. This will become the name of the class and the Java file.

   3. The Description field is optional.

   4. The Apama Package field is optional; this is the package of the monitor inside the correlator.

   5. Add a check to the Implement MatchListener check box if you want Apama Plugin for Eclipse to generate the skeleton code for the class’s MatchListener interface.

   6. The Source Folder field specifies the folder in the project to contain the file; by default this is java/src.

   7. The Java Package field is optional; this is the package of the created Java class.

3. Click Finish. The name of the new class file now appears in the Project Explorer view or the Workbench Project view under the project that contains it and the .java file opens in the editor.

For more information about JMon applications, see Overview of Apama JMon applications.

Adding a JMon event

To add a new JMon event to an Apama project

1. In the Project Explorer view or the Workbench Project view, right-click the name of the project where you want to add the monitor and select New > Java Event > Other. You can also select File > New from the menu and then select Apama > Java Event from the Select a wizard dialog. The New Apama Java Event wizard appears.

2. In the New Apama Java Event wizard, enter information in the following fields:

   1. The Application field is the application to which you are adding the event.

   2. In the Monitor name field, specify the name of the new event. This will become the name of the class and the Java file.

   3. The Description field is optional.

   4. The Apama Package field is optional; this is the package of the event inside the correlator.

   5. The Source Folder field specifies the folder in the project to contain the file; by default this is java/src.

   6. The Java Package field is optional; this is the package of the created Java class.

3. Click Finish. The name of the new class file now appears in the Project Explorer view or the Workbench Project view under the project that contains it and the .java file opens in the editor.

For more information about JMon applications, see Overview of Apama JMon applications.

Adding an EPL Plug-in written in Java

To add a new EPL plug-in written in Java to an Apama project

1. In the Project Explorer view or the Workbench Project view, right-click the name of the project where you want to add the EPL plug-in and select New > Java EPL Plugin. You can also select File > New > Other from the menu and then select Apama > Java EPL Plugin from the Select a wizard dialog. The New Apama Java EPL Plugin wizard appears.

2. In the New Apama Java EPL plug-in wizard, enter information in the following fields:

   1. The Application field is the application to which you are adding the plug-in.

   2. In the Plugin name field, specify the name of the new plug-in. This will become the name of the class and the Java file.

      Important:

      When importing the plug-in from EPL, you will use this plug-in name, prefixed by the package name from the Apama Package field (see below).

   3. The Description field is optional.

   4. The Apama Package field is optional. This is the package of the plug-in inside the correlator.

   5. The Source Folder field specifies the folder in the project to contain the file. By default, this is java/src.

   6. The Java Package field is optional, but by default corresponds to the Apama package name. This is the package of the created Java class.

3. Click Finish. The name of the new class file now appears in the Project Explorer view or the Workbench Project view under the project that contains it and the .java file opens in the editor. In Project Explorer, the () icon indicates a Java plug-in to the correlator.

4. You will find the source file for your Java class in the java/src package in your project. You can now add functionality to the class as required for your application. This can be called from EPL using the mechanism described in Using EPL plug-ins written in Java.

For applications that you plan to inject into a correlator, the recommendation is to create separate jar files for:

• EPL plug-ins written in Java
• JMon applications

Although the mechanism for creating these jars and describing their meta-data is similar, the interactions of these two different uses of injected jars mean that they will often need to be injected into the correlator separately. The creation of separate jar files ensures that you can inject your application components in the correct order, which is typically:

1. EPL plug-ins written in Java
2. EPL monitors and events
3. JMon applications

For more information, see Overview of Apama JMon applications and Writing EPL plug-ins in Java.

Creating new event files

Event files are used to supply events of a specific type. For example in applications written in EPL, you should usually send in an event to tell the monitors making up the application to start listening for events once everything has been injected.

To add a new event file to an Apama project

1. In the Project Explorer view or the Workbench Project view, right-click the events folder of the project where you want to add the event file and select New > File > Event. In the Workbench Project view you can also select the events folder and click the New Event File button.

2. In the New Event File wizard, enter information in the following fields:

   1. The Containing Folder field is the folder where the file will be saved; by default this is the folder of the currently selected project, but you can select another folder using the Browse button.

   2. In the File name field, specify the name of the new file. Specifying the .evt extension is optional as Apama Plugin for Eclipse will add the .evt file extension. Apama Plugin for Eclipse will not let you specify anything except .evt as a file extension.

3. Click Finish. The name of the new file now appears in the Project Explorer view or the Workbench Project view under the project that contains it and the event file opens in the Apama event editor.

Event Type Selection

The Event Type Selection dialog lists the event types that are available in the current project.

1. In the Choose an Event Typefield, specify the name of the event you want to use. As you type, event types that match are displayed in the Matching Events list.

2. In the Matching Events list, select the name of the event type you want to use. The name of the EPL file that defines the selected event is displayed in the status field at the bottom of the dialog.

3. Click OK.

Adding resources to EPL projects

To add an existing EPL file that defines a monitor to an Apama project, you add the file as an External Dependency. You can also add EPL files that are contained in an Apama Correlator Deployment Package file.

To add a file to an active project as an external dependency

1. Select Project > Properties from the menu.

2. In the Properties dialog, select Apama Build Path from the left hand pane and select the External Dependencies tab in the right pane.

3. Click Add External button and navigate to the files you want to add. You can select EPL (.mon) files or Correlator Deployment Package (.cdp) files.

4. Click OK at the Properties dialog.

Adding resources to JMon projects

• Java Configuration Editor
• Adding JMon applications
• Adding JMon classes
• Adding non-JMon Java files

To add existing resources to a JMon project, you modify the project’s configuration. The configuration information is stored in the project’s config/apama_java.xml file.

To add resources to a JMon project, double click the project’s config/apama_java.xml file. The Apama Java configuration editor appears.

The Application drop-down list on the right of the editor’s title bar shows the application you are editing. You can select any JMon application currently included in the project and you can add JMon applications from other projects to your current project.

You can use the Classpath field to specify any additional third party jars that should be on the runtime classpath of the JMon application or Java plug-in.

For example, ${sys:MY_THIRD_PARTY_DIR_SYS_PROP}/lib/foo.jar;${env:MY_OTHER_THIRD_PARTY_DIR_ENV_VAR}/bar.jar

For more information on the classpath string, see Specifying the classpath in deployment descriptor files.

You can add other JMon classes (JMon events and JMon monitors) and non-JMon Java files to a project.

Java Configuration Editor

On the Java Configuration editor, you add and manage resources for JMon projects.

The Application drop-down list on the right of the editor’s title bar shows the application you are editing. You can add the following resources to your project:

• JMon applications from other projects
• JMon classes from other JMon projects
• Non-JMon Java files

Adding JMon applications

To add a JMon application from another Apama project

1. Click the Add application button (()). The New Application Name dialog appears.

2. Specify a name for the new application and click OK. The editor will display the settings for this new application and the name will be added to the editor’s drop down list.

3. In the Apama Java configuration editor, expand the Java Application Classes heading. This displays the current list of the Java classes included in the project.

4. Click Add.

   The Select Java Apama Files dialog appears showing the available JMon Application projects.

5. Select the JMon application file you want and click OK.

6. When you save the configuration information, a .jar file is generated.

Adding JMon classes

To add a JMon monitor or event from another Apama project

1. In the Apama Java configuration editor, expand the Java Application Classes heading. This displays the current list of the Java classes included in the project.

2. Click Add.

   The Select Apama Java Files dialog appears showing the available JMon application projects.

3. In the Select Apama Java Files dialog navigate to the class you want to add, select it, and click OK.

4. In the Apama Java configuration editor, you can also change the order in which the JMon classes are listed with the Up and Down buttons. This affects the way the files are ordered in the manifest file and the order in which they are injected in the correlator. Events are injected first, followed by monitors; in both cases, they are injected in the order they are listed here.

Adding non-JMon Java files

To add non-JMon Java files

1. In the Apama Java configuration editor, expand the Additional Content heading. This displays the current list of non-JMon Java files included in the project.

   You can add files from other Apama projects and you can add non-project files from outside the Apama Plugin for Eclipse workspace.

2. To add a file from an existing Apama project:

   1. Click Add from a project. The Select a Resource dialog appears.

   2. Navigate to the file you want to add, select it, and click OK.

3. To add a file from outside Apama Plugin for Eclipse:

   1. Click Add a Variable. The Select variables to add to build path dialog appears.

   2. Select a variable and, if necessary, click Extend to identify specific folders on the path. Click OK.

Adding Docker support to Apama projects

To build an Apama project with Docker support, you must add Docker support to your Apama project.

To add Docker support to an Apama project

• In the Project Explorer view, right-click the project and select Apama > Add Docker Support.

  A Dockerfile is created in the Apama project. For more information on Dockerfile, see Building Apama projects during the Docker build.

Adding bundles to projects

• Adding EPL bundles to projects
• Adding connectivity and adapter bundles to projects

Bundles are named collections that group the Apama objects that are necessary for different types of applications. When you are creating a new Apama project, the New Apama Project dialog lists the following bundle:

• Standard bundles. This bundle contains standard EPL bundles supplied with the product. These bundles contain service monitors and event definitions that are specific to the type of application you are building. For example, applications that use DataViews need the DataView bundle. See Adding EPL bundles to projects.

• Connectivity bundles. This bundle contains the connectivity bundles supplied with the product, each of which contains connectivity configuration files (YAML and properties files), and sometimes also references to supporting EPL monitors. The connectivity plug-ins perform a similar role to IAF adapters: both allow plug-ins to transform and handle delivery of events. In most cases, we recommend using connectivity plug-ins instead of the IAF for new adapters. See Adding connectivity and adapter bundles to projects.

• Adapter bundles. The adapter bundles contain adapter configuration files, monitors, and other files needed by the Integration Adapter Framework (IAF). Apama provides adapters that communicate with third-party messaging systems, transforming incoming messages into Apama events and, in the opposite direction, transforming Apama events into the proprietary representations required by third-party messaging systems. In addition, the adapter for the Apama Database Connector (ADBC) allows an application to connect to standard ODBC and JDBC data sources as well as Apama Sim data sources. See Adding connectivity and adapter bundles to projects.

  Info

  The Apama Database Connector (ADBC) and other standard IAF plug-ins (except for the codec IAF plug-ins) are deprecated and will be removed in a future release.

• User bundles. The user bundles are user-defined bundles that are not packaged with the product. The user bundles can be received from Cumulocity through email, sample, community download and so on. If you want to add a user bundle, copy the user bundle file to the catalogs\bundles directory in your Apama work directory.

Adding EPL bundles to projects

• There are two ways of adding a bundle to a project.

  • If you are creating a new Apama project: Select File > New > Apama Project, give it a name, and click Next. Under the Standard bundles node, select the EPL bundle that is appropriate for your application. Click Finish. For more information, see Creating Apama projects.

  • If you are adding a bundle to an existing project: In the Project Explorer view, right-click the EPL Bundles node and select Add Bundle. Select the EPL bundle that is appropriate for your application. Click OK.

The EPL bundle is added to the EPL Bundles node in your project along with the supporting monitors such as DatabaseSupport.mon. If a bundle contains a correlator deployment package (CDP), you can see this in the bundle’s hierarchy in the project’s EPL Bundles node.

To remove an EPL bundle, right-click the bundle and click Remove Bundle. Click OK.

Adding connectivity and adapter bundles to projects

• Bundle instances
• Connectivity bundles
• Adding the Universal Messaging connectivity plug-in to a project
• Adding the MQTT connectivity plug-in to a project
• Adding the HTTP server connectivity plug-in to a project
• Adding the HTTP client connectivity plug-in to a project
• Adding the Kafka connectivity plug-in to a project
• Adding the Cumulocity IoT connectivity plug-in to a project
• Removing a bundle instance

To add a connectivity bundle or an adapter bundle to a project

• There are two ways of adding a connectivity bundle or an adapter bundle to a project.

  • If you are creating a new Apama project: Select File > New > Apama Project, give it a name, and click Next. Select the connectivity bundle or the adapter bundle that is appropriate for your application. Click Finish. For more information, see Creating Apama projects.

  • If you are adding a bundle to an existing project: In the Project Explorer view, right-click the project and select New > Connectivity and Adapters or right-click the Connectivity and Adapters node and select Add Connectivity and Adapters. In the Connectivity and Adapters dialog, select the bundle and create a new name for the bundle instance in the Instance name text box or accept the default instance name. Apama Plugin for Eclipse prevents you from using a name that is already in use. Click OK.

• For the connectivity bundles, the standard-codecs.yaml file and other linked configuration files are shown in the Linked Resources folder. The standard-codecs.yaml contains all the standard codecs defined by Apama; see Codec connectivity plug-ins for more information. Also, a .yaml and a .properties file are created in the Connectivity and Adapters > bundle_name > bundle_instance node; see Standard connectivity plug-ins for more information. References to bundled EPL files are listed in the Dependent Bundles node, for example, the Connectivity Plug-ins Application Support bundle which contains the EPL event definitions for controlling connectivity plug-in behavior; see the API reference for EPL (ApamaDoc) for more information.

• For the adapter bundles, Apama Plugin for Eclipse adds an instance of the adapter to the Connectivity and Adapters node in your project along with the supporting monitors such as IAFStatusManager.mon and the associated service monitors. Reference to bundled files associated with the adapters, such as IAF Status Manager and Status Support are listed in the adapter’s Dependent Bundles node. For more information, see Standard IAF plug-ins as well as The Database Connector IAF adapter (ADBC).

  Info

  The standard IAF plug-ins (except for the codec IAF plug-ins) are deprecated and will be removed in a future release.

You can add more than one bundle instance for some connectivity bundles and adapter bundles. This allows you to create different configurations of the adapter, for example if your application needs to run with different data providers.

Bundle instances

When you add a connectivity bundle or an adapter bundle to a project in the Project Explorer view, the bundle appears in the project’s directory structure. Many bundles contain only EPL or Java files. Adding these bundles means that references to the bundle files will be added to the project build path, but does not involve copying any files into the project. However, when you add a connectivity bundle or an adapter bundle that contains customizable files such as .evt or configuration files, Apama Plugin for Eclipse physically copies these files into the project, in addition to the changes made to the project build path.

If you add more than one instance of a particular connectivity bundle or an adapter bundle to the project, Apama Plugin for Eclipse creates separate copies of these files for each instance (except for bundles where it only makes sense to have one copy of the instance files per project). You can change and customize the bundle instance files in any manner. It is possible to add multiple instances of such bundles to a given project to allow different customization of the same instance files, for example if your application needs to run with two instances of a particular adapter, each connected to a different data provider.

To add more than one bundle instance

1. Right-click the bundle and select Add instance. The Connectivity and Adapter dialog appears.

2. Provide a unique name for the bundle instance in the Instance name text box to identify the instance to distinguish it from any other instances of the same bundle.

   Optionally, you can also accept the default bundle instance name.

   Info

   You can provide a name only for some of the connectivity bundles and adapter bundles.

   This instance name will be included in the filename of the bundle instance files when they are copied into the project. If only one instance of a given bundle will be required, it is fine to use the default bundle instance name.

3. Click OK.

A bundle_name.yaml file and a bundle_name.properties file are created in the Connectivity and Adapters > bundle_name > bundle_instance node.

Connectivity bundles

Apama supports the following connectivity bundles:

• User Connectivity. Select an instance of User Connectivity if you want to make use of any user-defined connectivity plug-ins. For more information, see Using connectivity plug-ins.

• Universal Messaging. Universal Messaging delivers data across different networks. It provides messaging functionality without the use of a web server or modifications to firewall policy. In Apama applications, you can configure and use the connectivity provided by Universal Messaging. For more information, see Adding the Universal Messaging connectivity plug-in to a project.

  Info

  The Universal Messaging transport connectivity plug-in is deprecated and will be removed in a future release. It is recommended to instead either use the MQTT transport connectivity plug-in or the correlator-integrated support for the Java Message Service (JMS).

• MQTT. Apama supports MQTT, which is a publish/subscribe-based “lightweight” message protocol designed for communication between constrained devices, for example, devices with limited network bandwidth or unreliable networks. Select an instance of MQTT if you want to make use of the MQTT connectivity plug-in. For more information, see Adding the MQTT connectivity plug-in to a project.

• HTTP Server. The HTTP server is a transport for use in connectivity plug-ins which external services can connect to over HTTP/REST. Select an instance of HTTP Server if you want to make use of the HTTP server connectivity plug-in. For more information, see Adding the HTTP server connectivity plug-in to a project.

• HTTP Client. The HTTP client is a transport for use in connectivity plug-ins which can connect to external services over HTTP/REST, perform requests on them and return the response as an event. Select an instance of HTTP Client if you want to make use of the HTTP client connectivity plug-in. For more information, see Adding the HTTP client connectivity plug-in to a project.

• Kafka. Apama supports Kafka, which is a distributed streaming platform. Select an instance of Kafka if you want to make use of the Kafka connectivity plug-in. For more information, see Adding the Kafka connectivity plug-in to a project.

• Cumulocity IoT. There are several bundles used for communication with IoT devices via the Cumulocity platform. For further information, see Adding the Cumulocity connectivity plug-in to a project.

Linked Resources

Linked Resources is a node that is created after adding a connectivity bundle in the Project Explorer view. The Linked Resources node is located at project_name > Connectivity and Adapters > connectivity_bundle_name > Linked Resources. The Linked Resources node in the Project Explorer view contains the common configuration files shared by the connectivity bundle instances (only.yaml or.properties files, or both). The configuration files under Linked Resources node are included in the configuration to start the correlator in the order as they appear. After the linked resources are included in the configuration, referenced instance files for bundles are also included. If the connectivity bundles link to the same configuration files, then these files are included in the configuration only the first time they are referenced.

Adding the Universal Messaging connectivity plug-in to a project

Universal Messaging delivers data across different networks. It provides messaging functionality without the use of a web server or modifications to firewall policy. In Apama applications, you can configure and use the connectivity provided by Universal Messaging.

To add the Universal Messaging connectivity plug-in to a project

1. Invoke the Connectivity and Adapters dialog as described in Adding connectivity and adapter bundles to projects.

2. Expand the Universal Messaging node and select the desired option.

   There are several options to choose from, ranging from a simple configuration that serializes Apama event fields into a JSON document, through to an advanced configuration containing many transport and mapping configuration possibilities that may be suitable for power users.

   In the Project Explorer view, the following files are created in the Connectivity and Adapters > Universal Messaging > Universal_Messaging_bundle instance node:

   • Universal_Messaging_bundle_instance.yaml
   • Universal_Messaging_bundle_instance.properties The Universal_Messaging_bundle_instance.properties file contains the most commonly needed Universal Messaging configuration options such as the Universal Messaging server realm names to connect to.

3. Optionally, edit the Universal_Messaging_bundle_instance.yaml file if you need to perform more advanced configuration tasks, such as enabling authentication or customizing the way Universal Messaging messages are mapped to the Apama events.

   For more information, see General steps for using Universal Messaging in Apama applications and Configuring the Universal Messaging connectivity plug-in.

Adding the MQTT connectivity plug-in to a project

In Apama applications, you can configure and use the MQTT connectivity plug-in provided with Apama.

To add the MQTT connectivity plug-in to a project

1. Add the MQTT connectivity plug-in as described in Adding connectivity and adapter bundles to projects.

   In the Project Explorer view, the following files are created in the Connectivity and Adapters > MQTT > MQTT_bundle_instance node:

   • MQTT_bundle_instance.properties
   • MQTT_bundle_instance.yaml

2. Double-click the MQTT_bundle_instance.yaml file to configure the MQTT connectivity plug-in. For more information, see The MQTT Transport Connectivity Plug-in.

Adding the HTTP server connectivity plug-in to a project

In Apama applications, you can configure and use the HTTP server connectivity plug-in provided with Apama.

To add the HTTP server connectivity plug-in to a project

1. Add the HTTP server connectivity plug-in as described in Adding connectivity and adapter bundles to projects.

   In the Project Explorer view, the following files are created in the Connectivity and Adapters > HTTP Server > HTTP_Server_bundle_instance node:

   • HTTP_Server_bundle_instance.properties
   • HTTP_Server_bundle_instance.yaml
   • swagger_HTTP_Server_bundle_instance.json

2. Double-click the HTTP_Server_bundle_instance.properties file to configure the HTTP server port, that is, the port on which the server is listening for HTTP requests.

3. Double-click the HTTP_Server_bundle_instance.yaml file to configure the HTTP server connectivity plug-in. For more information, see The HTTP Server Transport Connectivity Plug-in.

4. Double-click the swagger_HTTP_Server_bundle_instance.json file if you want to add more static files. For more information, see OpenAPI definitions and Serving static files.

Adding the HTTP client connectivity plug-in to a project

In Apama applications, you can configure and use the HTTP client connectivity plug-in provided with Apama.

To add the HTTP client connectivity plug-in to a project

1. Invoke the Connectivity and Adapters dialog as described in Adding connectivity and adapter bundles to projects.

2. Expand the HTTP Client node and select the desired option.

   There are several options to choose from:

   • an option that uses application-specific event definitions, transports and mapping configurations, and

   • an option that uses generic Apama event definitions and a chain configuration to invoke HTTP services with JSON payloads. This option can be added only once and can be used to invoke multiple HTTP services. In the Project Explorer view, the following files are created in the Connectivity and Adapters > HTTP Client > HTTP_Client_bundle_instance node:

   • HTTP_Client_bundle_instance.properties

   • HTTP_Client_bundle_instance.yaml The HTTP_Client_bundle_instance.properties file contains properties for configuring the HTTP client transport.

   If you have selected the “generic” option, the above files are not created. This works without any configuration. All configuration options and mappings are provided at runtime through the EPL application.

3. Optional. If you have not selected the “generic” option, edit the HTTP_Client_bundle_instance.yaml file to specify more advanced configurations, such as customizing the way HTTP messages are mapped to Apama events, using codecs for converting the message payload, or configuring the HTTP client transport. For more information, see The HTTP Client Transport Connectivity Plug-in.

For the “generic” option, additional bundles are added to the Dependent Bundles node (you need not make any changes to these bundles). The HTTP client adds a reference to com.apama.util.AnyExtractor which is useful for easily extracting data from an any type; see the API reference for EPL (ApamaDoc) for more details.

Adding the Kafka connectivity plug-in to a project

In Apama applications, you can configure and use the Kafka connectivity plug-in provided with Apama.

To add the Kafka connectivity plug-in to a project

1. Add the Kafka connectivity plug-in as described in Adding connectivity and adapter bundles to projects.

   In the Project Explorer view, the following files are created in the Connectivity and Adapters > Kafka > Kafka_bundle_instance node:

   • Kafka_bundle_instance.properties
   • Kafka_bundle_instance.yaml

2. Double-click the Kafka_bundle_instance.yaml file to configure the Kafka connectivity plug-in. For more information, see The Kafka Transport Connectivity Plug-in.

Adding the Cumulocity connectivity plug-in to a project

In Apama applications, you can configure and use the Cumulocity connectivity plug-in provided with Apama.

To add the Cumulocity connectivity plug-in to a project

1. Invoke the Connectivity and Adapters dialog as described in Adding connectivity and adapter bundles to projects.

2. Expand the Cumulocity IoT node, select the desired bundle and configure it.

   You must select only one of the following bundles:

   • Cumulocity Notifications 2.0

     Info

     Cumulocity Notifications 2.0 is currently only available as a private preview. Request access from Cumulocity Operations.

     In the Project Explorer view, the following files are created in the Connectivity and Adapters > Cumulocity IoT > CumulocityNotifications2.0 node:

     • CumulocityIoTREST.properties

       Double-click this file to configure the connection details to your Cumulocity tenant.

     • CumulocityNotifications2.properties

       Double-click this file to configure receiving real-time notifications.

   • Cumulocity REST Support

     Info

     Only add this bundle if you are not receiving notifications in your project and just want to send to or query the Cumulocity Platform. If you want to receive notifications, add one of the other bundles instead.

     In the Project Explorer view, the following file is created in the Connectivity and Adapters > Cumulocity IoT > CumulocityRESTSupport node:

     • CumulocityIoTREST.properties

       Double-click this file to configure the connection details to your Cumulocity tenant.

   • Cumulocity Client

     Info

     The Cumulocity Client bundle connects using the deprecated long-polling mechanism. It is recommended that you use the Cumulocity Notifications 2.0 bundle instead.
     In the Project Explorer view, the following files are created in the Connectivity and Adapters > Cumulocity IoT > CumulocityClient node:

     • CumulocityIoT.properties

       Double-click this file to configure the Cumulocity connectivity plug-in.

     • CumulocityIoT.yaml

     Info

     It is strongly recommended that you do not change the CumulocityIoT.yaml file. You should always set the properties in the CumulocityIoT.properties configuration file, which defines the substitution variables to be used in the CumulocityIoT.yaml file.

   For further information, see The Cumulocity transport connectivity plug-in.

Removing a bundle instance

After adding a connectivity bundle or an adapter bundle that contains instance files, the instances can be removed or updated independently.

• To remove all the bundle instances, right-click the bundle and click Remove all instances. Click Yes.
• To remove only an instance of a bundle, right-click the bundle instance and click Remove instance(s). Click Yes.

Editing Apama files

Apama Plugin for Eclipse provides many features to help you write application code for monitor files (.mon) and event files (.evt).

Obtaining content assistance

To obtain content assistance, enter Ctrl+space in a blank line, or after one or more words in a line.

Apama Plugin for Eclipse displays a list of keywords or names that are valid in that location. For example, it might display a list of event types, standard functions, or actions. Double click the one you want or select with the arrow keys and press Enter.

To ensure that content assistance is always as up-to-date as possible, turn on automatic builds. Automatic builds ensure that when you add, delete, or change a project resource, Apama Plugin for Eclipse immediately builds the project. Building a project after a resource change ensures that content assistance has access to the most current resources. See Build automatically when a resource changes.

Using auto-completion

To have Apama Plugin for Eclipse automatically complete the word you are typing, enter Ctrl+space.

If you have entered enough characters so that there is only one possible completion, Apama Plugin for Eclipse inserts the rest of the word. If there are two or more possible completions, Apama Plugin for Eclipse displays a list of the completion candidates. Double-click the correct completion or select with the arrow keys and press Enter.

Apama Plugin for Eclipse displays only those completion candidates that are valid in the current context and scope.

To ensure that auto-completion is always as up-to-date as possible, turn on automatic builds. Automatic builds ensure that when you add, delete, or change a project resource, Apama Plugin for Eclipse immediately builds the project. Building a project after a resource change ensures that auto-completion has access to the most current resources. See Build automatically when a resource changes.

Displaying information for events and actions

When you position the mouse cursor to hover over an event declaration or action, a box pops up that displays the event type definition or the signature for the action.

Specifying comments

To toggle comment notation, click in a line or select one or more lines, and press Ctrl+/. Alternatively, you can adjust comment notation.

To adjust comment notation

1. Click in a line or select one or more lines.

2. Right-click anywhere in the code editor.

3. In the menu that appears, select Source and then one of the following:

   • Toggle comment — Inserts // comment notation if the selected line or lines is not a comment. Removes // comment notation if the selection is already a comment.
   • Add block comment — Inserts /* at the beginning of the section, and */ at the end of the selection.
   • Remove block comment — Removes the /* and */ notation.

Using auto-indent

To indent one or more lines relative to the entire EPL file

1. Click in a line or select one or more lines.

2. Press Ctrl+I.

   Alternative: Right-click in the code editor and select Source > Correct Indentation.

Using auto-bracketing

Auto-bracketing is enabled by default. This can be changed in the Apama preferences. See the description of the Apama preferences page EPL for further information.

When auto-bracketing is enabled, and you enter an opening bracket, brace or quotation mark, a matching closing bracket, brace or closing quotation mark is automatically inserted.

Using tabs

By default, tabs are inserted in the EPL editor when you press the Tab key.

This is defined in the Apama preferences. If you want to insert spaces instead, see the description of the Apama preference page Editor Formatting.

Defining shorthand (templates) for frequently used EPL code

EPL templates provide a way for you to define a short name for a longer pattern that you often specify in an EPL file. For example, Apama provides the dict template. When you enter dict followed by a space, dictionary<> is automatically inserted.

Apama provides some templates in Apama Plugin for Eclipse and you can define additional templates. Each Apama project can use all EPL templates.

The EPL templates are defined in the Apama preferences. For more information, see the description of the Apama preference page Editor Templates.

Sharing templates among Apama Plugin for Eclipse  installations

You can define templates in one Apama Plugin for Eclipse installation, and export them for use in another Apama Plugin for Eclipse installation.

To export templates and import them in another installation

1. In the source Apama project, define all the templates that you want to share. See Defining shorthand (templates) for frequently used EPL code.

2. Go to the Apama preferences and export them all. For more information, see the description of the Apama preference page Editor Templates.

3. Go to some other Apama Plugin for Eclipse installation.

4. Go to the Apama preferences of this installation and import the templates. For more information, see the description of the Apama preference page Editor Templates.

Specifying colors to distinguish EPL elements

In EPL files, the following colors are used by default to indicate the various parts of EPL code:

• Keywords are dark magenta.
• Types are red.
• Comments are green.
• Literal values are blue.
• Operators (+, –, =, and so on) are black.
• All other text is black.

These colors are defined in the Apama preferences. If you want to use different colors, see the description of the Apama preference page Editor Colors.

Shortcuts when editing Apama files

Apama Plugin for Eclipse provides the following shortcuts, in addition to the usual Eclipse shortcuts:

Navigating in Apama files

Navigating in Apama files

In addition to the usual Eclipse navigation tools, Apama Plugin for Eclipse lets you navigate to particular parts of an EPL file as described in the topics below.

You can use these features to navigate the code of EPL files (.mon).

Using the Outline view to navigate

In an Apama perspective, the Outline view displays the event types and monitors in the currently open .mon or .bdf file, showing event parameters and actions and monitor fields, actions, and listeners within actions. When you click an entry in the Outline view, the focus in the editor view jumps to the code that defines the item you clicked.

Apama Plugin for Eclipse updates the Outline view each time it saves your EPL file. If you add a resource to your EPL file but you do not save your file, the new resource does not appear in the Outline view until you save your file.

Using the Quick Outline to navigate

While you are viewing a .mon or.bdf file in the editor, you can use the Quick Outline to jump to an event type, monitor, or action. Press Ctrl+O or select Navigate > Quick Outline to display the Quick Outline. Apama Plugin for Eclipse pops up a list of event parameters and actions and monitor fields, actions, and listeners within actions for the current EPL file. Click an entry in the list to jump to the code that defines the item you click.

Jumping to an event or action definition or variable declaration

To jump to an event or action definition or variable declaration

1. Select a reference to the event, action, or variable whose declaration you want to view.

2. Press F3 or choose Navigate > Open Declaration from the Apama Plugin for Eclipse menu bar. Apama Plugin for Eclipse highlights the line that begins the declaration for the selected event or variable.

Opening EPL elements and Java classes using the Open Type dialog

Apama Plugin for Eclipse supports opening EPL elements and Java classes in the appropriate editor using the Open Type dialog. The Open Type dialog lists all the EPL elements and Java classes, and the locations of the files in the Apama project. For elements related to bundles, the status line displays the bundle name. You must be in one of the Apama perspectives to open the Apama-specific Open Type dialog.

To open an EPL element or a Java class

1. In Apama Plugin for Eclipse, click Navigate > Open Type or press Ctrl+Shift+T or click the () toolbar button.

2. Select the EPL element or the Java class.

   Info

   You can filter the list by typing the first characters to see all the elements/classes that start with that name.

3. Click OK.

   The selected EPL element or Java class opens in the appropriate editor.

Searching in Apama project files

You can search for event types in your project’s .mon or.bdf files.

To start a search

1. In the Developer or Workbench perspective, select Search > Search from the menu bar. In the Developer perspective, you can also click the Search icon (). The Search dialog appears. Ensure that the Apama Event Search tab is selected.

2. Type the event type you want to search for in the Event name (fully qualified) field. You can use wildcard characters and regular expressions in your search. Modify the search details as necessary, for example by specifying if the search should be case sensitive or if you want to limit the scope of the search. You can limit your search to event listeners, senders (route, send, etc.), definitions (where an event type is defined) and values (anywhere a value of a particular event type is used).

3. Click Search. Results are displayed in the Search view (Search tab), showing the files where the search term occurs and how many times it occurs. For more information on the Search tab, see Search tab.

Search tab

Apama search results are displayed in the Search view (Search tab), showing the files where the search term occurs and how many times it occurs.

To use the Search tab

1. To display the first occurrence of the search term, double click the file name or click the Show Next Match () button. This opens the file containing the term in the appropriate editor.

2. To navigate through all occurrences of the search term click the Show Next Match() and Show Previous Match() buttons.

Building Apama projects

In Apama Plugin for Eclipse, “building a project” refers to the process in which the project is validated, and any errors or warnings flagged to the user. This section describes the features Apama Plugin for Eclipse provides to control when Apama Plugin for Eclipse will build an Apama project.

Apama Plugin for Eclipse tries to complete each build. It does not stop when it finds an error. If Apama Plugin for Eclipse finds problems during validation, it indicates them as follows:

• In the Problems view, the error icon () appears at the beginning of each line that describes an error.
• In the Project view, the error icon () appears at the beginning of the name of a project that contains at least one file that is not valid.
• In the Project view, the error icon () also appears at the beginning of the name of each file that is not valid.
• In the file editor, the error icon () appears at the beginning of each line that contains an error.
• In the overview scroll bar to the right of the editing pane, regardless of how long the file is, a mark (()) appears for every error in the file. You can hover over a mark to view a description of the error that it flags, or you can click on any mark to display the line that contains that error.

Build automatically when a resource changes

Apama Plugin for Eclipse can automatically build a project whenever you add, delete, or change a resource in that project. This is the default and Apama strongly recommends that you leave this feature on. Building a project automatically ensures that content assistance menus are always up to date.

To toggle Build Automatically on or off

1. Select Project in the menu.

2. In the drop-down menu that appears, if a checkmark appears in front of Build Automatically, automatic builds are already turned on. Otherwise, select Build Automatically to turn it on.

Build all Apama projects

To validate all Apama projects in your workspace, choose Project > Build All from the menu bar.

Build one Apama project

To validate one Apama project

1. In the Project Explorer view, select the project you want to build.

2. In the menu bar, choose Project > Build Project.

Build a working set

When an Apama project is large, you might find it more efficient to build a subset of the project rather than the entire project. To build a subset of an Apama project, specify a working set that contains the files you want to build. Then build the working set you defined.

To define a working set

1. In the Apama Plugin for Eclipse menu bar, choose Project > Build Working Set > Select Working Set.

2. In the Select Working Set dialog, click New.

3. Double-click Resource.

4. Specify a name for this working set.

5. Expand the project(s) that contains the file(s) that you want to be in the working set.

6. Select the file(s) that you want to be in the working set, and click Finish.

7. Back in the Select Working Set dialog, select the working set you just defined and click OK.

To build this working set, choose Project > Build Working Set > working_set_name from the menu bar.

Clean and rebuild projects

When Apama Plugin for Eclipse cleans a project, it discards all build problems and build states.

To rebuild a project from scratch, as though you have never built it before

1. In the Apama Plugin for Eclipse menu bar, choose Project > Clean.

2. Indicate which projects you want to rebuild from scratch or select Clean all projects.

3. Click OK.

Configuring the project EPL build path

By default, Apama Plugin for Eclipse includes all of the EPL files in a project when building (and launching) it. However, for many applications it will be necessary to customize the EPL build path, adding additional files from outside the project (and less commonly, limiting the set of files under the project directory that will be included). The set of files under the project directory that will be built can be customized using the Source tab. Apama Plugin for Eclipse provides three ways to add additional files from outside the project to its EPL build path:

• Required Projects
• External EPL Dependencies
• Bundles

For information on the Java build path, see the Eclipse documentation. Also, see Specifying the classpath in deployment descriptor files.

Project source files

By default, all files in the project directory are included in the build path, but this can be customized. Files within a project are grouped into folders and you can specify which folders should be included when a project is built. In addition, within each folder you can specify patterns that determine which files should be included or excluded.

To specify the files

1. Right-click the project in Project Explorer and select Properties.

2. Expand Apama.

3. In the Properties dialog, select Apama Build Path, and click Source.

4. On the Source tab, add new folders and specify which files to include in the build process. For example, you can include all event files with the .evt extension. For folders in the project, you can also modify which files to include or exclude.

   To add a folder to the build process:

   1. Select the project and click Add Folder.

   2. At the Source Folder Selection dialog add checks to the check boxes for the folder you want to include in the build process.

      Add a new folder to the project, click Create New Folder to display the New Source Folder wizard.

   To specify files in the folders to include or exclude:

   1. On the Source tab, select the folder and click Edit.
   2. On the Edit Source folder dialog, click Next.
   3. At the Edit source folder dialog, in the Inclusion patterns and Exclusion patterns fields, click Add or Add Multiple.
      • If you click Add, enter the text patterns that will specify the files you want to include or exclude using the displayed wildcards.
      • If you click Add Multiple, select the names of the files you want to include or exclude.

Specifying projects

A project can make use of other Apama Plugin for Eclipse projects.

To add a project to the build process

1. Select the project that requires another project in the Project Explorer view, and select Project > Properties from the Apama Plugin for Eclipse menu.

2. Expand Apama.

3. In the Properties dialog, select Apama Build Path, and click Projects.

4. On the Projects tab, click Add to display the Required Project Selection dialog. Specify the projects to include in the build process.

   The Required Project Selection dialog displays all the projects managed by Apama. Projects with checks in their check boxes will be included when building the selected project.

Specifying external dependencies

When an EPL file in your project depends on an external EPL file, you must explicitly specify the dependency. For example, if you refer to event types or actions that are defined in other EPL files, you must specify the files that define those constructs. This ensures that Apama Plugin for Eclipse includes the external file in the validated project. It also ensures that the Apama Plugin for Eclipse builder, content assistance facility, and launcher have access to the most up-to-date version of each required file.

How you define dependencies depends on whether you are the only one using your project or you share the project with one or more users.

Specifying dependencies for a single-user project

When you are the only one using a project, specify a file that your EPL file depends on.

To specify the file

1. Right-click the project and click Properties.

2. In the Properties dialog, select Apama.

3. Click Apama Build Path.

4. Click External Dependencies.

5. Click Add External.

6. In the Add Apama External Dependency dialog, browse to the file your project requires.

7. Click OK in the Properties dialog to specify the dependency.

Specifying dependencies for a multi-user project

When Apama Plugin for Eclipse builds a project, it defines any dependencies in an XML file that hard codes the path to the external files. This works correctly if you do not share projects among multiple users. However, if two or more users share a project, they might not store external files in the same location.

If you are sharing projects among two or more users, you should use a variable to define an external file on which your EPL file depends. For example, Apama Plugin for Eclipse automatically defines APAMA_HOME and APAMA_WORK variables that can be used to locate files under either of those directories in a way that is independent of exactly where Apama has been installed on the current machine.

To use a variable to define a dependency

1. Right-click the project and click Properties.

2. In the Properties dialog, expand Apama.

3. Click Apama Build Path.

4. Click External Dependencies.

5. Click Add Variable.

6. In the New Variable Dependency Entry dialog, do one of the following:

   • If a variable already exists that identifies the required file, double-click that variable. Click OK. You can skip the remaining steps.
   • If you select a variable that represents a directory, click Extend to specify an EPL file that completes file dependency path that starts with a variable. The Variable Extension dialog appears. Navigate to the EPL file that your project is dependent on. Double-click the EPL file.
   • To define a new variable that identifies the required file, click Configure Variables and click New.
     1. In the New Variable Entry dialog, in the Name field, enter the name of the new variable. Use upper case names for build path variables.
     2. Click File or Folder and navigate to the appropriate folder or EPL file.
     3. Click OK in the Preferences dialog. Apama Plugin for Eclipse confirms that the classpath variables have changed, and prompts you to indicate whether you want to rebuild your project so that it can use the new variable. Click Yes.

Specifying the project bundles properties

The Bundles tab lists the bundle instances for a project in a tree form where the roots are bundles and branches are bundle instances. The tab contains these buttons:

• Add — Displays the Add Instance dialog where you can add a new bundle instance to the project.
• Update — Synchronize the bundles in the project.
• Remove — If the bundle has bundle instance files, Remove is enabled for the instances. If the bundle has no bundle instance files, Remove is enabled for the bundle itself.

To add a bundle to your project

1. In the Project Explorer view, right-click the project and select Properties.

2. In the Properties dialog, expand Apama and then click Apama Build Path.

3. Select the Bundles tab.

4. Click Add to display a list of Apama bundles.

5. Select the bundle you want to add.

6. Click OK twice.

Defining Apama Build Path variables

In any Apama project, you can define a variable that you can use in all your Apama projects. You might find it useful to define a variable in a situation where multiple users share the same project. If the project is dependent on one or more external files, not all users might have the external file stored in the same location. Each user defines a variable to specify the location of a shared file dependency.

You define an Apama project variable in the Apama preferences. For more information, see the description of the Apama preference page Apama Build Path Variables.

Importing projects

You can import Apama projects that have been created with Apama Plugin for Eclipse (see also Creating Apama projects) or with the apama_project tool (see also Creating and managing an Apama project from the command line).

To import an Apama project created on another machine into this Apama Plugin for Eclipse workspace

1. Select File > Import > General > Existing Projects into Workspace from the Apama Plugin for Eclipse menu. Click Next.

2. In Select root directory specify the root directory where the project is located.

3. Add a check box next to the project(s) you want to import.

4. Check the Copy projects into workspace checkbox if you want to copy all the project files into the workspace directory.

   Leave the check box unchecked if you want to simply link to the project in its current location instead.

If you have an Apama application that is not currently part of an Apama project:

1. Select File > New > Apama Project from the Apama Plugin for Eclipse menu.
2. Enter the name of the new project.
3. Uncheck the Use default location check box.
4. Specify the folder containing the files that you wish to import as a new project.
5. Click Finish.

A project that you import might have dependencies on environment variables, bundles, or functions that have not yet been added to Apama Plugin for Eclipse. As an alternative to explicitly adding each dependency, see Reusing dependency, variable and catalog configuration with extension (.ste) files.

Reusing dependency, variable and catalog configuration with extension (.ste) files

A project that you want to import into Apama Plugin for Eclipse might have dependencies on any of the following:

• Environment variables
• String substitutions

Before you can build your project, you would need to add each dependency to Apama Plugin for Eclipse. An alternative to adding each dependency is to define the dependencies in a file, and place the file in the root_install_dir\Designer\extensions folder. When Apama Plugin for Eclipse starts, it collects any files in its extensions folder and uses them to set up the Apama Plugin for Eclipse environment. When you then import your project, its dependencies are already in place.

Format of extensions file

A file in the extensions folder must have the .ste (Studio Tuning Extension) extension and the data it contains must be in the following format:

• Define each item to be added to Apama Plugin for Eclipse on its own line.
• The first value in each line must be the type of the item you want to add. The type must be one of the following:
  • STRING_SUBSTITUTION
  • VARIABLE
  • BUNDLE_CATALOG
• In each line, insert a semicolon between values.
• Insert # at the beginning of a line to make it a comment.
• The values you specify vary according to the specified type. Path specifications must be fully qualified; they cannot be relative. In a path specification, you can use a variable, which can be defined directly in Apama Plugin for Eclipse or in any .ste file. You can specify the items in any order.

  • For string substitutions, the substitution value cannot be edited or removed in Apama Plugin for Eclipse. For details, See Java development user guide > Reference > Preferences > Run/Debug > String Substitutions in the Eclipse help provided with Apama Plugin for Eclipse. If you specify any character other than R, the substitution value can be edited and removed from Apama Plugin for Eclipse. The format is as follows:

    STRING_SUBSTITUTION; variable_name; path; description; Char (R)
    

    For example:

    STRING_SUBSTITUTION; HOME; C:\MyApp; Install dir for my app; R
    

  • For variables, the variable’s value cannot be edited and the variable cannot be removed in Apama Plugin for Eclipse. If you specify any character other than R, the variable’s value can be edited and removed from Apama Plugin for Eclipse. The format is as follows:

    VARIABLE; variable_name; path; Char \(R\)
    

    For example:

    VARIABLE; HOME; C:\MyApp; R
    

  • For BUNDLE_CATALOG, the path to the bundle_catalog cannot be edited and cannot be removed in Apama Plugin for Eclipse. Define this BUNDLE_CATALOG variable in the .ste file when adding the bundle catalogs to Apama Plugin for Eclipse, and define the catalog as an extension of this BUNDLE_CATALOG variable. The format is as follows:

    BUNDLE_CATALOG; `path to the bundle_catalog folder`
    

    For example:

    BUNDLE_CATALOG; `C:\MyBundles`
    

Suppose you have a .ste file in place and you start Apama Plugin for Eclipse. If you subsequently modify the content of that .ste file, you must restart Apama Plugin for Eclipse for the changes to take effect.

Use the .properties file to define these external variables while using the engine_deploy utility. For more information about using the properties file, see Deploying a correlator.

Results of using an extensions file

After you define an extensions file, place it in the root_install_dir\Designer\extensions folder and then start Apama Plugin for Eclipse.

You should see the items you defined in the extensions file in the appropriate Apama Plugin for Eclipse dialogs.

If you import a project that uses any of the items specified in the extensions file then the imported project will be valid with regard to any of these dependencies.

Exporting project information

Exporting project information

You can export a project’s initialization file list, deployment script, correlator deployment packages, and adapter configurations.

Exporting a project initialization file list

To export a project initialization file list

1. Select File > Export from the Apama Plugin for Eclipse menu.

2. Expand Apama.

3. Select Project Initialization File List and click Next.

4. Select Include event files (*.evt) if you want the file list to contain all the event files from the project.

5. Specify a name for the file to hold the initialization file list and click Finish.

This creates an ordered list of the files on the project build path and saves it in a text file (with one entry per line).

Exporting to a deployment script (deprecated)

You can export an application’s launch configuration to create a deployment script. This generates the build files, configuration files, property definition files, scripts, and EPL files and copies other resources that are used by Ant to build and launch the project on a different machine.

To export an Apama launch configuration to a deployment script

1. In the Project Explorer view, right-click the name of the project and select Export from the pop-up menu.

2. In the Export dialog, expand Apama.

3. Select Apama Ant Export and click Next.

4. In the Ant Export dialog, specify the settings as follows:

   • Launch configuration — The export operation uses the project’s default launch configuration, but if a project has multiple launch configurations, you can select which one to export. If you want to select a different launch configuration, click Browse. This will display the Choose Launch Configuration dialog.

   • Destination directory — The name of the directory for the exported files.

   • Generate initialization list during launch — Dynamically creates the file injection list from the project directory when the exported deployment script is executed, rather than during the export process.

     When you select this option you need to export your project’s launch configuration only once. The generated scripts specify the location of your project directory and then use the content of your project directory to create the file injection list at deployment time. If you do not select this option, then you must re-export the configuration each time you add, remove or edit a file in your application.

     For JMon applications that you develop in Apama Plugin for Eclipse, Apama Plugin for Eclipse creates the required .jar files whenever you modify your Java files. If you do not develop your JMon application in Apama Plugin for Eclipse, see Generating deployment descriptor files from annotations for information about building the .jar file for your application. Ensure that your application’s.jar file is in your project directory before export.

     Info

     Apama’s in-process API for Java (JMon) is deprecated and will be removed in a future release.

     If you selected a shared location when you created the launch configuration that you are exporting, then Apama Plugin for Eclipse generates two files that contain the launch information (.deploy and .launch) and puts them in the specified shared location. After you create the launch configuration, any changes you make to the launch configuration are reflected in these files. Since the exported deployment script uses these files at deployment time, any launch configuration changes will also be reflected upon deployment. Except, if you change the shared location then you must re-export the launch configuration to a new Ant deployment script. If you do not, the old Ant deployment script fails because it cannot find the .deploy file.

     When Generate initialization list during launch is selected, the option Copy resources to destination is not available because the script points to the project directory.

   • Copy resources to destination — To copy the specific resources that Apama Plugin for Eclipse exports, click Browse to display the Export Resource Browser dialog and specify the resources you want.

   • Use relative paths — By default, the generated build.xml file uses relative pathnames for the application’s monitors, events, jars, and adapter configurations and properties. Uncheck this box if you want to use absolute pathnames.

   • Include custom file — If you want the exported launch configuration to perform other operations, select this option to generate a stub custom.xml file. The custom.xml file has pre-custom and post-custom targets where you can add the desired operations.

   • Batch resources when possible — By default, the build.xml file generated by the export operation specifies that all monitors in the project will be injected in a batch when the application is launched. If you want to inject each monitor separately when the application is launched, uncheck this check box.

   • Launch correlator in separate console — By default, the exported launch configuration will launch the correlator in a separate console. Uncheck this check box if you want to start the correlator in the console where the launch is started.

   • Generate Windows scripts — Exports all scripts used by the launch configuration in Windows form.

   • Generate Unix scripts — Exports all scripts used by the launch configuration in UNIX form.

   • Generate export log — By default the export operation generates a log file that records the export operation. Uncheck the check box if you do not want to record the log file. Click Finish. The files are generated in the specified destination directory.

Exporting correlator deployment packages

You can export a project’s EPL (.mon, .qry, .evt, and .cdp files) to a correlator deployment package (CDP). The CDP files use a proprietary, non-plaintext format that treats EPL files in a manner similar to the way a JAR file treats a collection of Java files.

If you want to create a CDP containing all the files for a given correlator, you can select the default launch configuration.

If you want to create a CDP containing only a subset of the project’s files, you must create a dedicated launch configuration before opening the CDP export wizard.

To export a CDP

1. In the Project Explorer view, right-click the project and select Export from the pop-up menu.

2. In the Export dialog, expand Apama.

3. Select Export as Correlator Deployment Package and click Next.

4. In the Correlator Deployment Package wizard:

   • Launch Configuration. Select the launch configuration that you want to export using the Browse button.
   • Correlator. Select the required correlator in the launch configuration from the drop-down list. If there are multiple correlators in the launch configuration, you must select the required correlator.
   • Package filename. Specifies the name of the CDP file you want to create. Use the Browse button to navigate to the desired location.

5. Click Finish.

For more information, see Deploying a correlator.

Exporting ApamaDoc

In Apama Plugin for Eclipse, you can use the ApamaDoc tool to generate reference documentation for the EPL source code you add to a project. From the Export dialog, select Apama > ApamaDoc Export. This generates static HTML pages that document the structure of all EPL code in a project.

For detailed information on how to annotate your EPL source code and generate ApamaDoc, see Generating documentation for your EPL code.

Deleting projects and resources

If you want to delete projects or resources you should use Apama Plugin for Eclipse to do so, rather trying to delete them directly from the file system.

Deleting resources

1. In the Project Explorer view or Workbench Project view, right-click the resource and select Delete from the pop-up menu or select the resource and select Edit > Delete from the menu. In the Workbench Project view you can select the resource and click the Delete button.

2. In the Confirm Resource Delete dialog, click Yes if you want to proceed.

Deleting projects

1. In the Project Explorer view or Workbench Project view, right-click the project and select Delete from the pop-up menu or select the resource and select Edit > Delete from the menu. In the Workbench Project view you can select the resource and click the Delete button.

2. In the Confirm Project Delete dialog select whether or not you want to delete all the project’s resources from the file system, or simply remove the project from the Project view leaving all files in place. After selecting the latter option, such projects can be added to the workspace again using the Import wizard (see Importing projects). In most cases it is more useful to select the option to delete the project’s contents at the same time as the project itself, to avoid confusion.

Adding the Apama nature to a project

If you are working with a project that is not an Apama project, for example, a Java project, you can apply the Apama nature to the project with Apama Plugin for Eclipse. The project then becomes an Apama project in addition to whatever natures it had before.

To add the Apama nature to a project

1. In the Project Explorer view (or in the Package Explorer view if the project is a Java project), right-click the project.

2. Select Apama > Add Apama Nature from the pop-up menu.

After you apply the Apama nature to a project, the project shares all the features of any other Apama project, for example, EPL errors will be detected and flagged, and the project can be launched in an Apama correlator.

Note that the Add Apama Nature menu item is not available if a project is already an Apama project.

Adding the Java nature to an Apama project

You can add two different types of Java nature to an Apama project:

• Java nature. The Java nature applies standard Eclipse Java support to an Apama project, so that all operations that can be performed on a normal Java project can also be performed on the Apama project.

  When a project has the Java nature, Apama Plugin for Eclipse:

  • Uses ApamaJavaLibrary to add all necessary JAR files to the project’s Java build path.
  • Creates and updates the jmon-jar.xml file. This is the deployment descriptor file required by each JMon application. Inside the correlator, the JVM processes the deployment descriptor file and uses it as a guide to the event types and monitor classes to load.
  • Generates and maintains your application’s JMon JAR file in the project_name java application files` folder of your project.
    Info

    Apama’s in-process API for Java (JMon) is deprecated and will be removed in a future release.

• Apama Java nature. The Apama Java nature enables the Apama project to use Apama’s Java API and adds support for various operations.

When you create a new Apama project, you can add these natures by selecting the corresponding options. See Creating Apama projects for further information.

If you want to add these natures to an existing Apama project, proceed as described below.

To add the Java or Apama Java nature to an existing project

1. In the Project Explorer, right-click the Apama project.

2. Click either Apama > Add Java Nature or Apama > Add Apama Java Nature.

Viewing all EPL objects in all projects

The EPL Objects view shows all the EPL objects - the Apama events and monitors - defined in the projects in your Apama Plugin for Eclipse workspace. These objects are the events and monitors that you define, as well the events and monitors defined in the Apama bundles that are included in your projects.

If the EPL Objects view is not displayed, from the Apama Plugin for Eclipse menu select Window > Show View > Other > Apama > EPL Objects.

When you double-click the name of an object in the EPL Objects view, the EPL file that defines the object appears.

The EPL Objects view organizes the display of EPL objects by project. You can display events and/or monitors. To specify what type of objects you want to display, click the View Menu icon on the view’s title bar (()) and from the drop-down menu, select Customize View and then either Events, Monitors, or Show All.

You can display the EPL objects in a project grouped by package name (Hierarchy).

You can also display the EPL objects in a project alphabetically (Flat).

To change the way the object names are displayed, click the View Menu icon on the view’s title bar and from the drop-down menu, select Group By and then either Hierarchy or Flat.

You can also specify a regular expression in the text box to filter the EPL entries shown in the view. For example, entering *test in the text box results in showing only entries with “test” in their names.

Click on the Refresh icon (()) in the view’s title bar to reload the entries in the EPL Objects view.

Internationalizing Apama applications

By default, Apama Plugin for Eclipse saves Apama project files in your platform’s native encoding. If you choose to save Apama project files in UTF-8 encoding in the Resource tab of a file or a folder’s Properties dialog, Apama Plugin for Eclipse adds a UTF-8 BOM character at the beginning of each file. This indicates that the contents are in UTF-8. The character is required to be compatible with other Apama tools.

To specify the encoding for Apama projects

1. In the Apama Project Navigator view, click the project for which you want to define the encoding.

2. In the Apama Plugin for Eclipse menu bar, choose Project > Properties.

3. In the Properties dialog, click Info.

4. In the Text File Encoding group box, click Other and select the encoding you want.

5. Click OK.

Checking the error log

While using Apama with Apama Plugin for Eclipse, you might receive a message that prompts you to check the error log. If the Error Log view does not already appear with the Problems, Tasks, and Console views, display it as described below.

See also Checking the Apama log file for Apama Plugin for Eclipse.

To display the Error Log view

1. From the Window menu, choose Show View > Other.

2. In the Show View dialog, expand General.

3. Double-click Error Log.

   The Error Log view is now shown.

Checking the Apama log file for Apama Plugin for Eclipse

For detailed information about any unexpected problems you may encounter while using Apama with Apama Plugin for Eclipse, see the Apama log file for Apama Plugin for Eclipse at APAMA_WORK\logs\apama_designer.log.

You can directly go to the location of the log file by clicking the corresponding link in the preferences. See Apama for more information.

Specifying an adapter configuration in a launch configuration

The Adapter Configuration dialog is used to edit configuration information for the selected adapter. You can supply information for the following fields:

• Adapter — Select the adapter from the list of available adapters in the drop-down list. This allows you to choose the adapter bundle instance that is configured in the project. This field is required.

• Port — The port that this adapter will run on.

• Properties — Select the properties file that is appropriate for the selected adapter. The properties file is used to supply actual values for the variables that are contained in the adapter configuration file. This field is required.

• Apama Messaging — Select this option when your application does not use Universal Messaging, and instead uses Apama channels and explicitly set connections between components.

  While it is possible for an adapter to use both Apama Messaging and UM Messaging, this is not recommended.

  Selection of Apama Messaging enables the <apama> element in the adapter’s configuration file. That is, it sets the APAMA_MSG_ENABLED substitution variable to true and sets the UM_MSG_ENABLED substitution variable to false. These values are used for launching the adapter.

  Selection of Apama Messaging has no impact if the adapter configuration does not use the APAMA_MSG_ENABLED and UM_MSG_ENABLED substitution variables.

• UM Messaging — Select this option when you want the deployed adapter to use Universal Messaging. If the project does not contain a Universal Messaging configuration properties file, this option is disabled.

  Selection of UM Messaging enables the <universal-messaging> element in the adapter’s configuration file. That is, it sets the UM_MSG_ENABLED substitution variable to true and sets the APAMA_MSG_ENABLED substitution variable to false. These values are used for launching the adapter.

  Selection of UM Messaging has no impact if the adapter configuration does not use the APAMA_MSG_ENABLED and UM_MSG_ENABLED substitution variables.

  Info

  Use of Universal Messaging from the IAF is deprecated and will be removed in a future release.

• Extra command-line options — Optionally, specify any additional arguments for starting the IAF process.

• Working directory — Identify the directory that will contain the files used to run the adapter.

Using Apama Plugin for Eclipse to configure adapters that use Universal Messaging

To configure an IAF adapter to use Universal Messaging

1. Add support for Universal Messaging to your project. Right-click the project and select Apama > Add UM Configuration to IAF.

2. Add one of the following adapters to your project:

   • File Adapter
   • JDBC Adapter
   • ODBC Adapter
   • Sim File Adapter

3. Open the instance of the adapter you just added. In the Settings tab, you can see the following substitution variables:

   • APAMA_MSG_ENABLED
   • UM_MSG_ENABLED Use Apama Plugin for Eclipse’s launch configuration editor to manage these substitution variables.

4. Select Run As > Run Configurations….

5. In the Run Configurations dialog, select the Apama project that contains the adapter you want to configure and then click the Components tab.

6. In the Components tab, double-click the adapter you want to configure.

   In the Adapter Configuration dialog, if you added Universal Messaging support to your project, the default for a new adapter in your project is that the UM Messaging radio button is selected. Adding Universal Messaging support to a project does not change an existing adapter configuration.

7. Ensure that UM Messaging is selected. This sets the related substitution variables as follows:

   • APAMA_MSG_ENABLED is false.
   • UM_MSG_ENABLED is true.

8. Click OK, Apply, and then Close to save the adapter configuration in that launch configuration.

Apama Plugin for Eclipse manages the APAMA_MSG_ENABLED and UM_MSG_ENABLED substitution variables by means of the launch configuration.

If you click the XML Source tab you can see that the <apama> element and the <universal-messaging> element each contain the enabled attribute. In the <apama> element, Apama Plugin for Eclipse sets the enabled attribute to the @APAMA_MSG_ENABLED@ substitution value. In the <universal-messaging> element, Apama Plugin for Eclipse sets the enabled attribute to the @UM_MSG_ENABLED@ substitution value. When you launch the project, Apama Plugin for Eclipse uses the settings of the APAMA_MSG_ENABLED and UM_MSG_ENABLED substitution variables to set the value of the enabled attribute in each element.

The default is that the enabled attribute is set to true. Consequently, if you delete the enabled attribute, it is as if it is set to true.

See also: Configuring IAF adapters to use Universal Messaging.