diff options
Diffstat (limited to 'bundles/org.eclipse.equinox.logstream/src/org/osgi/util/pushstream/SimplePushEventSource.java')
| -rw-r--r-- | bundles/org.eclipse.equinox.logstream/src/org/osgi/util/pushstream/SimplePushEventSource.java | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/bundles/org.eclipse.equinox.logstream/src/org/osgi/util/pushstream/SimplePushEventSource.java b/bundles/org.eclipse.equinox.logstream/src/org/osgi/util/pushstream/SimplePushEventSource.java new file mode 100644 index 000000000..747b4530d --- /dev/null +++ b/bundles/org.eclipse.equinox.logstream/src/org/osgi/util/pushstream/SimplePushEventSource.java @@ -0,0 +1,104 @@ +/* + * Copyright (c) OSGi Alliance (2015, 2016). All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.osgi.util.pushstream; + +import org.osgi.annotation.versioning.ProviderType; +import org.osgi.util.promise.Promise; + +/** + * A {@link SimplePushEventSource} is a helper that makes it simpler to write a + * {@link PushEventSource}. Users do not need to manage multiple registrations + * to the stream, nor do they have to be concerned with back pressure. + * + * @param <T> The type of the events produced by this source + */ +@ProviderType +public interface SimplePushEventSource<T> + extends PushEventSource<T>, AutoCloseable { + /** + * 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 + * {@link PushEventConsumer} that tries to {@link #open(PushEventConsumer)} + * this source will immediately receive a close event. + */ + @Override + void close(); + + /** + * Asynchronously publish an event to this stream and all connected + * {@link 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. + * + * @param t + * @throws IllegalStateException if the source is closed + */ + void publish(T t); + + /** + * Close this source for now, but potentially reopen it later. Calling this + * method asynchronously sends a close event to all connected consumers. + * After calling this method any {@link PushEventConsumer} that wishes may + * {@link #open(PushEventConsumer)} this source, and will receive subsequent + * events. + */ + void endOfStream(); + + /** + * Close this source for now, but potentially reopen it later. Calling this + * method asynchronously sends an error event to all connected consumers. + * After calling this method any {@link PushEventConsumer} that wishes may + * {@link #open(PushEventConsumer)} this source, and will receive subsequent + * events. + * + * @param e the error + */ + void error(Exception e); + + /** + * Determine whether there are any {@link PushEventConsumer}s for this + * {@link PushEventSource}. This can be used to skip expensive event + * creation logic when there are no listeners. + * + * @return true if any consumers are currently connected + */ + boolean isConnected(); + + /** + * 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 + * {@link PushEventConsumer} instances have opened the + * SimplePushEventSource. + * <p> + * The returned promise may already be resolved if this + * {@link SimplePushEventSource} already has connected consumers. If the + * {@link SimplePushEventSource} is closed before the returned Promise + * resolves then it will be failed with an {@link IllegalStateException}. + * <p> + * Note that the connected consumers are able to asynchronously close their + * connections to this {@link SimplePushEventSource}, and therefore it is + * possible that once the promise resolves this + * {@link SimplePushEventSource} may no longer be connected to any + * consumers. + * + * @return A promise representing the connection state of this EventSource + */ + Promise<Void> connectPromise(); + +} |