org.asteriskjava.manager
Class DefaultManagerConnection

java.lang.Object
  org.asteriskjava.manager.DefaultManagerConnection

All Implemented Interfaces:

ManagerConnection

public class DefaultManagerConnection
extends java.lang.Object
implements ManagerConnection

Default implemention of the ManagerConnection interface.

Generelly avoid direct use of this class. Use a ManagerConnectionFactory to obtain a ManagerConnection instead.

When using a dependency injection framework like the Spring Framework 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 once it is ManagerConnectionState.CONNECTING.

Version:

$Id: DefaultManagerConnection.java 1155 2008-08-25 20:22:46Z srt $

Author:

srt

See Also:

ManagerConnectionFactory

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.

DefaultManagerConnection(java.lang.String hostname, java.lang.String username, java.lang.String password)
Creates a new instance with the given connection parameters using Asterisk's default port.

Method Summary

void	addEventListener(ManagerEventListener listener) Registers an event listener that is called whenever an ManagerEvent is receiced from the Asterisk server.
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".
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 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(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 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 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	setDefaultTimeout(long defaultTimeout) Deprecated. use setDefaultResponseTimeout(long) instead
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	setSleepTime(long sleepTime) Deprecated. no longer needed as we now use an interrupt based response checking approach.
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

Constructor Detail

DefaultManagerConnection

public DefaultManagerConnection()

Creates a new instance.

DefaultManagerConnection

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

Creates a new instance with the given connection parameters using Asterisk's default port.

Parameters:

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

username - the username to use for login

password - the password to use for login

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

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

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. no longer needed as we now use an interrupt based response checking approach.

This method is deprecated and will be removed in Asterisk-Java 0.4.

It does nothing.

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.

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.

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.

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.lang.IllegalStateException,
                  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.lang.IllegalStateException - if connection is not in state INITIAL or DISCONNECTED.

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 events)
           throws java.lang.IllegalStateException,
                  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:

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:

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

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

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

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

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

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object