1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.asteriskjava.manager;
18
19 import java.io.IOException;
20
21 import org.asteriskjava.manager.action.EventGeneratingAction;
22 import org.asteriskjava.manager.action.ManagerAction;
23 import org.asteriskjava.manager.event.ManagerEvent;
24 import org.asteriskjava.manager.response.ManagerResponse;
25
26 /***
27 * The main interface to talk to an Asterisk server via the Asterisk Manager
28 * API.
29 * <p>
30 * The ManagerConnection repesents a connection to an Asterisk server and is
31 * capable of sending {@link org.asteriskjava.manager.action.ManagerAction}s
32 * and receiving {@link org.asteriskjava.manager.response.ManagerResponse}s and
33 * {@link org.asteriskjava.manager.event.ManagerEvent}s. It does not add any
34 * further functionality but rather provides a Java view to Asterisk's Manager
35 * API (freeing you from TCP/IP connection and parsing stuff).
36 * <p>
37 * It is used as the foundation for higher leveled interfaces like the
38 * Asterisk-Java Live.
39 * <p>
40 * A concrete implementation of this interface can be obtained from a
41 * {@link org.asteriskjava.manager.ManagerConnectionFactory}.
42 *
43 * @see org.asteriskjava.manager.ManagerConnectionFactory
44 * @author srt
45 * @version $Id: ManagerConnection.java 592 2007-01-21 16:44:00Z srt $
46 */
47 public interface ManagerConnection
48 {
49 /***
50 * Returns the hostname of the connected Asterisk server.
51 *
52 * @return the hostname of the connected Asterisk server.
53 * @since 0.3
54 */
55 String getHostname();
56
57 /***
58 * Returns the Manager API port of the connected Asterisk server.
59 *
60 * @return the Manager API port of the connected Asterisk server.
61 * @since 0.3
62 */
63 int getPort();
64
65 /***
66 * Returns the username to use to connect to the Asterisk server. This is
67 * the username specified in Asterisk's <code>manager.conf</code> file.
68 *
69 * @return the username to use for login
70 * @since 0.3
71 */
72 String getUsername();
73
74 /***
75 * Returns the password to use to connect to the Asterisk server. This is
76 * the username specified in Asterisk's <code>manager.conf</code> file.
77 *
78 * @return the password to use for login
79 * @since 0.3
80 */
81 String getPassword();
82
83 /***
84 * Returns whether to use SSL.
85 * <p>
86 * Default is false.
87 *
88 * @return <code>true</code> if SSL is used for the connection,
89 * <code>false</code> for a plain text connection.
90 * @since 0.3
91 */
92 boolean isSsl();
93
94 /***
95 * Registers a new user event type.
96 * <p>
97 * Asterisk allows you to send custom events via the UserEvent application.
98 * If you choose to send such events you can extend the abstract class
99 * UserEvent provide a name for your new event and optionally add your own
100 * attributes. After registering a user event type Asterisk-Java will handle
101 * such events the same way it handles the internal events and inform your
102 * registered event handlers.
103 * <p>
104 * Note: If you write your own Asterisk applications that use Asterisk's
105 * <code>manager_event()</code> function directly and don't use the
106 * channel and uniqueid attributes provided by UserEvent you can also
107 * register events that directly subclass {@link ManagerEvent}.
108 * <p>
109 * The event class must be a concrete class with a default constructor (one
110 * that takes no arguments).
111 *
112 * @param userEventClass the class representing the user event to register.
113 * @throws IllegalArgumentException if userEventClass is not a valid event
114 * class.
115 * @see org.asteriskjava.manager.event.UserEvent
116 * @see ManagerEvent
117 */
118 void registerUserEventClass(Class userEventClass);
119
120 /***
121 * The timeout to use when connecting the the Asterisk server.
122 * <p>
123 * Default is 0, that is using Java's built-in default.
124 *
125 * @param socketTimeout the timeout value to be used in milliseconds.
126 * @see java.net.Socket#connect(java.net.SocketAddress, int)
127 * @since 0.2
128 */
129 public void setSocketTimeout(int socketTimeout);
130
131 /***
132 * Connection is dropped (and restarted) if it stales on read longer than
133 * the timeout.
134 * <p>
135 * If you set this property to a non zero value be sure to also use a
136 * {@link PingThread} or somthing similar to make sure there is some network
137 * traffic, otherwise you will encounter lots of unexpected reconnects. The
138 * read timeout should be at least twice the interval set for the
139 * PingThread.
140 * <p>
141 * Default is 0, that is no read timeout.
142 *
143 * @param socketReadTimeout the read timeout value to be used in
144 * milliseconds.
145 * @see java.net.Socket#setSoTimeout(int)
146 * @since 0.3
147 */
148 void setSocketReadTimeout(int socketReadTimeout);
149
150 /***
151 * Logs in to the Asterisk server with the username and password specified
152 * when this connection was created.
153 *
154 * @throws IllegalStateException if connection is not in state INITIAL or
155 * DISCONNECTED.
156 * @throws IOException if the network connection is disrupted.
157 * @throws AuthenticationFailedException if the username and/or password are
158 * incorrect or the ChallengeResponse could not be built.
159 * @throws TimeoutException if a timeout occurs while waiting for the
160 * protocol identifier. The connection is closed in this case.
161 * @see org.asteriskjava.manager.action.LoginAction
162 * @see org.asteriskjava.manager.action.ChallengeAction
163 */
164 void login() throws IllegalStateException, IOException, AuthenticationFailedException, TimeoutException;
165
166 /***
167 * Logs in to the Asterisk server with the username and password specified
168 * when this connection was created and a given event mask.
169 *
170 * @param events the event mask. Set to "on" if all events should be send,
171 * "off" if not events should be sent or a combination of
172 * "system", "call" and "log" (separated by ',') to specify what
173 * kind of events should be sent.
174 * @throws IllegalStateException if connection is not in state INITIAL or
175 * DISCONNECTED.
176 * @throws IOException if the network connection is disrupted.
177 * @throws AuthenticationFailedException if the username and/or password are
178 * incorrect or the ChallengeResponse could not be built.
179 * @throws TimeoutException if a timeout occurs while waiting for the
180 * protocol identifier. The connection is closed in this case.
181 * @since 0.3
182 * @see org.asteriskjava.manager.action.LoginAction
183 * @see org.asteriskjava.manager.action.ChallengeAction
184 */
185 void login(String events) throws IllegalStateException, IOException, AuthenticationFailedException, TimeoutException;
186
187 /***
188 * Sends a LogoffAction to the Asterisk server and disconnects.
189 *
190 * @throws IllegalStateException if not in state CONNECTED or RECONNECTING.
191 * @see org.asteriskjava.manager.action.LogoffAction
192 */
193 void logoff() throws IllegalStateException;
194
195 /***
196 * Returns the protocol identifier, that is a string like "Asterisk Call
197 * Manager/1.0".
198 *
199 * @return the protocol identifier of the Asterisk Manager Interface in use
200 * if it has already been received; <code>null</code> otherwise
201 */
202 String getProtocolIdentifier();
203
204 /***
205 * Returns the lifecycle status of this connection.
206 *
207 * @return the lifecycle status of this connection.
208 */
209 ManagerConnectionState getState();
210
211 /***
212 * Sends a ManagerAction to the Asterisk server and waits for the
213 * corresponding ManagerResponse.
214 *
215 * @param action the action to send to the Asterisk server
216 * @return the corresponding response received from the Asterisk server
217 * @throws IOException if the network connection is disrupted.
218 * @throws TimeoutException if no response is received within the default
219 * timeout period.
220 * @throws IllegalArgumentException if the action is <code>null</code>.
221 * @throws IllegalStateException if you are not connected to an Asterisk
222 * server.
223 * @see #sendAction(ManagerAction, long)
224 * @see #sendAction(ManagerAction, SendActionCallback)
225 */
226 ManagerResponse sendAction(ManagerAction action) throws IOException, TimeoutException, IllegalArgumentException,
227 IllegalStateException;
228
229 /***
230 * Sends a ManagerAction to the Asterisk server and waits for the
231 * corresponding {@link ManagerResponse}.
232 *
233 * @param action the action to send to the Asterisk server
234 * @param timeout milliseconds to wait for the response before throwing a
235 * TimeoutException
236 * @return the corresponding response received from the Asterisk server
237 * @throws IOException if the network connection is disrupted.
238 * @throws TimeoutException if no response is received within the given
239 * timeout period.
240 * @throws IllegalArgumentException if the action is <code>null</code>.
241 * @throws IllegalStateException if you are not connected to an Asterisk
242 * server.
243 * @see #sendAction(ManagerAction, SendActionCallback)
244 */
245 ManagerResponse sendAction(ManagerAction action, long timeout) throws IOException, TimeoutException,
246 IllegalArgumentException, IllegalStateException;
247
248 /***
249 * Sends a ManagerAction to the Asterisk server and registers a callback
250 * handler to be called when the corresponding {@link ManagerResponse} is
251 * received. Be very careful that your callbackHandler terminates very
252 * quickly and does not do any fancy processing because it is called from
253 * the reader thread which is blocked for the time it takes to execute your
254 * callbackHandler.
255 *
256 * @param action the action to send to the Asterisk server
257 * @param callback the callback handler to call when the response is
258 * received or <code>null</code> if you are not interested in
259 * the response
260 * @throws IOException if the network connection is disrupted.
261 * @throws IllegalArgumentException if the action is <code>null</code>.
262 * @throws IllegalStateException if you are not connected to the Asterisk
263 * server.
264 */
265 void sendAction(ManagerAction action, SendActionCallback callback) throws IOException, IllegalArgumentException,
266 IllegalStateException;
267
268 /***
269 * Sends an {@link EventGeneratingAction} to the Asterisk server and waits
270 * for the corresponding {@link ManagerResponse} and the
271 * {@link org.asteriskjava.manager.event.ResponseEvent}s
272 * <p>
273 * EventGeneratingActions are {@link ManagerAction}s that don't return
274 * their response in the corresponding {@link ManagerResponse} but send a
275 * series of events that contain the payload.
276 * <p>
277 * This method will block until the correpsonding action complete event has
278 * been received. The action complete event is determined by
279 * {@link EventGeneratingAction#getActionCompleteEventClass()}.
280 * <p>
281 * Examples for EventGeneratingActions are
282 * {@link org.asteriskjava.manager.action.StatusAction},
283 * {@link org.asteriskjava.manager.action.QueueAction} or
284 * {@link org.asteriskjava.manager.action.AgentsAction}.
285 *
286 * @param action the action to send to the Asterisk server
287 * @return a ResponseEvents that contains the corresponding response and
288 * response events received from the Asterisk server
289 * @throws IOException if the network connection is disrupted.
290 * @throws EventTimeoutException if no response or not all response events
291 * are received within the given timeout period.
292 * @throws IllegalArgumentException if the action is <code>null</code>,
293 * the actionCompleteEventClass property of the action is
294 * <code>null</code> or if actionCompleteEventClass is not a
295 * ResponseEvent.
296 * @throws IllegalStateException if you are not connected to an Asterisk
297 * server.
298 * @see EventGeneratingAction
299 * @see org.asteriskjava.manager.event.ResponseEvent
300 * @since 0.2
301 */
302 ResponseEvents sendEventGeneratingAction(EventGeneratingAction action) throws IOException, EventTimeoutException,
303 IllegalArgumentException, IllegalStateException;
304
305 /***
306 * Sends an {@link EventGeneratingAction} to the Asterisk server and waits
307 * for the corresponding {@link ManagerResponse} and the
308 * {@link org.asteriskjava.manager.event.ResponseEvent}s
309 * <p>
310 * EventGeneratingActions are {@link ManagerAction}s that don't return
311 * their response in the corresponding {@link ManagerResponse} but send a
312 * series of events that contain the payload.
313 * <p>
314 * This method will block until the correpsonding action complete event has
315 * been received but no longer that timeout seconds. The action complete
316 * event is determined by
317 * {@link EventGeneratingAction#getActionCompleteEventClass()}.
318 * <p>
319 * Examples for EventGeneratingActions are the
320 * {@link org.asteriskjava.manager.action.StatusAction}, the
321 * {@link org.asteriskjava.manager.action.QueueAction} or the
322 * {@link org.asteriskjava.manager.action.AgentsAction}.
323 *
324 * @param action the action to send to the Asterisk server
325 * @param timeout milliseconds to wait for the response and the action
326 * complete event before throwing a TimeoutException
327 * @return a ResponseEvents that contains the corresponding response and
328 * response events received from the Asterisk server
329 * @throws IOException if the network connection is disrupted.
330 * @throws EventTimeoutException if no response or not all response events
331 * are received within the given timeout period.
332 * @throws IllegalArgumentException if the action is <code>null</code>,
333 * the actionCompleteEventClass property of the action is
334 * <code>null</code> or if actionCompleteEventClass is not a
335 * ResponseEvent.
336 * @throws IllegalStateException if you are not connected to an Asterisk
337 * server.
338 * @see EventGeneratingAction
339 * @see org.asteriskjava.manager.event.ResponseEvent
340 * @since 0.2
341 */
342 ResponseEvents sendEventGeneratingAction(EventGeneratingAction action, long timeout) throws IOException,
343 EventTimeoutException, IllegalArgumentException, IllegalStateException;
344
345 /***
346 * Registers an event listener that is called whenever an
347 * {@link org.asteriskjava.manager.event.ManagerEvent} is receiced from the
348 * Asterisk server.
349 * <p>
350 * Event listeners are notified about new events in the same order as they
351 * were registered.
352 *
353 * @param eventListener the listener to call whenever a manager event is
354 * received
355 * @see #removeEventListener(ManagerEventListener)
356 */
357 void addEventListener(ManagerEventListener eventListener);
358
359 /***
360 * Unregisters a previously registered event listener.
361 * <p>
362 * Does nothing if the given event listener hasn't be been regiered before.
363 *
364 * @param eventListener the listener to remove
365 * @see #addEventListener(ManagerEventListener)
366 */
367 void removeEventListener(ManagerEventListener eventListener);
368 }