Using the Management interface

To use the Management interface, add the Correlator Management bundle to your Apama project. Alternatively, you can directly use the EPL interfaces provided in APAMA_HOME\monitors\Management.mon.

The Management interface provides the following actions for obtaining information about the correlator that the Management interface is being used in:

getHostname() - Returns the host name of the host the correlator is running on. The host name is dependent on the environment's name resolution configuration, and the name can be used only if the name resolution is correctly configured. The name is the same as that logged in the correlator log file, for example, dev3.acme.com.

getComponentName() - Returns the name that is used to identify the correlator. You can set this name by specifying the -N correlator command line flag (or by means of the extraArgs attribute in the ANT macros). The default name of the correlator is correlator.

These actions are defined in the com.apama.correlator.Component event. There are engine_management utility options that you can specify

The correlator also logs all of these values to its log file at startup.

In a persistence-enabled correlator, you can use the Management interface to request a snapshot to occur as soon as possible, and be notified of when that snapshot has been committed to disk. The Management interface lets persistent and non-persistent monitors create instances of Persistence events and then call the persist() action on those events.

When the correlator processes the persist() call it takes and commits a snapshot and executes the specified callback action at some point after the snapshot is committed. There are no guarantees about the elapsed time between the persist() call, the snapshot and the callback, especially when large amounts of correlator state are changing. Your code resumes executing immediately after the call to the persist() action. See Using Correlator Persistence.

The Management interface defines the Persistence event:

Consider the following sample code:

using com.apama.correlator.Persistence;
event Number {
integer i;
}

persistent monitor MyApplication {
integer counter := 0;
sequence<integer> myNumbers;

action onload() {
Number n;
on all Number(*):n {
myNumbers.append(n.i);
counter := counter + 1;
if(counter % 10 = 0) then {
doCommit();
}
}
}

action doCommit() {
Persistence p := new Persistence;
p.persist(logCommit);
}

action logCommit() {
log "Commit succeeded";
}
}

Because MyApplication is a persistent monitor the correlator copies its state to disk as that state changes. This monitor listens for Number events and stores their content in the myNumbers sequence. After every tenth Number event, the code executes the doCommit() action, which uses the Persistence event in the Management interface to request that the correlator commits persistent state to disk. When that commit has succeeded, the Management interface calls the action variable that was passed to the persist() action. This action writes "Commit succeeded" to the correlator log.

The Management interface guarantees that at the moment the callback action (logCommit() in this example) is executed, the state of all persistent monitors at a particular point in time will have been committed. The particular point in time is guaranteed only to be between the point at which persist() was called and the point at which the callback action was executed. For example, suppose the following event stream is being sent into the correlator:

At the point that Number(10) is received, the myNumbers sequence contains the ten items 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 and so the application initiates a snapshot commit. Suppose that the correlator suddenly terminates after notification of success appears in the log. When the correlator recovers, MyApplication has a myNumbers sequence that contains at least ten items. However, the sequence might contain 11 or even 12 items, if more Number events were received after the commit was requested but before the snapshot was actually taken. The correlator also persists state periodically, or as directed by other monitors that call the Management interface, so the sequence can be persisted at other points as well.