Package rife.engine

Class ServerSentEvent

java.lang.Object
rife.engine.ServerSentEvent
public class ServerSentEvent extends Object
A ServerSentEvent object describes a single server-sent event that can be sent through an SseConnection or broadcast to all the connections of an SseBroadcaster.

All the fields are optional, since they will only be part of the event on the wire when they have been set. Events are built fluently: 

sse.send(new ServerSentEvent().name("update").id("42").data("changed"));

Data can be provided as text with data(), or as a Template or a single template block with template() and templateBlock(). Templates will be processed exactly like Context.print(Template) processes them, with all the filtered tags resolved against the context of each receiving connection, which makes them convenient for sending HTML fragments, for instance for the htmx sse extension.

Since:
1.10
See Also:

  • Constructor Details

    • ServerSentEvent

      public ServerSentEvent()

  • Method Details

    • name

      public ServerSentEvent name(String name)
      Sets the event name, which is transmitted as the event field.

      Browsers dispatch named events to the listener that was registered for that particular name.

      Parameters:
      name - the name of the event
      Returns:
      this event instance
      Throws:
      IllegalArgumentException - when the name contains line breaks
      Since:
      1.10
      See Also:

    • id

      public ServerSentEvent id(String id)
      Sets the event ID, which is transmitted as the id field.

      Browsers echo the last received ID back in the Last-Event-ID header when they reconnect, which can be retrieved with SseConnection.lastEventId().

      Event IDs that you set yourself are the reconnection strategy of your application. Broadcasters that have history enabled assign their own IDs and will refuse events that carry one.

      Parameters:
      id - the ID of the event
      Returns:
      this event instance
      Throws:
      IllegalArgumentException - when the ID contains line breaks or NUL characters, since browsers ignore IDs with NUL characters when they track their last event ID
      Since:
      1.10
      See Also:

    • retry

      public ServerSentEvent retry(int milliseconds)
      Sets the reconnection time in milliseconds, which is transmitted as the retry field.
      Parameters:
      milliseconds - the reconnection time in milliseconds
      Returns:
      this event instance
      Throws:
      IllegalArgumentException - when the reconnection time is negative
      Since:
      1.10

    • comment

      public ServerSentEvent comment(String comment)
      Adds a comment line to the event.

      Comments are ignored by browsers and are typically used as keep-alive heartbeats to prevent proxies from closing idle connections.

      Parameters:
      comment - the comment text
      Returns:
      this event instance
      Since:
      1.10
      See Also:

    • data

      public ServerSentEvent data(CharSequence data)
      Adds data to the event, which is transmitted as data fields.

      This method can be called multiple times, since each call adds another line of data. Data that itself contains line breaks will automatically be transmitted as multiple data fields.

      Parameters:
      data - the data to add
      Returns:
      this event instance
      Since:
      1.10
      See Also:

    • json

      public ServerSentEvent json(Object value)
      Adds the compact JSON representation of a value as the data of the event, which is transmitted as a data field.

      This accepts the same values as Json.toString(Object): strings, numbers, booleans, null, maps, collections, arrays, dates, temporals, enums, JsonObject and JsonArray. Beans and records are additionally converted through Json.from(java.lang.Object), as are the elements of collections.

      Since compact JSON contains no line breaks, the value will always be transmitted as a single data field, which clients can parse directly with JSON.parse(event.data).

      Parameters:
      value - the value whose JSON representation will be added as event data
      Returns:
      this event instance
      Since:
      1.10
      See Also:

    • template

      public ServerSentEvent template(Template template)
      Uses the content of a template as the data of the event.

      The template will be processed exactly like Context.print(Template) processes it, resolving all the filtered tags against the context of each connection that receives the event.

      A single trailing line break of the template content isn't transmitted, since it's a template file convention rather than meaningful event data.

      Parameters:
      template - the template whose content will be used as event data
      Returns:
      this event instance
      Since:
      1.10
      See Also:

    • templateBlock

      public ServerSentEvent templateBlock(Template template, String blockId)
      Uses the content of a single template block as the data of the event.

      The template will be processed exactly like Context.print(Template) processes it, after which only the content of the provided block is used, with the value assignments that are active at that moment.

      This makes it possible to maintain a page template and the event fragments that update it in the same template file.

      Parameters:
      template - the template that contains the block
      blockId - the ID of the block whose content will be used as event data
      Returns:
      this event instance
      Since:
      1.10
      See Also: