net.sf.asterisk.manager
Class DefaultManagerConnection

java.lang.Object
  net.sf.asterisk.manager.DefaultManagerConnection

All Implemented Interfaces:

Dispatcher, ManagerConnection

public class DefaultManagerConnection
extends java.lang.Object
implements ManagerConnection, Dispatcher

Default implemention of the ManagerConnection interface.
Generelly avoid direct use of this class. Use the ManagerConnectionFactory to obtain a ManagerConnection instead.
When using a dependency injection framework like Spring direct usage for wiring up beans that require a ManagerConnection property is fine though.
Note that the DefaultManagerConnection will create one new Thread for reading data from Asterisk on the first call to on of the login() methods.

Version:

$Id: DefaultManagerConnection.java,v 1.34 2005/11/08 15:25:18 srt Exp $

Author:

srt

See Also:

ManagerConnectionFactory

Field Summary

protected boolean	keepAlive Should we attempt to reconnect when the connection is lost? This is set to true after successful login and to false after logoff or after an authentication failure when keepAliveAfterAuthenticationFailure is false.
protected java.lang.String	password The password to use for login as defined in Asterisk's manager.conf.
protected java.lang.String	username The username to use for login as defined in Asterisk's manager.conf.

Constructor Summary

DefaultManagerConnection()
Creates a new instance.

DefaultManagerConnection(java.lang.String hostname, int port, java.lang.String username, java.lang.String password)
Creates a new instance with the given connection parameters.

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.
protected void	connect()
protected ManagerReader	createReader(Dispatcher dispatcher, AsteriskServer server)
protected SocketConnectionFacade	createSocket()
protected ManagerWriter	createWriter()
protected AsteriskVersion	determineVersion()
void	dispatchEvent(ManagerEvent event) This method is called by the reader whenever a ManagerEvent is received.
void	dispatchResponse(ManagerResponse response) This method is called by the reader whenever a ManagerResponse is received.
AsteriskServer	getAsteriskServer() Returns the Asterisk server of this connection.
java.lang.String	getProtocolIdentifier() Returns the protocol identifier, i.e.
boolean	isConnected() Returns true if there is a socket connection to the asterisk server, false otherwise.
void	login() Logs in to the asterisk manager using asterisk's MD5 based challenge/response protocol.
void	logoff() Sends a LogoffAction and disconnects from the server.
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	setDefaultEventTimeout(long defaultEventTimeout) Sets the time in milliseconds the synchronous method sendEventGeneratingAction(EventGeneratingAction) will wait for a response and the last response event before throwing a TimeoutException. Default is 5000.
void	setDefaultResponseTimeout(long defaultResponseTimeout) Sets the time in milliseconds the synchronous method sendAction(ManagerAction) will wait for a response before throwing a TimeoutException. Default is 2000.
void	setDefaultTimeout(long defaultTimeout) Deprecated. use setDefaultResponseTimeout(long) instead
void	setHostname(java.lang.String hostname) Sets the hostname of the asterisk server to connect to. Default is localhost.
void	setKeepAliveAfterAuthenticationFailure(boolean keepAliveAfterAuthenticationFailure) Set to true to try reconnecting to ther asterisk serve even if the reconnection attempt threw an AuthenticationFailedException. Default is false.
void	setPassword(java.lang.String password) Sets the password to use to connect to the asterisk server.
void	setPort(int port) Sets the port to use to connect to the asterisk server.
void	setSleepTime(long sleepTime) Deprecated. this has been replaced by an interrupt based response checking approach.
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.
void	setUsername(java.lang.String username) Sets the username to use to connect to the asterisk server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

username

protected java.lang.String username

The username to use for login as defined in Asterisk's manager.conf.

password

protected java.lang.String password

The password to use for login as defined in Asterisk's manager.conf.

keepAlive

protected boolean keepAlive

Should we attempt to reconnect when the connection is lost?
This is set to true after successful login and to false after logoff or after an authentication failure when keepAliveAfterAuthenticationFailure is false.

Constructor Detail

DefaultManagerConnection

public DefaultManagerConnection()

Creates a new instance.

DefaultManagerConnection

public DefaultManagerConnection(java.lang.String hostname,
                                int port,
                                java.lang.String username,
                                java.lang.String password)

Creates a new instance with the given connection parameters.

Parameters:

hostname - the hosname of the Asterisk server to connect to.

port - the port where Asterisk listens for incoming Manager API connections, usually 5038.

username - the username to use for login

password - the password to use for login

Method Detail

createReader

protected ManagerReader createReader(Dispatcher dispatcher,
                                     AsteriskServer server)

createWriter

protected ManagerWriter createWriter()

setHostname

public void setHostname(java.lang.String hostname)

Sets the hostname of the asterisk server to connect to.
Default is localhost.

Parameters:

hostname - the hostname to connect to

setPort

public void setPort(int port)

Sets the port to use to connect to the asterisk server. This is the port specified in asterisk's manager.conf file.
Default is 5038.

Parameters:

port - the port to connect to

setUsername

public void setUsername(java.lang.String username)

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

Parameters:

username - the username to use for login

setPassword

public void setPassword(java.lang.String password)

Sets the password to use to connect to the asterisk server. This is the password specified in asterisk's manager.conf file.

Parameters:

password - the password to use for login

setDefaultTimeout

public void setDefaultTimeout(long defaultTimeout)

Deprecated. use setDefaultResponseTimeout(long) instead

Sets the time in milliseconds the synchronous sendAction methods sendAction(ManagerAction) will wait for a response before throwing a TimeoutException.
Default is 2000.

Parameters:

defaultTimeout - default timeout in milliseconds

setDefaultResponseTimeout

public void setDefaultResponseTimeout(long defaultResponseTimeout)

Sets the time in milliseconds the synchronous method sendAction(ManagerAction) will wait for a response before throwing a TimeoutException.
Default is 2000.

Parameters:

defaultResponseTimeout - default response timeout in milliseconds

Since:

0.2

setDefaultEventTimeout

public void setDefaultEventTimeout(long defaultEventTimeout)

Sets the time in milliseconds the synchronous method sendEventGeneratingAction(EventGeneratingAction) will wait for a response and the last response event before throwing a TimeoutException.
Default is 5000.

Parameters:

defaultEventTimeout - default event timeout in milliseconds

Since:

0.2

setSleepTime

public void setSleepTime(long sleepTime)

Deprecated. this has been replaced by an interrupt based response checking approach.

Sets the time in milliseconds the synchronous methods sendAction(ManagerAction) and sendAction(ManagerAction, long) will sleep between two checks for the arrival of a response. This value should be rather small.
The sleepTime attribute is also used when checking for the protocol identifer.
Default is 50.

Parameters:

sleepTime - time in milliseconds to sleep between two checks for the arrival of a response or the protocol identifier

setKeepAliveAfterAuthenticationFailure

public void setKeepAliveAfterAuthenticationFailure(boolean keepAliveAfterAuthenticationFailure)

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

registerUserEventClass

public void registerUserEventClass(java.lang.Class userEventClass)

Description copied from interface: ManagerConnection

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.

Specified by:

registerUserEventClass in interface ManagerConnection

Parameters:

userEventClass - the class of the user event to register.

See Also:

UserEvent, ManagerEvent

setSocketTimeout

public void setSocketTimeout(int socketTimeout)

Description copied from interface: ManagerConnection

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

Specified by:

setSocketTimeout in interface ManagerConnection

Parameters:

socketTimeout - the timeout value to be used in milliseconds.

See Also:

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

login

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

Logs in to the asterisk manager using asterisk's MD5 based challenge/response protocol. The login is delayed until the protocol identifier has been received by the reader.

Specified by:

login in interface ManagerConnection

Throws:

AuthenticationFailedException - if the username and/or password are incorrect

TimeoutException - if no response is received within the specified timeout period

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

See Also:

ChallengeAction, LoginAction

determineVersion

protected AsteriskVersion determineVersion()
                                    throws java.io.IOException,
                                           TimeoutException

Throws:

java.io.IOException

TimeoutException

connect

protected void connect()
                throws java.io.IOException

Throws:

java.io.IOException

createSocket

protected SocketConnectionFacade createSocket()
                                       throws java.io.IOException

Throws:

java.io.IOException

isConnected

public boolean isConnected()

Returns true if there is a socket connection to the asterisk server, false otherwise.

Specified by:

isConnected in interface ManagerConnection

Returns:

true if there is a socket connection to the asterisk server, false otherwise.

logoff

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

Sends a LogoffAction and disconnects from the server.

Specified by:

logoff in interface ManagerConnection

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

sendAction

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

Description copied from interface: ManagerConnection

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

Specified by:

sendAction in interface ManagerConnection

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:

ManagerConnection.sendAction(ManagerAction, long), ManagerConnection.sendAction(ManagerAction, ManagerResponseHandler)

sendAction

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

Description copied from interface: ManagerConnection

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

Specified by:

sendAction in interface ManagerConnection

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:

ManagerConnection.sendAction(ManagerAction, ManagerResponseHandler)

sendAction

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

Description copied from interface: ManagerConnection

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

Specified by:

sendAction in interface ManagerConnection

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

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

Description copied from interface: ManagerConnection

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.

Specified by:

sendEventGeneratingAction in interface ManagerConnection

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.

See Also:

EventGeneratingAction, ResponseEvent

sendEventGeneratingAction

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

Description copied from interface: ManagerConnection

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.

Specified by:

sendEventGeneratingAction in interface ManagerConnection

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.

See Also:

EventGeneratingAction, ResponseEvent

addEventHandler

public void addEventHandler(ManagerEventHandler eventHandler)

Description copied from interface: ManagerConnection

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.

Specified by:

addEventHandler in interface ManagerConnection

Parameters:

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

See Also:

ManagerConnection.removeEventHandler(ManagerEventHandler)

removeEventHandler

public void removeEventHandler(ManagerEventHandler eventHandler)

Description copied from interface: ManagerConnection

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

Specified by:

removeEventHandler in interface ManagerConnection

Parameters:

eventHandler - the event handle to unregister

See Also:

ManagerConnection.addEventHandler(ManagerEventHandler)

getProtocolIdentifier

public java.lang.String getProtocolIdentifier()

Description copied from interface: ManagerConnection

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

Specified by:

getProtocolIdentifier in interface ManagerConnection

Returns:

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

getAsteriskServer

public AsteriskServer getAsteriskServer()

Description copied from interface: ManagerConnection

Returns the Asterisk server of this connection.

Specified by:

getAsteriskServer in interface ManagerConnection

Returns:

the Asterisk server of this connection.

dispatchResponse

public void dispatchResponse(ManagerResponse response)

This method is called by the reader whenever a ManagerResponse is received. The response is dispatched to the associated ManagerResponseHandler.

Specified by:

dispatchResponse in interface Dispatcher

Parameters:

response - the response received by the reader

See Also:

ManagerReader

dispatchEvent

public void dispatchEvent(ManagerEvent event)

This method is called by the reader whenever a ManagerEvent is received. The event is dispatched to all registered ManagerEventHandlers.

Specified by:

dispatchEvent in interface Dispatcher

Parameters:

event - the event received by the reader

See Also:

addEventHandler(ManagerEventHandler), removeEventHandler(ManagerEventHandler), ManagerReader