net.sf.asterisk.manager
Class DefaultManagerConnection

java.lang.Object
  extended by 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


Copyright © 2004-2005 Stefan Reuter. All Rights Reserved.