event
Values of the event type are data objects that can represent notifications of something happening, such as a customer order, shipment delivery, sensor state change, stock trade, or myriad other things. Event objects can also be used as a container or structure for holding several related data values.
Usage
Each kind of event has a type name and one or more data elements, called event fields, associated with it. An event can also have blocks of executable code, called actions, associated with it.
A field in an event can be any Apama type. If an event contains a field of type action, chunk, listener, or stream, you cannot specify that event in an event template, and you cannot send, emit, route or enqueue that event.
Two events are equal if corresponding members are equal. If corresponding members are not equal then the events are ordered according to the first member that differs.
The correlator orders events by considering the event’s fields in order.
An
event variable can be a potentially cyclic type, a type that directly or indirectly refers to itself. For details about the behavior of such objects, see
Potentially cyclic types.
Methods
The following methods may be called on variables of event type and on event types:
canParse() — this method is available only on events that are parseable. Returns
true if the string argument can be successfully parsed to create an event object. For more information about the parseable type property, see the table in
Type properties summary.
clone() – returns a new
event that is an exact copy of the
event. All the
event’s contents are cloned into the new
event, and if they were complex types themselves, their contents are cloned as well. Takes no parameters.
When the event you are cloning is a potentially cyclic type, the correlator preserves multiple references, if they exist, to the same object. That is, the correlator does not create a copy of the object to correspond to each reference. See also
Potentially cyclic types.
getFieldNames() – returns a
sequence of strings that contain the field names of an event type. This method takes no parameters. The return value is of type
sequence <string>. You can call this method on an event type or on an instance of an
event type.
getFieldTypes() – returns a sequence of strings that contain the type names of an event type’s fields. This method takes no parameters. The return value is of type
sequence <string>. You can call this method on an event type or on an instance of an
event type.
getFieldValues() – returns a sequence of strings that contain the field values of an event. This method takes no parameters. The return value is of type
sequence <string>.
getName() – returns a
string whose value is an event’s type name. This method takes no parameters. You can call this method on an event type or on an instance of an
event type.
getTime() – returns a
float that indicates a time expressed in seconds since the epoch, January 1st, 1970. The particular time returned is as follows:
If the correlator created this event, the
getTime() method returns the time that the correlator created the event. This is the creation time in the context in which the correlator created the event.
Coassignment sets the timestamp of an event. A call to
getTime() on a coassigned event returns the time that the correlator performed the coassignment. This is the time in the context in which the correlator performed the coassignment and it can be the time the event was received or routed or added to a query window. For an enqueued event, a call to
getTime() returns the receiving context’s current time when the enqueued event arrived in the context.
An event’s timestamp might not match the time when an event listener for that event fires. For example, consider the following:
on A():a and B():b {
...
}
Suppose that currentTime is 1 when the correlator processes A and currentTime is 2 when the correlator processes B. A call to a.getTime() returns 1, while a call to b.getTime() returns 2. Of course, the event listener fires only after processing B.
Caution! In the Software AG Designer code editor, you might notice the
setTimeDeep() method, which can be invoked on
event type variables. This method is for internal use only. You should not invoke this method without assistance from Software AG Global Support. If you will be sending
&TIME events to externally control time in the correlator then use the
&SETTIME event to specify the start time. See
Setting the time in the correlator (&SETTIME event).
isExternal() – returns a
boolean that indicates whether the event was generated by an external source. Such an event came from an external event sender, triggered an event listener, and was coassigned to a monitor instance variable. When a monitor instance enqueues an event, this event is considered to be generated by an external source.
A return value of true indicates an event that was generated by an external source.
When the correlator spawns a monitor instance, it preserves the value that the isExternal() method returns. In other words, if you coassign an external event in a monitor instance, and then spawn that monitor instance, the isExternal() method returns true in the spawned monitor instance.
This method takes no parameters.
The isExternal() method returns false when a monitor instance
Routes an event that was external
Creates an event inside the correlator
Clones an event
This method is useful when you need to determine whether an event came from outside or was in some way derived inside the correlator. Although this distinction is often clear from the event type, that is not always the case.
parse() – this method is available only on events that are parseable. Returns the
event object represented by the
string argument. For more information about the parseable type property, see the table in
Type properties summary. You can call this method on an event type or on an instance of an
event type. The more typical use is to call
parse() directly on the event type.
The
parse() method takes a single string as its argument. This string must be the string form of an
event object. The string must adhere to the format described in
Event file format. For example:
A a := new A;
a := A.parse("A(10, \"foo\")");
You can specify the parse() method after an expression or type name. If the correlator is unable to parse the string, it is a runtime error and the monitor instance that the EPL is running in terminates.
When an event is a potentially cyclic type, the behavior of the
parse() method is different. See
Potentially cyclic types.
toString() – returns a
string representation of the event. Takes no parameters. The return value is constructed by concatenating the string representation of the referenced event's fields.
When you define an event type inside a monitor it has a fully qualified name. For example:
monitor Test
{
event Example{}
}
The fully qualified name for the Example event type is Test.Example and the toString() output for the event name is "Test.Example()".
When an event is a potentially cyclic type, the behavior of the
toString() method is different. See
Potentially cyclic types.
Also, you can define your own actions on events.