Sending events is accomplished by obtaining an SseSink instance from a ServerResponse using the SseSink.TYPE constant. The following example converts the response into an SseSink, emits two string messages and then closes the connection.

try (SseSink sseSink = res.sink(SseSink.TYPE)) {
    sseSink.emit(SseEvent.create("hello"))
            .emit(SseEvent.create("world"));
}

Once an SseSink is obtained from a ServerResponse, the latter is no longer usable to send additional data to the client given that response Content-Type will be automatically set to text/event-stream. Note that an SseSink is auto closeable, so it can be part of a try-with-resources block as shown above.

Events can be created using any of the static create methods in SseEvent as well as via a builder obtained by calling SseEvent.builder(). For more information see the Javadocs for those classes. In the example above, a simple create method with a string param is used to showcase a very common use case. The API supports integration with media type providers, so the event data may actually be of any type as long as it is possible to convert it to a string value.

It is possible to serialize event data using the media support. For example, if JSON-P is available in your class path, you can create an SSE event from a JsonObject and Helidon will find the appropriate media converter and serialize the event data on your behalf.

JsonObject json = Json.createObjectBuilder()
        .add("hello", "world")
        .build();
try (SseSink sseSink = res.sink(SseSink.TYPE)) {
    sseSink.emit(SseEvent.create(json));
}

Similarly, if JSON-B support is available in your class path, an event can be created from an arbitrary Java class and serialized as shown next:

class HelloWorld {

    private String hello;

    public String getHello() {
        return hello;
    }

    public void setHello(String hello) {
        this.hello = hello;
    }
}

void handle(ServerRequest req, ServerResponse res) {
    HelloWorld json = new HelloWorld();
    json.setHello("world");
    try (SseSink sseSink = res.sink(SseSink.TYPE)) {
        sseSink.emit(SseEvent.create(json));
    }
}

An optional media type can be specified alongside the event’s data, in case a different type of serialization is required or when multiple media converters are available in the class path. For example, when passing a Java instance, you may request XML instead of JSON serialization by using application/xml as the event’s media type.

Receiving events is accomplished by providing an SseSource handler using the source type SseSource.TYPE. An SseSource is a functional interface defined for the purpose of processing events. The following example, obtains an Http1ClientResponse from a request and registers an SseSource to process a single event.

try (Http1ClientResponse r = client.get("/sseJson")
        .header(ACCEPT_EVENT_STREAM)
        .request()) {
    CountDownLatch latch = new CountDownLatch(1);
    r.source(SseSource.TYPE, event -> {
        // ...
        latch.countDown();
    });
}

The SseSource type defines other methods such as onOpen, onClose and onError. The following example waits for zero or more string events until the connection is closed. A CountDownLatch is a convenient way to asynchronously wait until all the events are received.

try (Http1ClientResponse r = client.get("/sseString")
        .header(ACCEPT_EVENT_STREAM)
        .request()) {
    CountDownLatch latch = new CountDownLatch(1);
    r.source(SseSource.TYPE, new SseSource() {
        @Override
        public void onEvent(SseEvent event) {
            // ...
        }

        @Override
        public void onClose() {
            latch.countDown();
        }
    });
    assertThat(latch.await(5, TimeUnit.SECONDS), is(true));

The Client API is also integrated with media type support. The data received as part of an event can be deserialized using any of the media converters available in your class path. There are special methods in SseEvent for this purpose. Without a parameter, the method data() in SseEvent will always return a string. Other types can be requested using data(Class<T>) and data(Class<T>, MediaType). The latter is necessary to select the correct media converter given that there is no (standard) content type available as part of each event --but only a single text/event-stream content type for the whole response.

For example, to convert an event into a Java instance using JSON-B, the application/json media type is required as a second parameter --the first parameter HelloWorld.class simply does not convey sufficient information to select the appropriate converter for the event’s data in this case.

try (Http1ClientResponse r = client.get("/sseJson")
        .header(ACCEPT_EVENT_STREAM)
        .request()) {
    CountDownLatch latch = new CountDownLatch(1);
    r.source(SseSource.TYPE, event -> {
        HelloWorld json = event.data(HelloWorld.class, MediaTypes.APPLICATION_JSON);
        // ...
        latch.countDown();
    });
}