Package com.launchdarkly.eventsource

Class MessageEvent

java.lang.Object
com.launchdarkly.eventsource.MessageEvent
All Implemented Interfaces:
StreamEvent
public class MessageEvent extends Object implements StreamEvent
Information about a message received from the stream.

The properties of a message are defined by the SSE specification. Every message has an event name set by the "event:" field (DEFAULT_EVENT_NAME if not specified), a data string set by "date:" fields, an optional last event ID string (set by the "id:" field and defaulting to the same value until it is set again), and an origin URI (always the same stream URI).

  • Field Details

    • DEFAULT_EVENT_NAME

      public static final String DEFAULT_EVENT_NAME
      The default value of getEventName() for all SSE messages that did not have an event field. This constant is defined in the SSE specification.
      Since:
      2.6.0
      See Also:

  • Constructor Details

    • MessageEvent

      public MessageEvent(String data)
      Simple constructor with event data only, using the default event name.

      This constructor assumes that the event data has been fully read into memory as a String.

      Parameters:
      data - the event data; if null, will be changed to an empty string

    • MessageEvent

      public MessageEvent(String data, String lastEventId, URI origin)
      Constructs a new instance with the default event name.

      This constructor assumes that the event data has been fully read into memory as a String.

      Parameters:
      data - the event data; if null, will be changed to an empty string
      lastEventId - the event ID, or null if none
      origin - the stream endpoint

    • MessageEvent

      public MessageEvent(String eventName, String data, String lastEventId, URI origin)
      Constructs a new instance.

      This constructor assumes that the event data has been fully read into memory as a String.

      Parameters:
      eventName - the event name; if null, DEFAULT_EVENT_NAME is used
      data - the event data; if null, will be changed to an empty string
      lastEventId - the event ID, or null if none
      origin - the stream endpoint
      Since:
      2.6.0

    • MessageEvent

      public MessageEvent(String eventName, String data, String lastEventId, URI origin, ResponseHeaders headers)
      Constructs a new instance with response headers.

      This constructor assumes that the event data has been fully read into memory as a String.

      Parameters:
      eventName - the event name; if null, DEFAULT_EVENT_NAME is used
      data - the event data; if null, will be changed to an empty string
      lastEventId - the event ID, or null if none
      origin - the stream endpoint
      headers - the response headers from the current connection, or null if not available
      Since:
      4.2.0

    • MessageEvent

      public MessageEvent(String eventName, Reader dataReader, String lastEventId, URI origin)
      Constructs a new instance with lazy-loading behavior.

      This constructor takes a Reader instead of a String for the event data. This is an optimization that sometimes allows events to be processed without large buffers. The caller must be careful about using this model because the behavior of the reader is not idempotent; see getDataReader().

      Parameters:
      eventName - an object that will provide the event name if requested
      dataReader - a Reader for consuming the event data
      lastEventId - an object that will provide the last event ID if requested
      origin - the stream endpoint
      Since:
      2.6.0
      See Also:

    • MessageEvent

      public MessageEvent(String eventName, Reader dataReader, String lastEventId, URI origin, ResponseHeaders headers)
      Constructs a new instance with lazy-loading behavior and response headers.

      This constructor takes a Reader instead of a String for the event data. This is an optimization that sometimes allows events to be processed without large buffers. The caller must be careful about using this model because the behavior of the reader is not idempotent; see getDataReader().

      Parameters:
      eventName - an object that will provide the event name if requested
      dataReader - a Reader for consuming the event data
      lastEventId - an object that will provide the last event ID if requested
      origin - the stream endpoint
      headers - the response headers from the current connection, or null if not available
      Since:
      4.2.0
      See Also:

    • MessageEvent

      public MessageEvent(String eventName, String data)
      Constructs a new instance.
      Parameters:
      eventName - the event name
      data - the event data, if any

  • Method Details

    • getEventName

      public String getEventName()
      Returns the event name. This is the value of the event field in the SSE message, or, if there was none, the constant DEFAULT_EVENT_NAME.
      Returns:
      the event name
      Since:
      2.6.0

    • getData

      public String getData()
      Returns the event data as a string.

      The format of event data is described in the SSE specification. Every event has at least one line with a data or data: prefix. After removing the prefix, multiple lines are concatenated with a separator of '\n'.

      If you have set the EventSource.Builder.streamEventData(boolean) option to true to enable streaming delivery of event data to your handler without buffering the entire event, you should use getDataReader() instead of getData(). Calling getData() in this mode would defeat the purpose by causing all of the data to be read at once. However, if you do this, getData() memoizes the result so that calling it repeatedly does not try to read the stream again.

      The method will never return null; every event has data, even if the data is empty (zero length).

      Returns:
      the data string

    • getDataReader

      public Reader getDataReader()
      Returns a single-use Reader for consuming the event data.

      This is meant to be used if you have set the option EventSource.Builder.streamEventData(boolean) to true, indicating that you want to consume the data with a streaming approach, rather than buffering the full event in memory. In this mode, getDataReader() returns a Reader that consumes the event data while it is being received. The format is the same as described in getData() (for instance, if the data was sent in multiple lines, the lines are separated by '\n'). Because this Reader is connected directly to the HTTP response stream, it is only valid until you read the next message.

      See EventSource.Builder.streamEventData(boolean) for more details and important limitations of the streaming mode.

      If you have not set that option, then the returned Reader simply provides the same already-buffered data that would be available from getData().

      This Reader can be used only once; if you have already consumed the data, further calls to getDataReader() will return the same instance that will not read any more.

      The method will never return null; every event has data, even if the data is empty (zero length).

      If the stream connection is closed before a complete SSE message has been received (that is, before the usual blank line that would terminate a message), then instead of a normal EOF, the Reader will throw a StreamClosedWithIncompleteMessageException. If this happens, the application should generally discard the entire MessageEvent and not try to process it further.

      Returns:
      a reader for the event data
      Since:
      2.6.0

    • getLastEventId

      public String getLastEventId()
      Returns the event ID, if any.
      Returns:
      the event ID or null

    • getOrigin

      public URI getOrigin()
      Returns the endpoint of the stream that generated the event.
      Returns:
      the stream URI

    • getHeaders

      public ResponseHeaders getHeaders()
      Returns the response headers from the current connection, or null if not available.

      For HTTP connections, this contains the HTTP response headers that were received when the connection was established. These headers remain the same for all events received on this connection.

      Returns:
      the response headers, or null if not available
      Since:
      4.2.0

    • isStreamingData

      public boolean isStreamingData()
      Returns true if this event was dispatched with streaming data behavior rather than pre-read data.

      This is only the case if you have set the EventSource.Builder.streamEventData(boolean) option to true.

      Returns:
      true if the event has streaming data
      Since:
      2.6.0

    • close

      public void close()
      Indicates that you are finished with this message.

      This method is only relevant if you are using streaming data mode. It tells EventSource that you will not be using the getDataReader() stream any more and that any remaining data for this event should be skipped.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object