org.asteriskjava.manager

Interface ManagerConnection

All Known Implementing Classes:

DefaultManagerConnection, ManagerConnectionImpl

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 of sending ManagerActions and receiving ManagerResponses and ManagerEvents. It does not add any further 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 Asterisk-Java Live.

A concrete implementation of this interface can be obtained from a ManagerConnectionFactory.

Version:

$Id$

Author:

srt

See Also:

ManagerConnectionFactory

Method Summary

Modifier and Type	Method and Description
void	addEventListener(ManagerEventListener eventListener) Registers an event listener that is called whenever an ManagerEvent is receiced from the Asterisk server.
void	deregisterEventClass(Class<? extends ManagerEvent> eventClass)
Charset	getEncoding() Returns the encoding to use to connect to the Asterisk server (eg.
String	getHostname() Returns the hostname of the connected Asterisk server.
InetAddress	getLocalAddress() Returns the local address of the underlying socket connection.
int	getLocalPort() Returns the local port of the underlying socket connection.
String	getPassword() Returns the password to use to connect to the Asterisk server.
int	getPort() Returns the Manager API port of the connected Asterisk server.
String	getProtocolIdentifier() Returns the protocol identifier, that is a string like "Asterisk Call Manager/1.0".
InetAddress	getRemoteAddress() Returns the remote address of the underlying socket connection.
int	getRemotePort() Returns the remote port of the underlying socket connection.
ManagerConnectionState	getState() Returns the lifecycle status of this connection.
String	getUsername() Returns the username to use to connect to the Asterisk server.
AsteriskVersion	getVersion() Returns the version of Asterisk running in the server.
boolean	isSsl() Returns whether to use SSL.
void	login() Logs in to the Asterisk server with the username and password specified when this connection was created.
void	login(String events) Logs in to the Asterisk server with the username and password specified when this connection was created and a given event mask.
void	logoff() Sends a LogoffAction to the Asterisk server and disconnects.
void	registerUserEventClass(Class<? extends ManagerEvent> userEventClass) Registers a new user event type.
void	removeEventListener(ManagerEventListener eventListener) Unregisters a previously registered event listener.
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, SendActionCallback callback) 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 an EventGeneratingAction to the Asterisk server and waits for the corresponding ManagerResponse and the ResponseEvents
ResponseEvents	sendEventGeneratingAction(EventGeneratingAction action, long timeout) Sends an EventGeneratingAction to the Asterisk server and waits for the corresponding ManagerResponse and the ResponseEvents
void	sendEventGeneratingAction(EventGeneratingAction action, SendEventGeneratingActionCallback callback) Asynchronously sends an EventGeneratingAction to the Asterisk server.
void	setEncoding(Charset encoding) Sets the encoding to use to connect to the Asterisk server (eg.
void	setKeepAliveAfterAuthenticationFailure(boolean keepAliveAfterAuthenticationFailure) Set to true to try reconnecting to ther asterisk serve even if the reconnection attempt threw an AuthenticationFailedException.
void	setSocketReadTimeout(int socketReadTimeout) Connection is dropped (and restarted) if it stales on read longer than the timeout.
void	setSocketTimeout(int socketTimeout) The timeout to use when connecting the the Asterisk server.

Method Detail

getHostname

String getHostname()

Returns the hostname of the connected Asterisk server.

Returns:

the hostname of the connected Asterisk server.

Since:

0.3

getPort

int getPort()

Returns the Manager API port of the connected Asterisk server.

Returns:

the Manager API port of the connected Asterisk server.

Since:

0.3

getUsername

String getUsername()

Returns the username to use to connect to the Asterisk server. This is the username specified in Asterisk's manager.conf file.

Returns:

the username to use for login

Since:

0.3

getPassword

String getPassword()

Returns the password to use to connect to the Asterisk server. This is the username specified in Asterisk's manager.conf file.

Returns:

the password to use for login

Since:

0.3

getVersion

AsteriskVersion getVersion()

Returns the version of Asterisk running in the server.

Returns:

the Asterisk version running in the server.

Since:

1.0.0

setEncoding

void setEncoding(Charset encoding)

Sets the encoding to use to connect to the Asterisk server (eg. important for manager/user events). All connections should use the same encoding. The default is UTF-8.

Parameters:

encoding - the encoding to use for manager/user events etc.

getEncoding

Charset getEncoding()

Returns the encoding to use to connect to the Asterisk server (eg. important for manager/user events). All connections should use the same encoding. The default is UTF-8.

Returns:

the encoding to use for manager/user events etc.

isSsl

boolean isSsl()

Returns whether to use SSL.

Default is false.

Returns:

true if SSL is used for the connection, false for a plain text connection.

Since:

0.3

getLocalAddress

InetAddress getLocalAddress()

Returns the local address of the underlying socket connection.

Returns:

the local address of the underlying socket connection.

Since:

1.0.0

getLocalPort

int getLocalPort()

Returns the local port of the underlying socket connection.

Returns:

the local port of the underlying socket connection.

Since:

1.0.0

getRemoteAddress

InetAddress getRemoteAddress()

Returns the remote address of the underlying socket connection.

Returns:

the remote address of the underlying socket connection.

Since:

1.0.0

getRemotePort

int getRemotePort()

Returns the remote port of the underlying socket connection.

Returns:

the remote port of the underlying socket connection.

Since:

1.0.0

registerUserEventClass

void registerUserEventClass(Class<? extends ManagerEvent> 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.

The event class must be a concrete class with a default constructor (one that takes no arguments).

Parameters:

userEventClass - the class representing the user event to register.

Throws:

IllegalArgumentException - if userEventClass is not a valid event class.

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)

setSocketReadTimeout

void setSocketReadTimeout(int socketReadTimeout)

Connection is dropped (and restarted) if it stales on read longer than the timeout.

If you set this property to a non zero value be sure to also use a PingThread or somthing similar to make sure there is some network traffic, otherwise you will encounter lots of unexpected reconnects. The read timeout should be at least twice the interval set for the PingThread.

Default is 0, that is no read timeout.

Parameters:

socketReadTimeout - the read timeout value to be used in milliseconds.

Since:

0.3

See Also:

Socket.setSoTimeout(int)

setKeepAliveAfterAuthenticationFailure

void setKeepAliveAfterAuthenticationFailure(boolean keepAliveAfterAuthenticationFailure)

Set to true to try reconnecting to ther asterisk serve even if the reconnection attempt threw an AuthenticationFailedException.
Default is true.

Parameters:

keepAliveAfterAuthenticationFailure - true to try reconnecting to ther asterisk serve even if the reconnection attempt threw an AuthenticationFailedException, false otherwise.

login

void login()
    throws IllegalStateException,
           IOException,
           AuthenticationFailedException,
           TimeoutException

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

Throws:

IllegalStateException - if connection is not in state INITIAL or DISCONNECTED.

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 a timeout occurs while waiting for the protocol identifier. The connection is closed in this case.

See Also:

LoginAction, ChallengeAction

login

void login(String events)
    throws IllegalStateException,
           IOException,
           AuthenticationFailedException,
           TimeoutException

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

Parameters:

events - the event mask. Set to "on" if all events should be send, "off" if not events should be sent or a combination of "system", "call" and "log" (separated by ',') to specify what kind of events should be sent.

Throws:

IllegalStateException - if connection is not in state INITIAL or DISCONNECTED.

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 a timeout occurs while waiting for the protocol identifier. The connection is closed in this case.

Since:

0.3

See Also:

LoginAction, ChallengeAction

logoff

void logoff()
     throws IllegalStateException

Sends a LogoffAction to the Asterisk server and disconnects.

Throws:

IllegalStateException - if not in state CONNECTED or RECONNECTING.

See Also:

LogoffAction

getProtocolIdentifier

String getProtocolIdentifier()

Returns the protocol identifier, that is 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

getState

ManagerConnectionState getState()

Returns the lifecycle status of this connection.

Returns:

the lifecycle status of this connection.

sendAction

ManagerResponse sendAction(ManagerAction action)
                    throws IOException,
                           TimeoutException,
                           IllegalArgumentException,
                           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:

IOException - if the network connection is disrupted.

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

IllegalArgumentException - if the action is null.

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

See Also:

sendAction(ManagerAction, long), sendAction(ManagerAction, SendActionCallback)

sendAction

ManagerResponse sendAction(ManagerAction action,
                           long timeout)
                    throws IOException,
                           TimeoutException,
                           IllegalArgumentException,
                           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:

IOException - if the network connection is disrupted.

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

IllegalArgumentException - if the action is null.

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

See Also:

sendAction(ManagerAction, SendActionCallback)

sendAction

void sendAction(ManagerAction action,
                SendActionCallback callback)
         throws IOException,
                IllegalArgumentException,
                IllegalStateException

Sends a ManagerAction to the Asterisk server and registers a callback handler to be called when the corresponding ManagerResponse is received. Be very careful that your callbackHandler terminates very quickly and does not do any fancy processing because it is called from the reader thread which is blocked for the time it takes to execute your callbackHandler.

Parameters:

action - the action to send to the Asterisk server

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

Throws:

IOException - if the network connection is disrupted.

IllegalArgumentException - if the action is null.

IllegalStateException - if you are not connected to the Asterisk server.

sendEventGeneratingAction

ResponseEvents sendEventGeneratingAction(EventGeneratingAction action)
                                  throws IOException,
                                         EventTimeoutException,
                                         IllegalArgumentException,
                                         IllegalStateException

Sends an 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.

This method will block until the correpsonding action complete event has been received. The action complete event is determined by EventGeneratingAction.getActionCompleteEventClass().

Examples for EventGeneratingActions are StatusAction, QueueStatusAction or 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:

IOException - if the network connection is disrupted.

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

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

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 IOException,
                                         EventTimeoutException,
                                         IllegalArgumentException,
                                         IllegalStateException

Sends an 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.

This method will block until the correpsonding action complete event has been received but no longer that timeout seconds. The action complete event is determined by EventGeneratingAction.getActionCompleteEventClass().

Examples for EventGeneratingActions are the StatusAction, the QueueStatusAction or the AgentsAction.

Parameters:

action - the action to send to the Asterisk server

timeout - milliseconds to wait for the response and the action complete event before throwing a TimeoutException

Returns:

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

Throws:

IOException - if the network connection is disrupted.

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

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

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

Since:

0.2

See Also:

EventGeneratingAction, ResponseEvent

sendEventGeneratingAction

void sendEventGeneratingAction(EventGeneratingAction action,
                               SendEventGeneratingActionCallback callback)
                        throws IOException,
                               IllegalArgumentException,
                               IllegalStateException

Asynchronously sends an EventGeneratingAction to the Asterisk server. This is similar to sendEventGeneratingAction(EventGeneratingAction, long) except it does NOT block to wait for the completion. Instead after the action completes or fails the result is provided to the optional callback via SendEventGeneratingActionCallback.onResponse(ResponseEvents).

Throws:

IOException

IllegalArgumentException

IllegalStateException

See Also:

sendEventGeneratingAction(EventGeneratingAction, long)

addEventListener

void addEventListener(ManagerEventListener eventListener)

Registers an event listener that is called whenever an ManagerEvent is receiced from the Asterisk server.

Event listeners are notified about new events in the same order as they were registered.

Parameters:

eventListener - the listener to call whenever a manager event is received

See Also:

removeEventListener(ManagerEventListener)

removeEventListener

void removeEventListener(ManagerEventListener eventListener)

Unregisters a previously registered event listener.

Does nothing if the given event listener hasn't be been regiered before.

Parameters:

eventListener - the listener to remove

See Also:

addEventListener(ManagerEventListener)

deregisterEventClass

void deregisterEventClass(Class<? extends ManagerEvent> eventClass)