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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
/*******************************************************************************
* Copyright (c) 2011, 2014 Wind River Systems, Inc. and others. All rights reserved.
* This program and the accompanying materials are made available under the terms
* of the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Wind River Systems - initial API and implementation
*******************************************************************************/
package org.eclipse.tcf.te.tcf.core.interfaces;
import java.util.Map;
import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.core.runtime.OperationCanceledException;
import org.eclipse.tcf.protocol.IChannel;
import org.eclipse.tcf.protocol.IPeer;
import org.eclipse.tcf.services.IStreams;
/**
* TCF channel manager public API declaration.
*/
public interface IChannelManager extends IAdaptable {
/**
* If set to <code>true</code>, a new and not reference counted channel is opened.
* <p>
* All channels opened by the channel manager must be closed by the channel managers
* {@link #closeChannel(IChannel)} API.
* <p>
* If not present in the flags map passed in to open channel, the default value is
* <code>false</code>.
*/
public static final String FLAG_FORCE_NEW = "channel.forceNew"; //$NON-NLS-1$
/**
* If set to <code>true</code>, a new and not reference counted channel is opened,
* and no value add is launched and associated with the channel. This option should
* be used with extreme caution.
* <p>
* All channels opened by the channel manager must be closed by the channel managers
* {@link #closeChannel(IChannel)} API.
* <p>
* If not present in the flags map passed in to open channel, the default value is
* <code>false</code>.
*/
public static final String FLAG_NO_VALUE_ADD = "channel.noValueAdd"; //$NON-NLS-1$
/**
* If set to <code>true</code>, a new and not reference counted channel is opened,
* and the configured path map is not auto applied to the opened channel.
* <p>
* All channels opened by the channel manager must be closed by the channel managers
* {@link #closeChannel(IChannel)} API.
* <p>
* If not present in the flags map passed in to open channel, the default value is
* <code>false</code>.
*/
public static final String FLAG_NO_PATH_MAP = "channel.noPathMap"; //$NON-NLS-1$
/**
* Client call back interface for openChannel(...).
*/
interface DoneOpenChannel {
/**
* Called when the channel fully opened or failed to open.
* <p>
* <b>Note:</b> If error is of type {@link OperationCanceledException}, than it signals that
* the channel got closed normally while still in state {@link IChannel#STATE_OPENING}. Clients
* should handle the case explicitly if necessary.
*
* @param error The error description if operation failed, <code>null</code> if succeeded.
* @param channel The channel object or <code>null</code>.
*/
void doneOpenChannel(Throwable error, IChannel channel);
}
/**
* Opens a new channel to communicate with the given peer.
* <p>
* Channels opened by the channel manager must be closed by the channel managers
* {@link #closeChannel(IChannel)} API.
* <p>
* The method can be called from any thread context, the client done callback
* is always invoked within the TCF event dispatch thread.
*
* @param peer The peer. Must not be <code>null</code>.
* @param flags Map containing the flags to parameterize the channel opening, or <code>null</code>.
* @param done The client callback. Must not be <code>null</code>.
*/
public void openChannel(IPeer peer, Map<String, Boolean> flags, DoneOpenChannel done);
/**
* Returns the shared channel instance for the given peer. Channels retrieved using this
* method cannot be closed by the caller.
* <p>
* Callers of this method are expected to test for the current channel state themselves.
* <p>
* The method can be called from any thread context.
*
* @param peer The peer. Must not be <code>null</code>.
* @return The channel instance or <code>null</code>.
*/
public IChannel getChannel(IPeer peer);
/**
* Closes the given channel.
* <p>
* If the given channel is a reference counted channel, the channel will be closed if the reference counter
* reaches 0. For non reference counted channels, the channel is closed immediately.
* <p>
* The method can be called from any thread context.
*
* @param channel The channel. Must not be <code>null</code>.
*/
public void closeChannel(IChannel channel);
/**
* Shutdown the communication to the given peer, no matter of the current
* reference count. A possible associated value-add is shutdown as well.
*
* @param peer The peer. Must not be <code>null</code>.
*/
public void shutdown(IPeer peer);
/**
* Close all open channel, no matter of the current reference count.
* <p>
* If <code>wait</code> equals <code>false</code>, the method can be called
* from any thread context. Otherwise it must be called from outside the
* TCF event dispatch thread.
*
* @param wait If <code>true</code> the method will wait until all channels or closed. If <code>false</code>,
* the method will return immediately.
*/
public void closeAll(boolean wait);
/**
* Channel manager specific interface to be implemented by streams listener proxies.
*/
interface IStreamsListenerProxy {
/**
* Trigger the processing of all delayed created events.
*/
void processDelayedCreatedEvents();
}
/**
* Channel manager specific extension of the {@link IStreams.StreamsListener} interface
* to handle the stream disconnect in a common place.
*
* @see IStreams.StreamsListener
*/
interface IStreamsListener extends IStreams.StreamsListener {
/**
* Associate the given proxy with the streams listener. The
* streams listener can call the proxy methods to tell the
* proxy implementation which created stream should be disconnected.
*
* @param proxy The streams listener proxy or <code>null</code>.
*/
void setProxy(IStreamsListenerProxy proxy);
/**
* Returns if or if not the listener has a context set and can
* decide if a created event is consumed or not.
*
* @return <code>True</code> if the listener has a context, <code>false</code> if not.
*/
boolean hasContext();
/**
* Returns if or if not the given created event is consumed by the streams listener
* or not.
*
* @param stream_type The stream type. Must not be <code>null</code>.
* @param stream_id The stream id. Must not be <code>null</code>.
* @param context_id The context id or <code>null</code>.
*
* @return <code>True</code> if the created event is consumed, <code>false</code> otherwise.
*/
boolean isCreatedConsumed(String stream_type, String stream_id, String context_id);
}
/**
* Client call back interface for subscribeStream(...).
*/
interface DoneSubscribeStream {
/**
* Called when subscribing to a stream type is done.
*
* @param error The error description if operation failed, <code>null</code> if succeeded.
*/
void doneSubscribeStream(Throwable error);
}
/**
* Subscribe to the given stream type if not yet subscribed and register the given streams listener.
*
* @param channel The channel. Must not be <code>null</code>.
* @param streamType The stream source type. Must not be <code>null</code>.
* @param listener The streams listener. Must not be <code>null</code>.
* @param done The client callback. Must not be <code>null</code>.
*/
public void subscribeStream(IChannel channel, String streamType, IStreamsListener listener, DoneSubscribeStream done);
/**
* Client call back interface for unsubscribeStream(...).
*/
interface DoneUnsubscribeStream {
/**
* Called when unsubscribing a stream type is done.
*
* @param error The error description if operation failed, <code>null</code> if succeeded.
*/
void doneUnsubscribeStream(Throwable error);
}
/**
* Unsubscribe from the given stream type if subscribed and unregister the given streams listener.
*
* @param channel The channel. Must not be <code>null</code>.
* @param streamType The stream source type. Must not be <code>null</code>.
* @param listener The streams listener. Must not be <code>null</code>.
* @param done The client callback. Must not be <code>null</code>.
*/
public void unsubscribeStream(IChannel channel, String streamType, IStreamsListener listener, DoneUnsubscribeStream done);
}
|
