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

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(string) — 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 that this method is called on. 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. For example:

event Foo {
   string bar;
   integer count;
}

monitor m {
   action onload() {
    print Foo.getFieldNames().toString();
    }
}

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

event Foo {
   string bar;
   integer count;
}

monitor m {
   action onload() {
   print Foo.getFieldTypes().toString();
   }
}

getFieldValues() — Returns a sequence of strings that contain the string versions of the event's field values. This method takes no parameters. The return value is of type sequence <string>. For string type fields, there is no quoting or escaping. You can call this method only on an event instance. For example:

event Foo {
   string bar;
   integer count;
}

monitor m {
   action onload() {
   Foo f:=Foo("Hello",1);
   print f.getFieldValues().toString();
}
}

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

event Foo {
string bar;
   integer count;
}

monitor m {
action onload() {
   print Foo.getName();
   }
}

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 context's time at the point at which the correlator performed the coassignment or added the event to a query window. Events that are routed, sent or enqueued will have their time updated to be the receiving context's current time when the event was processed (and thus coassigned) by that 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.

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. Typically, such an event came from an external event sender, triggered an event listener, and was coassigned to a monitor instance variable. A return value of true indicates an event that was generated by an external source.

When a monitor instance uses enqueue to send an event, then that event is considered to be generated by an external source. When a monitor uses route, send..to or enqueue..to, the isExternal() property of the event does not change. If an external event is received and then sent to another context using send..to, it will still be external (unless the event is copied with clone; see below).

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.

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(string) — 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:

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.

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.