Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 747b4530df4dfc725b84303af0702aea135454ad (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
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();

}

Back to the top