org.osgi.util.pushstream

Interface SimplePushEventSource<T>

Type Parameters:

T - The type of the events produced by this source

All Superinterfaces:

java.lang.AutoCloseable, PushEventSource<T>

@ProviderType
public interface SimplePushEventSource<T>
extends PushEventSource<T>, java.lang.AutoCloseable

A SimplePushEventSource is a helper that makes it simpler to write a PushEventSource. Users do not need to manage multiple registrations to the stream, nor do they have to be concerned with back pressure.

Method Summary

Modifier and Type	Method and Description
void	close() Close this source.
Promise<java.lang.Void>	connectPromise() This method can be used to delay event generation until an event source has connected.
void	endOfStream() Close this source for now, but potentially reopen it later.
void	error(java.lang.Throwable t) Close this source for now, but potentially reopen it later.
boolean	isConnected() Determine whether there are any PushEventConsumers for this PushEventSource.
void	publish(T t) Asynchronously publish an event to this stream and all connected PushEventConsumer instances.

Methods inherited from interface org.osgi.util.pushstream.PushEventSource

open

Method Detail

close

void close()

Close this source. Calling this method indicates that there will never be any more events published by it. Calling this method sends a close event to all connected consumers. After calling this method any PushEventConsumer that tries to PushEventSource.open(PushEventConsumer) this source will immediately receive a close event, and will not see any remaining buffered events.

Specified by:

close in interface java.lang.AutoCloseable

publish

void publish(T t)

Asynchronously publish an event to this stream and all connected PushEventConsumer instances. When this method returns there is no guarantee that all consumers have been notified. Events published by a single thread will maintain their relative ordering, however they may be interleaved with events from other threads.

Parameters:

t -

Throws:

java.lang.IllegalStateException - if the source is closed

endOfStream

void endOfStream()

Close this source for now, but potentially reopen it later. Calling this method asynchronously sends a close event to all connected consumers and then disconnects them. Any events previously queued by the publish(Object) method will be delivered before this close event.

After calling this method any PushEventConsumer that wishes may PushEventSource.open(PushEventConsumer) this source, and will receive subsequent events.

error

void error(java.lang.Throwable t)

Close this source for now, but potentially reopen it later. Calling this method asynchronously sends an error event to all connected consumers and then disconnects them. Any events previously queued by the publish(Object) method will be delivered before this error event.

After calling this method any PushEventConsumer that wishes may PushEventSource.open(PushEventConsumer) this source, and will receive subsequent events.

Parameters:

t - the error

isConnected

boolean isConnected()

Determine whether there are any PushEventConsumers for this PushEventSource. This can be used to skip expensive event creation logic when there are no listeners.

Returns:

true if any consumers are currently connected

connectPromise

Promise<java.lang.Void> connectPromise()

This method can be used to delay event generation until an event source has connected. The returned promise will resolve as soon as one or more PushEventConsumer instances have opened the SimplePushEventSource.

The returned promise may already be resolved if this SimplePushEventSource already has connected consumers. If the SimplePushEventSource is closed before the returned Promise resolves then it will be failed with an IllegalStateException.

Note that the connected consumers are able to asynchronously close their connections to this SimplePushEventSource, and therefore it is possible that once the promise resolves this SimplePushEventSource may no longer be connected to any consumers.

Returns:

A promise representing the connection state of this EventSource