Package com.apama.event

Class Event

  • public class Event
extends java.lang.Object
    An Event object representing an event instance in flat event string format and/or structured format (as defined by its associated EventType).

    To get a parsed Event object from an event string, call EventParser.parse(String) (or EventType.parse(String)); to build up an Event from a set of field values, start by using the Event(EventType) constructor.

    The event field values can be updated or retrieved by calling the setField(Field, Object) and getField(Field) methods respectively.

    See the com.apama.event.parser package documentation for an example of how event strings may be generated and parsed using this class.

    In order to make the Event "known" to the Correlator, the event definition must be injected to the correlator before any events of that type are sent into it.

    See Also:
    EventParser, EventType, FieldTypes, Field

    • Constructor Summary

      Constructors 
      Constructor Description
      Event​(EventType eventType)
      Constructor to create an Event based on an EventType.
      Event​(java.lang.String eventString)
      Constructor to create an Event based on a raw event string (for advanced uses only).
      Event​(java.lang.String eventString, java.lang.String channel)
      Constructor to create an Event based on a raw event string and channel string (for advanced uses only).

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getChannel()
      Method to retrieve the channel name for an event.
      EventType getEventType()
      Get the EventType for this Event.
      <T> T getField​(Field<T> fieldDefinition)
      Get the value of a field in this event instance.
      java.lang.Object getField​(java.lang.String name)
      Get the value of a field in this event instance.
      <T> T getField​(java.lang.String fieldName, FieldType<T> fieldType)
      Get the value of a field in this event instance.
      java.util.Map<java.lang.String,​java.lang.Object> getFieldsMap()
      Method to retrieve the fieldName/value map of the event fields.
      java.lang.String getName()
      Retrieve the name of the event type.
      java.lang.String getText()
      Retrieve the Apama string representation of the event.
      double getTime()
      Method to retrieve the timestamp for the event.
      void setChannel​(java.lang.String newChannel)
      Method to set the channel name for an event.
      void setEventParser​(EventParser eventParser)
      Method to set a user-provided EventParser.
      <T> Event setField​(Field<T> fieldDefinition, T value)
      Set the value of a field in this event instance.
      <T> Event setField​(java.lang.String fieldName, FieldType<T> fieldType, T value)
      Set the value of a field in this event instance.
      void setField​(java.lang.String name, java.lang.Object value)
      Set the value of a field in this event instance.
      void setTime​(double t)
      Method to set the timestamp for the event.
      java.lang.String toString()
      Retrieve the event's type and its contents as a String.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • Event

        public Event​(java.lang.String eventString,
             java.lang.String channel)
        Constructor to create an Event based on a raw event string and channel string (for advanced uses only).

        Note that this constructor is provided only for rare/advanced use cases such as needing an Event object to send to the Correlator based on an existing event string that was already generated by some other means. For more common use cases, the best way to get an Event from an event string is to call EventParser.parse(String) (or EventType.parse(String)), and the best way to build up an Event of a known type from a set of field values is the Event(EventType) constructor.

        No parsing will be performed until user makes the first request to the event field, for example by calling the setField() or getField() method. Once the parsing has taken place, the parsed fields will be stored in the Event object.

        The user is responsible for registering the corresponding EventType for this particular event with the EventParser before it will be able to parse events of that type (by calling setEventParser(EventParser); otherwise, the singleton EventParser.getDefaultParser() is used). Otherwise, a ParserRuntimeException will be thrown.

        Parameters:
        eventString - the event text (raw event). Can be null or "", in which case null or "" will be returned if user asked for the text with the getText() method
        channel - Channel name
        See Also:
        EventParser.parse(String), Event(EventType)

      • Event

        public Event​(java.lang.String eventString)
        Constructor to create an Event based on a raw event string (for advanced uses only).

        Note that this constructor is provided only for rare/advanced use cases such as needing an Event object to send to the Correlator based on an existing event string that was already generated by some other means. For more common use cases, the best way to get an Event from an event string is to call EventParser.parse(String) (or EventType.parse(String)), and the best way to build up an Event of a known type from a set of field values is the Event(EventType) constructor.

        No parsing will be performed until user makes the first request to the event field, for example by calling the setField() or getField() method. Once the parsing has taken place, the parsed fields will be stored in the Event object.

        The user is responsible for registering the corresponding EventType for this particular event with the EventParser before it will be able to parse events of that type (by calling setEventParser(EventParser); otherwise, the singleton EventParser.getDefaultParser() is used). Otherwise, a ParserRuntimeException will be thrown.

        Parameters:
        eventString - the event text (raw event). Can be null or "", in which case null or "" will be returned if user asked for the text with the getText() method
        See Also:
        EventParser.parse(String), Event(EventType)

      • Event

        public Event​(EventType eventType)
        Constructor to create an Event based on an EventType.
        Parameters:
        eventType - to use to create the Event

    • Method Detail

      • getText

        public java.lang.String getText()
        Retrieve the Apama string representation of the event.
        Returns:
        String containing the event's textual representation.

      • getEventType

        public EventType getEventType()
        Get the EventType for this Event.
        Returns:
        The EventType for this event. null if failure while parsing the event

      • getName

        public java.lang.String getName()
        Retrieve the name of the event type.
        Returns:
        the name of the event; null if eventText is null or empty

      • toString

        public java.lang.String toString()
        Retrieve the event's type and its contents as a String. This call is equivalent to getText().
        Overrides:
        toString in class java.lang.Object
        Returns:
        String containing the event's textual representation.

      • setEventParser

        public void setEventParser​(EventParser eventParser)
        Method to set a user-provided EventParser. If this method is not called, then the result of EventParser.getDefaultParser()) will be used for parsing the event.
        Parameters:
        eventParser - the eventParser for parsing the event.

      • setField

        public void setField​(java.lang.String name,
                     java.lang.Object value)
              throws ParserRuntimeException
        Set the value of a field in this event instance. Consider using the typesafe methods setField(Field, Object) or setField(String, FieldType, Object) instead of this method.

        The type of the value that must be provided depends on which Apama FieldType is associated with this field in the EventType definition. For example, if the field's type is a new SequenceFieldType(FloatFieldType.TYPE) then the value must be an object that implements the java.util.List interface, and contains Double objects for each float in the sequence. More information about the classes used to represent field values is available in the documentation for each com.apama.event.parser.*FieldType class.

        Parameters:
        name - the name of the field
        value - the value of the field. The specified value must be assignable to the Java type associated with the Apama FieldType for this field in the event definition. The null value is converted to default value for the FieldType associated with this field in the EventType definition. See defaultValue() method of the corresponding com.apama.event.parser.*FieldType class for more information about default value for this field.
        Throws:
        ParserRuntimeException - if there was a problem during initial parsing of a textual event, or if the specified field name is not a valid field in this event type.
        See Also:
        FieldType

      • setField

        public <T> Event setField​(Field<T> fieldDefinition,
                          T value)
                   throws ParserRuntimeException
        Set the value of a field in this event instance.
        Parameters:
        fieldDefinition - A field object representing the field's name and type.
        value - The value of the field. The null value is converted to default value for the FieldType associated with this field in the EventType definition. See defaultValue() method of the corresponding com.apama.event.parser.*FieldType class for more information about default value for this field.
        Returns:
        Returns the same Event instance that the method was called on, to make it easy to set several field values in a single statement.
        Throws:
        ParserRuntimeException - If there was a problem during initial parsing of a textual event, or if the specified field name is not a valid field in this event type.
        See Also:
        FieldType

      • setField

        public <T> Event setField​(java.lang.String fieldName,
                          FieldType<T> fieldType,
                          T value)
                   throws ParserRuntimeException
        Set the value of a field in this event instance.
        Parameters:
        fieldName - The name of the field.
        fieldType - The type of the field.
        value - The value of the field. The null value is converted to default value for the FieldType associated with this field in the EventType definition. See defaultValue() method of the corresponding com.apama.event.parser.*FieldType class for more information about default value for this field.
        Returns:
        Returns the same Event instance that the method was called on, to make it easy to set several field values in a single statement.
        Throws:
        ParserRuntimeException - If there was a problem during initial parsing of a textual event, or if the specified field name is not a valid field in this event type.
        See Also:
        FieldType

      • getField

        public java.lang.Object getField​(java.lang.String name)
                          throws ParserRuntimeException
        Get the value of a field in this event instance. Consider using the typesafe methods getField(Field) or getField(String, FieldType) instead of this method.

        The type of the value that is returned depends on which Apama FieldType is associated with the field in the EventType definition. For example, if the field's type is a new SequenceFieldType(FloatFieldType.TYPE) then the returned value will be an object that implements the java.util.List interface, and contains Double objects for each float in the sequence. More information about the classes used to represent field values is available in the documentation for each com.apama.event.parser.*FieldType class.

        If a value is not explicitly set then default value for the FieldType associated with this field in the EventType definition is returned. See defaultValue() method of the corresponding com.apama.event.parser.*FieldType class for more information about default value for this field.

        Parameters:
        name - the name of the field to retrieve
        Returns:
        the value, which will never be null
        Throws:
        ParserRuntimeException - if there was a problem during parsing of a event string, or if the specified field name is not a valid field in this event type.
        See Also:
        getField(Field), FieldType

      • getField

        public <T> T getField​(Field<T> fieldDefinition)
               throws ParserRuntimeException
        Get the value of a field in this event instance.
        Parameters:
        fieldDefinition - The field of interest. This is typically (but not necessarily) the Field object that was used to construct the EventType registered with the parser.
        Returns:
        The value, which will never be null.
        Throws:
        ParserRuntimeException - if there was a problem during parsing of a event string or if the specified field is not a valid field in this event type. An exception should never be thrown if the field exists and the event was parsed from an event string.
        See Also:
        getField(Field), FieldType

      • getField

        public <T> T getField​(java.lang.String fieldName,
                      FieldType<T> fieldType)
               throws ParserRuntimeException
        Get the value of a field in this event instance.
        Parameters:
        fieldName - The name of the field whose value should be retrieved.
        fieldType - The type of the field.
        Returns:
        The value, which will never be null.
        Throws:
        ParserRuntimeException - if there was a problem during parsing of a event string or if the specified field is not a valid field in this event type An exception should never be thrown if the field exists and the event was parsed from an event string.
        See Also:
        getField(Field), FieldType

      • getFieldsMap

        public java.util.Map<java.lang.String,​java.lang.Object> getFieldsMap()
                                                                    throws ParserRuntimeException
        Method to retrieve the fieldName/value map of the event fields.
        Returns:
        the Map containing the event fields. Keys are the field names in order and values are the corresponding field values. The resulting map should not be changed by the caller.
        Throws:
        ParserRuntimeException - if there was a problem during initial parsing of a textual event
        See Also:
        getField(String)

      • getTime

        public double getTime()
        Method to retrieve the timestamp for the event.

        This timestamp currently only has meaning for events which have been source from the correlator, in which case it is set to the correlator time at which it was created, or the value it was set to explicitly by code running within the correlator.

        To use the returned value with Java time and date routines, you will need to convert to milliseconds as a long.
        long millis = (long)(event.getTime() * 1000.0)
        Returns:
        the timestamp of the event

      • setTime

        public void setTime​(double t)
        Method to set the timestamp for the event.
        Parameters:
        t - the new timestamp of the event

      • getChannel

        public java.lang.String getChannel()
        Method to retrieve the channel name for an event.

        This currently only has meaning for events which have been sourced from the correlator, in which case it is set to the name of the channel the event was emitted from, or "" (the empty string) for the wildcard channel.

        Returns:
        the channel of the event.

      • setChannel

        public void setChannel​(java.lang.String newChannel)
        Method to set the channel name for an event.
        Parameters:
        newChannel - The new channel name.