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.

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 data 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 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.

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.

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. 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:

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.

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.

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.

Routes an event that was external

Creates an event inside the correlator

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 Deploying and Managing Apama Applications, Event file format. For example:

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 calling the toString() method on each of the referenced event’s fields and catenating the individual return values into the result.

When you define an event type inside a monitor it has a fully qualified name. For 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.