net.sf.asterisk.manager
Interface ManagerConnection

All Known Implementing Classes:

DefaultManagerConnection

public interface ManagerConnection

The main interface to talk to an Asterisk server via the Asterisk Manager API.
The ManagerConnection repesents a connection to an Asterisk Server and is capable to send Actions and receive Responses and Events. It does not add any valuable functionality but rather provides a Java view to Asterisk's Manager API (freeing you from TCP/IP connection and parsing stuff).
It is used as the foundation for higher leveled interfaces like the AsteriskManager.
A concrete implementation of this interface can be obtained from a ManagerConnectionFactory.

Version:

$Id: ManagerConnection.java,v 1.12 2005/10/10 20:33:55 srt Exp $

Author:

srt

See Also:

ManagerConnectionFactory

Method Summary

void	addEventHandler(ManagerEventHandler eventHandler) Registers an event handler to be called whenever an ManagerEvent is receiced from the Asterisk server. Event handlers are notified about new events in the same order as they were registered via addEventHandler.
AsteriskServer	getAsteriskServer() Returns the Asterisk server of this connection.
java.lang.String	getProtocolIdentifier() Returns the protocol identifier, i.e.
boolean	isConnected() Checks if the connection to the Asterisk server is established.
void	login() Logs in to the Asterisk server with the username and password specified when this connection was created.
void	logoff() Sends a LogoffAction to the Asterisk server and disconnects.
void	registerUserEventClass(java.lang.Class userEventClass) Registers a new user event type. Asterisk allows you to send custom events via the UserEvent application.
void	removeEventHandler(ManagerEventHandler eventHandler) Unregisters a previously registered event handler. Does nothing if the given event handler hasn't be been regiered before.
ManagerResponse	sendAction(ManagerAction action) Sends a ManagerAction to the Asterisk server and waits for the corresponding ManagerResponse.
ManagerResponse	sendAction(ManagerAction action, long timeout) Sends a ManagerAction to the Asterisk server and waits for the corresponding ManagerResponse.
void	sendAction(ManagerAction action, ManagerResponseHandler callbackHandler) Sends a ManagerAction to the Asterisk server and registers a callback handler to be called when the corresponding ManagerResponse is received.
ResponseEvents	sendEventGeneratingAction(EventGeneratingAction action) Sends a EventGeneratingAction to the Asterisk server and waits for the corresponding ManagerResponse and the ResponseEvents. EventGeneratingActions are ManagerActions that don't return their response in the corresponding ManagerResponse but send a series of events that contain the payload. Examples for EventGeneratingActions are the StatusAction, the net.sf.asterisk.manager.action.QueueAction or the AgentsAction.
ResponseEvents	sendEventGeneratingAction(EventGeneratingAction action, long timeout) Sends a EventGeneratingAction to the Asterisk server and waits for the corresponding ManagerResponse and the ResponseEvents.
void	setSocketTimeout(int socketTimeout) The timeout to use when connecting the the Asterisk server. Default is 0, that is using Java's built-in default.

Method Detail

registerUserEventClass

void registerUserEventClass(java.lang.Class userEventClass)

Registers a new user event type.
Asterisk allows you to send custom events via the UserEvent application. If you choose to send such events you can extend the abstract class UserEvent provide a name for your new event and optionally add your own attributes. After registering a user event type Asterisk-Java will handle such events the same way it handles the internal events and inform your registered event handlers.
Note: If you write your own Asterisk applications that use Asterisk's manager_event() function directly and don't use the channel and uniqueid attributes provided by UserEvent you can also register events that directly subclass ManagerEvent.

Parameters:

userEventClass - the class of the user event to register.

See Also:

UserEvent, ManagerEvent

setSocketTimeout

void setSocketTimeout(int socketTimeout)

The timeout to use when connecting the the Asterisk server.
Default is 0, that is using Java's built-in default.

Parameters:

socketTimeout - the timeout value to be used in milliseconds.

Since:

0.2

See Also:

Socket.connect(java.net.SocketAddress, int)

login

void login()
           throws java.io.IOException,
                  AuthenticationFailedException,
                  TimeoutException

Logs in to the Asterisk server with the username and password specified when this connection was created.

Throws:

java.io.IOException - if the network connection is disrupted.

AuthenticationFailedException - if the username and/or password are incorrect or the ChallengeResponse could not be built.

TimeoutException - if no response is received within the default timeout period. If the implementation uses challenge/response this can either be a timeout of the ChallengeAction or the LoginAction; otherwise it is always a timeout of the LoginAction.

See Also:

LoginAction, ChallengeAction

logoff

void logoff()
            throws java.io.IOException,
                   TimeoutException

Sends a LogoffAction to the Asterisk server and disconnects.

Throws:

java.io.IOException - if the network connection is disrupted.

TimeoutException - if no response to the logoff action is received within the default timeout period.

See Also:

LogoffAction

getProtocolIdentifier

java.lang.String getProtocolIdentifier()

Returns the protocol identifier, i.e. a string like "Asterisk Call Manager/1.0".

Returns:

the protocol identifier of the Asterisk Manager Interface in use if it has already been received; null otherwise

sendAction

ManagerResponse sendAction(ManagerAction action)
                           throws java.io.IOException,
                                  TimeoutException,
                                  java.lang.IllegalArgumentException,
                                  java.lang.IllegalStateException

Sends a ManagerAction to the Asterisk server and waits for the corresponding ManagerResponse.

Parameters:

action - the action to send to the Asterisk server

Returns:

the corresponding response received from the Asterisk server

Throws:

java.io.IOException - if the network connection is disrupted.

TimeoutException - if no response is received within the default timeout period.

java.lang.IllegalArgumentException - if the action is null.

java.lang.IllegalStateException - if you are not connected to an Asterisk server.

See Also:

sendAction(ManagerAction, long), sendAction(ManagerAction, ManagerResponseHandler)

sendAction

ManagerResponse sendAction(ManagerAction action,
                           long timeout)
                           throws java.io.IOException,
                                  TimeoutException,
                                  java.lang.IllegalArgumentException,
                                  java.lang.IllegalStateException

Sends a ManagerAction to the Asterisk server and waits for the corresponding ManagerResponse.

Parameters:

action - the action to send to the Asterisk server

timeout - milliseconds to wait for the response before throwing a TimeoutException

Returns:

the corresponding response received from the Asterisk server

Throws:

java.io.IOException - if the network connection is disrupted.

TimeoutException - if no response is received within the given timeout period.

java.lang.IllegalArgumentException - if the action is null.

java.lang.IllegalStateException - if you are not connected to an Asterisk server.

See Also:

sendAction(ManagerAction, ManagerResponseHandler)

sendAction

void sendAction(ManagerAction action,
                ManagerResponseHandler callbackHandler)
                throws java.io.IOException,
                       java.lang.IllegalArgumentException,
                       java.lang.IllegalStateException

Sends a ManagerAction to the Asterisk server and registers a callback handler to be called when the corresponding ManagerResponse is received.

Parameters:

action - the action to send to the Asterisk server

callbackHandler - the callback handler to call when the response is received or null if you are not interested in the response

Throws:

java.io.IOException - if the network connection is disrupted.

java.lang.IllegalArgumentException - if the action is null.

java.lang.IllegalStateException - if you are not connected to an Asterisk server.

sendEventGeneratingAction

ResponseEvents sendEventGeneratingAction(EventGeneratingAction action)
                                         throws java.io.IOException,
                                                EventTimeoutException,
                                                java.lang.IllegalArgumentException,
                                                java.lang.IllegalStateException

Sends a EventGeneratingAction to the Asterisk server and waits for the corresponding ManagerResponse and the ResponseEvents.
EventGeneratingActions are ManagerActions that don't return their response in the corresponding ManagerResponse but send a series of events that contain the payload.
Examples for EventGeneratingActions are the StatusAction, the net.sf.asterisk.manager.action.QueueAction or the AgentsAction.

Parameters:

action - the action to send to the Asterisk server

Returns:

a ResponseEvents that contains the corresponding response and response events received from the Asterisk server

Throws:

java.io.IOException - if the network connection is disrupted.

EventTimeoutException - if no response or not all response events are received within the given timeout period.

java.lang.IllegalArgumentException - if the action is null, the actionCompleteEventClass property of the action is null or if actionCompleteEventClass is not a ResponseEvent.

java.lang.IllegalStateException - if you are not connected to an Asterisk server.

Since:

0.2

See Also:

EventGeneratingAction, ResponseEvent

sendEventGeneratingAction

ResponseEvents sendEventGeneratingAction(EventGeneratingAction action,
                                         long timeout)
                                         throws java.io.IOException,
                                                EventTimeoutException,
                                                java.lang.IllegalArgumentException,
                                                java.lang.IllegalStateException

Sends a EventGeneratingAction to the Asterisk server and waits for the corresponding ManagerResponse and the ResponseEvents. EventGeneratingActions are ManagerActions that don't return their response in the corresponding ManagerResponse but send a series of events that contain the payload.
Examples for EventGeneratingActions are the StatusAction, the net.sf.asterisk.manager.action.QueueAction or the AgentsAction.

Parameters:

action - the action to send to the Asterisk server

timeout - milliseconds to wait for the response and the response events before throwing a TimeoutException

Returns:

a ResponseEvents that contains the corresponding response and response events received from the Asterisk server

Throws:

java.io.IOException - if the network connection is disrupted.

EventTimeoutException - if no response or not all response events are received within the given timeout period.

java.lang.IllegalArgumentException - if the action is null, the actionCompleteEventClass property of the action is null or if actionCompleteEventClass is not a ResponseEvent.

java.lang.IllegalStateException - if you are not connected to an Asterisk server.

Since:

0.2

See Also:

EventGeneratingAction, ResponseEvent

addEventHandler

void addEventHandler(ManagerEventHandler eventHandler)

Registers an event handler to be called whenever an ManagerEvent is receiced from the Asterisk server.
Event handlers are notified about new events in the same order as they were registered via addEventHandler.

Parameters:

eventHandler - the handler to call whenever a manager event is received

See Also:

removeEventHandler(ManagerEventHandler)

removeEventHandler

void removeEventHandler(ManagerEventHandler eventHandler)

Unregisters a previously registered event handler.
Does nothing if the given event handler hasn't be been regiered before.

Parameters:

eventHandler - the event handle to unregister

See Also:

addEventHandler(ManagerEventHandler)

getAsteriskServer

AsteriskServer getAsteriskServer()

Returns the Asterisk server of this connection.

Returns:

the Asterisk server of this connection.

isConnected

boolean isConnected()

Checks if the connection to the Asterisk server is established.

Returns:

true if the connection is established, false otherwise.

Since:

0.2