org.asteriskjava.manager.internal
Class ManagerConnectionImpl

java.lang.Object
  org.asteriskjava.manager.internal.ManagerConnectionImpl

All Implemented Interfaces:

ManagerConnection

public class ManagerConnectionImpl
extends java.lang.Object
implements ManagerConnection

Internal implemention of the ManagerConnection interface.

Version:

$Id: ManagerConnectionImpl.java 1286 2009-04-04 09:40:40Z srt $

Author:

srt

See Also:

ManagerConnectionFactory

Field Summary

protected java.lang.String	password The password to use for login as defined in Asterisk's manager.conf.
protected ManagerConnectionState	state
protected java.lang.String	username The username to use for login as defined in Asterisk's manager.conf.

Constructor Summary

ManagerConnectionImpl()
Creates a new instance.

Method Summary

void	addEventListener(ManagerEventListener listener) Registers an event listener that is called whenever an ManagerEvent is receiced from the Asterisk server.
protected void	connect()
protected ManagerReader	createReader(org.asteriskjava.manager.internal.Dispatcher dispatcher, java.lang.Object source)
protected SocketConnectionFacade	createSocket()
protected ManagerWriter	createWriter()
protected AsteriskVersion	determineVersion()
protected void	disconnect() Closes the socket connection.
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.
protected void	doLogin(long timeout, java.lang.String eventMask) Does the real login, following the steps outlined below.
java.lang.String	getHostname() Returns the hostname of the connected Asterisk server.
java.net.InetAddress	getLocalAddress() Returns the local address of the underlying socket connection.
int	getLocalPort() Returns the local port of the underlying socket connection.
java.lang.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.
java.lang.String	getProtocolIdentifier() Returns the protocol identifier, that is a string like "Asterisk Call Manager/1.0".
protected java.lang.String	getRawVersion()
java.net.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.
java.lang.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(java.lang.String eventMask) 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(java.lang.Class<? extends ManagerEvent> userEventClass) Registers a new user event type.
void	removeEventListener(ManagerEventListener listener) 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	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.
void	setDefaultResponseTimeout(long defaultResponseTimeout) Sets the time in milliseconds the synchronous method sendAction(ManagerAction) will wait for a response before throwing a TimeoutException.
void	setHostname(java.lang.String hostname) Sets the hostname of the asterisk server to connect to.
void	setKeepAliveAfterAuthenticationFailure(boolean keepAliveAfterAuthenticationFailure) Set to true to try reconnecting to ther asterisk serve even if the reconnection attempt threw an AuthenticationFailedException.
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	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.
void	setSsl(boolean ssl) Sets whether to use SSL.
void	setUsername(java.lang.String username) Sets the username to use to connect to the asterisk server.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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.

state

protected ManagerConnectionState state

Constructor Detail

ManagerConnectionImpl

public ManagerConnectionImpl()

Creates a new instance.

Method Detail

createReader

protected ManagerReader createReader(org.asteriskjava.manager.internal.Dispatcher dispatcher,
                                     java.lang.Object source)

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

setSsl

public void setSsl(boolean ssl)

Sets whether to use SSL.

Default is false.

Parameters:

ssl - true to use SSL for the connection, false for a plain text connection.

Since:

0.3

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

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

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 true.

Parameters:

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

getUsername

public java.lang.String getUsername()

Description copied from interface: ManagerConnection

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

Specified by:

getUsername in interface ManagerConnection

Returns:

the username to use for login

getPassword

public java.lang.String getPassword()

Description copied from interface: ManagerConnection

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

Specified by:

getPassword in interface ManagerConnection

Returns:

the password to use for login

getVersion

public AsteriskVersion getVersion()

Description copied from interface: ManagerConnection

Returns the version of Asterisk running in the server.

Specified by:

getVersion in interface ManagerConnection

Returns:

the Asterisk version running in the server.

getHostname

public java.lang.String getHostname()

Description copied from interface: ManagerConnection

Returns the hostname of the connected Asterisk server.

Specified by:

getHostname in interface ManagerConnection

Returns:

the hostname of the connected Asterisk server.

getPort

public int getPort()

Description copied from interface: ManagerConnection

Returns the Manager API port of the connected Asterisk server.

Specified by:

getPort in interface ManagerConnection

Returns:

the Manager API port of the connected Asterisk server.

isSsl

public boolean isSsl()

Description copied from interface: ManagerConnection

Returns whether to use SSL.

Default is false.

Specified by:

isSsl in interface ManagerConnection

Returns:

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

getLocalAddress

public java.net.InetAddress getLocalAddress()

Description copied from interface: ManagerConnection

Returns the local address of the underlying socket connection.

Specified by:

getLocalAddress in interface ManagerConnection

Returns:

the local address of the underlying socket connection.

getLocalPort

public int getLocalPort()

Description copied from interface: ManagerConnection

Returns the local port of the underlying socket connection.

Specified by:

getLocalPort in interface ManagerConnection

Returns:

the local port of the underlying socket connection.

getRemoteAddress

public java.net.InetAddress getRemoteAddress()

Description copied from interface: ManagerConnection

Returns the remote address of the underlying socket connection.

Specified by:

getRemoteAddress in interface ManagerConnection

Returns:

the remote address of the underlying socket connection.

getRemotePort

public int getRemotePort()

Description copied from interface: ManagerConnection

Returns the remote port of the underlying socket connection.

Specified by:

getRemotePort in interface ManagerConnection

Returns:

the remote port of the underlying socket connection.

registerUserEventClass

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

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

Specified by:

registerUserEventClass in interface ManagerConnection

Parameters:

userEventClass - the class representing 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)

setSocketReadTimeout

public void setSocketReadTimeout(int socketReadTimeout)

Description copied from interface: ManagerConnection

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.

Specified by:

setSocketReadTimeout in interface ManagerConnection

Parameters:

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

See Also:

Socket.setSoTimeout(int)

login

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

Description copied from interface: ManagerConnection

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

Specified by:

login in interface ManagerConnection

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

See Also:

LoginAction, ChallengeAction

login

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

Description copied from interface: ManagerConnection

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

Specified by:

login in interface ManagerConnection

Parameters:

eventMask - 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:

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

See Also:

LoginAction, ChallengeAction

doLogin

protected void doLogin(long timeout,
                       java.lang.String eventMask)
                throws java.io.IOException,
                       AuthenticationFailedException,
                       TimeoutException

Does the real login, following the steps outlined below.

1. Connects to the asterisk server by calling connect() if not already connected
2. Waits until the protocol identifier is received but not longer than timeout ms.
3. Sends a ChallengeAction requesting a challenge for authType MD5.
4. When the ChallengeResponse is received a LoginAction is sent using the calculated key (MD5 hash of the password appended to the received challenge).

Parameters:

timeout - the maximum time to wait for the protocol identifier (in ms)

eventMask - 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:

java.io.IOException - if there is an i/o problem.

AuthenticationFailedException - if username or password are incorrect and the login action returns an error or if the MD5 hash cannot be computed. The connection is closed in this case.

TimeoutException - if a timeout occurs while waiting for the protocol identifier. The connection is closed in this case.

determineVersion

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

Throws:

java.io.IOException

TimeoutException

getRawVersion

protected java.lang.String getRawVersion()

connect

protected void connect()
                throws java.io.IOException

Throws:

java.io.IOException

createSocket

protected SocketConnectionFacade createSocket()
                                       throws java.io.IOException

Throws:

java.io.IOException

logoff

public void logoff()
            throws java.lang.IllegalStateException

Description copied from interface: ManagerConnection

Sends a LogoffAction to the Asterisk server and disconnects.

Specified by:

logoff in interface ManagerConnection

Throws:

java.lang.IllegalStateException - if not in state CONNECTED or RECONNECTING.

See Also:

LogoffAction

disconnect

protected void disconnect()

Closes the socket connection.

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, SendActionCallback)

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, SendActionCallback)

sendAction

public void sendAction(ManagerAction action,
                       SendActionCallback callback)
                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. 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.

Specified by:

sendAction in interface ManagerConnection

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:

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 the 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 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.

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

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 action complete event 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

addEventListener

public void addEventListener(ManagerEventListener listener)

Description copied from interface: ManagerConnection

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.

Specified by:

addEventListener in interface ManagerConnection

Parameters:

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

See Also:

ManagerConnection.removeEventListener(ManagerEventListener)

removeEventListener

public void removeEventListener(ManagerEventListener listener)

Description copied from interface: ManagerConnection

Unregisters a previously registered event listener.

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

Specified by:

removeEventListener in interface ManagerConnection

Parameters:

listener - the listener to remove

See Also:

ManagerConnection.addEventListener(ManagerEventListener)

getProtocolIdentifier

public java.lang.String getProtocolIdentifier()

Description copied from interface: ManagerConnection

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

getState

public ManagerConnectionState getState()

Description copied from interface: ManagerConnection

Returns the lifecycle status of this connection.

Specified by:

getState in interface ManagerConnection

Returns:

the lifecycle status 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 SendActionCallback.

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.

Parameters:

event - the event received by the reader

See Also:

addEventListener(ManagerEventListener), removeEventListener(ManagerEventListener), ManagerReader

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object