org.glassfish.jersey.media.sse

Class EventSource

java.lang.Object

org.glassfish.jersey.media.sse.EventSource

All Implemented Interfaces:

EventListener

public class EventSource
extends Object
implements EventListener

Client for reading and processing incoming Server-Sent Events.

Once an EventSource is created, it opens a connection to the associated web target and starts processing any incoming inbound events.

Whenever a new event is received, an onEvent(InboundEvent) method is called as well as any registered event listeners are notified (see register(EventListener) and register(EventListener, String, String...).

Instances of this class are thread safe.

Author:

Pavel Bucek (pavel.bucek at oracle.com), Marek Potociar (marek.potociar at oracle.com)

Constructor Summary

Constructors

Constructor and Description
EventSource(WebTarget target) Create new SSE event source and open a connection it to the supplied SSE streaming web target.
EventSource(WebTarget target, boolean open) Create new SSE event source pointing at a SSE streaming web target.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Close this event source.
boolean	close(long timeout, TimeUnit unit) Close this event source and wait for the internal event processing task to complete for up to the specified amount of wait time.
boolean	isOpen() Check if this event source instance is open.
void	onEvent(InboundEvent inboundEvent) Called when InboundEvent is received.
void	open() Open the connection to the supplied SSE underlying web target and start processing incoming events.
void	register(EventListener listener) Register new event listener to receive all streamed SSE events.
void	register(EventListener listener, String eventName, String... eventNames) Add name-bound event listener which will be called only for incoming SSE events whose name is equal to the specified name(s).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EventSource

public EventSource(WebTarget target)
            throws NullPointerException

Create new SSE event source and open a connection it to the supplied SSE streaming web target.

The created event source instance automatically opens a connection to the supplied SSE streaming web target and starts processing incoming events.

The incoming events are processed in an asynchronous task running in an internal single thread executor.

Parameters:

target - SSE streaming web target. Must not be null.

Throws:

NullPointerException - in case the supplied web target is null.

EventSource

public EventSource(WebTarget target,
           boolean open)

Create new SSE event source pointing at a SSE streaming web target.

If the supplied open flag is true, the created event source instance automatically opens a connection to the supplied SSE streaming web target and starts processing incoming events. Otherwise, if the open flag is set to false, the created event source instance is not automatically connected to the web target. In this case it is expected that the user who created the event source will manually invoke its open() method.

The incoming events are processed in an asynchronous task running in an internal single thread executor.

Parameters:

target - SSE streaming web target. Must not be null.

Throws:

NullPointerException - in case the supplied web target is null.

Method Detail

open

public void open()
          throws IllegalStateException

Open the connection to the supplied SSE underlying web target and start processing incoming events.

Throws:

IllegalStateException - in case the event source has already been opened earlier.

isOpen

public boolean isOpen()

Check if this event source instance is open.

Returns:

true if this event source is open, false otherwise.

register

public void register(EventListener listener)

Register new event listener to receive all streamed SSE events.

Parameters:

listener - event listener to be registered with the event source.

See Also:

register(EventListener, String, String...)

register

public void register(EventListener listener,
            String eventName,
            String... eventNames)

Add name-bound event listener which will be called only for incoming SSE events whose name is equal to the specified name(s).

Parameters:

listener - event listener to register with this event source.

eventName - inbound event name.

eventNames - additional event names.

See Also:

register(EventListener)

onEvent

public void onEvent(InboundEvent inboundEvent)

Called when InboundEvent is received.

The default EventSource implementation is empty, users can override this method to handle incoming InboundEvents.

Note that overriding this method may be necessary to make sure no InboundEvent incoming events are lost in case the event source is constructed using EventSource(javax.ws.rs.client.WebTarget) constructor or in case a true flag is passed to the EventSource(javax.ws.rs.client.WebTarget, boolean) constructor, since the connection is opened as as part of the constructor call and the event processing starts immediately. Therefore any EventListeners registered later after the event source has been constructed may miss the notifications about the one or more events that arrive immediately after the connection to the event source is established.

Specified by:

onEvent in interface EventListener

Parameters:

inboundEvent - received inbound event.

close

public void close()

Close this event source. The method will wait up to 5 seconds for the internal event processing task to complete.

close

public boolean close(long timeout,
            TimeUnit unit)

Close this event source and wait for the internal event processing task to complete for up to the specified amount of wait time.

The method blocks until the event processing task has completed execution after a shutdown request, or until the timeout occurs, or the current thread is interrupted, whichever happens first.

In case the waiting for the event processing task has been interrupted, this method restores the interrupt flag on the thread before returning false.

Parameters:

timeout - the maximum time to wait.

unit - the time unit of the timeout argument.

Returns:

true if this executor terminated and false if the timeout elapsed before termination or the termination was interrupted.