Debugging JMon Applications

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

This section describes practical information for developing and debugging JMon applications with Apama Plugin for Eclipse. General knowledge of Java and Apama application development is assumed.

Apama Plugin for Eclipse is built on the Eclipse IDE framework and as such running and debugging JMon applications for the Apama correlator engine is no more different than with any standard Java application. There are however a few things to consider:

  • Single thread — For JMon applications, the correlator uses a single thread of execution. When programming in Java consider the importance of maintaining determinism by not routing, emitting, or enqueueing an event in a thread other than the current thread. Java provides no guarantee on execution order for separate threads, so try to keep your JMon applications single threaded at all times. Although multiple threads are currently allowed for JMon applications, this might change in the future, with the correlator JVM issuing a warning or possibly an error.
  • Event definitions — To instantiate event definitions in your JMon application, the Event subclass in question needs to be defined and included in your JAR file. This is because the correlator uses a separate classloader for each application (that is, each JMon JAR file injected) and hence cannot share the event definitions across separate JMon applications. Also, a JMon application cannot make use of any event definition already present in the correlator. Any event definition (either a subclass of the JMon Event class or a definition in an EPL file) must be replicated for each JMon application and for your injected EPL files.

Preparing the correlator for remote debugging

Launching the correlator with the –j option enables the Java Virtual Machine (JVM) as a subprocess in correlator execution. When launching an Apama project in Apama Plugin for Eclipse, specification of the -j option launches the correlator and launches its JVM as an external process. Consequently, you must enable a socket connection to the JVM so that you can connect the Apama Plugin for Eclipse debugger to it. This also applies to launching a correlator through any other means.

Enable debugging in the correlator JVM by specifying the Java options for the correlator component in the launch configuration. The Java Debug Wire Protocol (JDWP) is the protocol used for communication between a debugger and the Java virtual machine (VM) that it debugs. Oracle’s VM implementations require command-line options to load the JDWP agent for debugging. JDWP is optional; it might not be available in some implementations of the Java™ 2 SDK. The existence of JDWP can allow the same debugger to work.

From Java 5.0 (or 1.5.0) onwards, specify the -agentlib:jdwp option to load and specify options to the JDWP agent. For Java releases prior to 5.0, the -Xdebug and -Xrunjdwp options are used. (The 5.0 implementation also supports the -Xdebug and -Xrunjdwp options but the newer -agentlib:jdwp option is preferable as the JDWP agent in 5.0 uses the JVMTI interface to the VM rather than the older JVMDI interface.) Specify this option in the correlator component in your launch configuration or when launching the correlator independently:

-J -agentlib:jdwp=transport=dt_socket,address=8787,server=y,suspend=n

This tells the JVM to use a socket transport on port 8787. You can change this at will and use your own options. For more Java debugging/agent options, see https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/conninv.html#Invocation.

To launch the correlator with Java and remote debugging enabled, you can use a command line or Apama Plugin for Eclipse.

On the command line, invoke the correlator with the following arguments:

correlator -l ApamaServerLicense.xml -j -J
-agentlib:jdwp=transport=dt_socket,address=8787,server=y,suspend=n

In Apama Plugin for Eclipse, invoke the correlator as follows:

  1. From the Apama Plugin for Eclipse menu, select Run > Run Configurations.

  2. Click the Components tab.

  3. Select the correlator you want to start and click Edit.

  4. Enter the following in the Extra command line arguments field:

    -J -agentlib:jdwp=transport=dt_socket,address=8787,server=y,suspend=n

  5. Select OK and then Run to start the correlator.

The correlator is now enabled for Java debugging. The next section discusses how to connect to the correlator with the Apama Plugin for Eclipse debugger.

Creating a debug run configuration

After you have a running correlator that is enabled for remote debugging, you must create a debug run configuration that you use to connect to the correlator:

To create a debug run configuration

  1. From the Apama Plugin for Eclipse menu, select Run > Debug Configurations.

  2. In the Debug dialog, on the left, select Remote Java Application.

  3. From the Debug dialog toolbar, select New launch configuration(Icon).

  4. Select the Connect tab, if it is not already selected.

  5. Enter a name for your project and set the host and port for the remote JVM connection you previously specified as Java options when you started the correlator.

  6. Click the Source tab and add the path to the Java source for your JMon application.

  7. Click Apply and then Debug.

This launch configuration immediately connects to the remote JVM process in the correlator and Apama Plugin for Eclipse switches to the Apama Runtime perspective, which you use for debugging. You are now ready to remotely debug your JMon application. Debugging a JMon application in Apama Plugin for Eclipse is the same as debugging any other Java application in Eclipse.

Debug perspective

The Debug perspective appears automatically when you start a debug session. The default Debug perspective has five panels that you can use for debugging:

Using the Debug view with a JMon application

The Debug view shows the call stack and status of current threads, including any threads that have already run to completion. Whenever execution reaches a breakpoint, the current thread in the Debug view is highlighted.

This view provides code execution controls. These allow you to suspend and resume execution, step through breakpoints in various ways, jump between stack frames, connect/disconnect to remote JVMs process, and so on. See the Eclipse online help for detailed information on this view.

Working with breakpoints in a JMon application

You can set breakpoints in your code in a number of ways. The most straightforward way is to select a line in your Java code and double-click on the gray area to the left of the line. This sets a breakpoint before the execution of that line. The debugger will suspend execution when it reaches that line, allowing you to inspect variable values and results of expressions, either as defined in the code or created by you in real-time. These expressions can also be used in conditions for breakpoints.

You can set breakpoints on particular Java exceptions, on particular line numbers, on particular method calls, on conditions such as after a certain number of hits on a particular statement, and so on.

The Breakpoints view allows you to view and control all your currently defined breakpoints. After execution reaches a breakpoint, you can control process execution by stepping forwards or backwards through your code execution, or by simply resuming execution until the next breakpoint or until your program terminates.

See the Eclipse online help for detailed information on this view.

Viewing stack frame variables for a JMon application

When selecting a particular stack frame in the Debug view, the Variables view lets you inspect all variables as defined in the current stack context. Of course, you can also view variables alongside other variable values (globals, constants, and so on) if they are specified in the options. See the Eclipse online help for detailed information on this view.

Additional resources for Java debugging

This section introduces the basic concepts for debugging JMon applications in Apama Plugin for Eclipse. There are a number of Apama Plugin for Eclipse debugging features not mentioned, but the mechanisms are essentially the same as for other Java applications. For additional information about available debugging options, see the following Eclipse information: