Asterisk-Java

org.asteriskjava.live
Interface AsteriskServer

All Known Implementing Classes:
AsteriskServerImpl, DefaultAsteriskServer, SecureAsteriskServer

public interface AsteriskServer

The AsteriskServer is built on top of the ManagerConnection and is an attempt to simplify interaction with Asterisk by abstracting the interface.

You will certainly have less freedom using AsteriskServer but it will make life easier for easy things (like originating a call or getting a list of open channels).

AsteriskServer is still in an early state of development. So, when using AsteriskServer be aware that it might change in the future.

Version:
$Id: AsteriskServer.java 1371 2009-10-13 04:17:42Z srt $
Author:
srt

Method Summary
 void addAsteriskServerListener(AsteriskServerListener listener)
          Adds a listener to this AsteriskServer.

If this server is not yet connected it will be implicitly connected.

 java.util.List<java.lang.String> executeCliCommand(java.lang.String command)
          Executes a command line interface (CLI) command.
 java.util.Collection<AsteriskAgent> getAgents()
          Return the agents, registered at Asterisk server.
 AsteriskChannel getChannelById(java.lang.String id)
          Returns a channel by its unique id.
 AsteriskChannel getChannelByName(java.lang.String name)
          Returns a channel by its name.
 java.util.Collection<AsteriskChannel> getChannels()
          Returns the active channels of the Asterisk server.
 ConfigFile getConfig(java.lang.String filename)
          Reads the given Asterisk configuration file.
 java.lang.String getGlobalVariable(java.lang.String variable)
          Returns the value of the given global variable.
 ManagerConnection getManagerConnection()
          Returns the underlying ManagerConnection.
 MeetMeRoom getMeetMeRoom(java.lang.String roomNumber)
          Returns the MeetMe room with the given number, if the room does not yet exist a new MeetMeRoom object is created.
 java.util.Collection<MeetMeRoom> getMeetMeRooms()
          Returns the acitve MeetMe rooms on the Asterisk server.
 java.util.Collection<AsteriskQueue> getQueues()
          Returns the queues served by the Asterisk server.
 java.lang.String getVersion()
          Returns the exact version string of this Asterisk server.
 int[] getVersion(java.lang.String file)
          Returns the CVS revision of a given source file of this Asterisk server.
 java.util.Collection<Voicemailbox> getVoicemailboxes()
          Returns a collection of all voicemailboxes configured for this Asterisk server with the number of new and old messages they contain.
 void initialize()
          Opens the connection to this server.
 boolean isModuleLoaded(java.lang.String module)
          Checks whether a module is currently loaded.
 void loadModule(java.lang.String module)
          Loads a module or subsystem
 AsteriskChannel originate(OriginateAction originateAction)
          Generates an outgoing channel.
 void originateAsync(OriginateAction originateAction, OriginateCallback cb)
          Asynchronously generates an outgoing channel.
 AsteriskChannel originateToApplication(java.lang.String channel, java.lang.String application, java.lang.String data, long timeout)
          Generates an outgoing channel to an application.
 AsteriskChannel originateToApplication(java.lang.String channel, java.lang.String application, java.lang.String data, long timeout, CallerId callerId, java.util.Map<java.lang.String,java.lang.String> variables)
          Generates an outgoing channel to an application and sets an optional map of channel variables.
 void originateToApplicationAsync(java.lang.String channel, java.lang.String application, java.lang.String data, long timeout, CallerId callerId, java.util.Map<java.lang.String,java.lang.String> variables, OriginateCallback callback)
          Asynchronously generates an outgoing channel to an application and sets an optional map of channel variables.
 void originateToApplicationAsync(java.lang.String channel, java.lang.String application, java.lang.String data, long timeout, OriginateCallback callback)
          Asynchronously generates an outgoing channel to an application.
 AsteriskChannel originateToExtension(java.lang.String channel, java.lang.String context, java.lang.String exten, int priority, long timeout)
          Generates an outgoing channel to a dialplan entry (extension, context, priority).
 AsteriskChannel originateToExtension(java.lang.String channel, java.lang.String context, java.lang.String exten, int priority, long timeout, CallerId callerId, java.util.Map<java.lang.String,java.lang.String> variables)
          Generates an outgoing channel to a dialplan entry (extension, context, priority) and sets an optional map of channel variables.
 void originateToExtensionAsync(java.lang.String channel, java.lang.String context, java.lang.String exten, int priority, long timeout, CallerId callerId, java.util.Map<java.lang.String,java.lang.String> variables, OriginateCallback callback)
          Asynchronously generates an outgoing channel to a dialplan entry (extension, context, priority) and sets an optional map of channel variables.
 void originateToExtensionAsync(java.lang.String channel, java.lang.String context, java.lang.String exten, int priority, long timeout, OriginateCallback callback)
          Asynchronously generates an outgoing channel to a dialplan entry (extension, context, priority).
 void reloadAllModules()
          Reloads all currently loaded modules.
 void reloadModule(java.lang.String module)
          Reloads a module or subsystem.
 void removeAsteriskServerListener(AsteriskServerListener listener)
          Removes a listener from this Asterisk server.
 void setGlobalVariable(java.lang.String variable, java.lang.String value)
          Sets the value of the given global variable.
 void shutdown()
          Closes the connection to this server.
 void unloadModule(java.lang.String module)
          Unloads a module or subsystem.
 

Method Detail

getManagerConnection

ManagerConnection getManagerConnection()
Returns the underlying ManagerConnection.

Unlike the methods operating on the manager connection this method does not implicitly initialize the connection. Thus you can use this method to add custom ManagerEventListeners before the connection to the Asterisk server is established. If you want to ensure that the connection is established call initialize().

Returns:
the underlying ManagerConnection.

originate

AsteriskChannel originate(OriginateAction originateAction)
                          throws ManagerCommunicationException,
                                 NoSuchChannelException
Generates an outgoing channel.

Parameters:
originateAction - the action that contains parameters for the originate
Returns:
the generated channel
Throws:
NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateAsync

void originateAsync(OriginateAction originateAction,
                    OriginateCallback cb)
                    throws ManagerCommunicationException
Asynchronously generates an outgoing channel.

Parameters:
originateAction - the action that contains parameters for the originate
cb - callback to inform about the result
Throws:
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToExtension

AsteriskChannel originateToExtension(java.lang.String channel,
                                     java.lang.String context,
                                     java.lang.String exten,
                                     int priority,
                                     long timeout)
                                     throws ManagerCommunicationException,
                                            NoSuchChannelException
Generates an outgoing channel to a dialplan entry (extension, context, priority).

Parameters:
channel - channel name to call, for example "SIP/1310".
context - context to connect to
exten - extension to connect to
priority - priority to connect to
timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)
Returns:
the generated channel
Throws:
NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToExtension

AsteriskChannel originateToExtension(java.lang.String channel,
                                     java.lang.String context,
                                     java.lang.String exten,
                                     int priority,
                                     long timeout,
                                     CallerId callerId,
                                     java.util.Map<java.lang.String,java.lang.String> variables)
                                     throws ManagerCommunicationException,
                                            NoSuchChannelException
Generates an outgoing channel to a dialplan entry (extension, context, priority) and sets an optional map of channel variables.

Parameters:
channel - channel name to call, for example "SIP/1310".
context - context to connect to
exten - extension to connect to
priority - priority to connect to
timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)
callerId - callerId to use for the outgoing channel, may be null.
variables - channel variables to set, may be null.
Returns:
the generated channel
Throws:
NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToApplication

AsteriskChannel originateToApplication(java.lang.String channel,
                                       java.lang.String application,
                                       java.lang.String data,
                                       long timeout)
                                       throws ManagerCommunicationException,
                                              NoSuchChannelException
Generates an outgoing channel to an application.

Parameters:
channel - channel name to call, for example "SIP/1310".
application - application to connect to, for example "MeetMe"
data - data to pass to the application, for example "1000|d", may be null.
timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)
Returns:
the generated channel
Throws:
NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToApplication

AsteriskChannel originateToApplication(java.lang.String channel,
                                       java.lang.String application,
                                       java.lang.String data,
                                       long timeout,
                                       CallerId callerId,
                                       java.util.Map<java.lang.String,java.lang.String> variables)
                                       throws ManagerCommunicationException,
                                              NoSuchChannelException
Generates an outgoing channel to an application and sets an optional map of channel variables.

Parameters:
channel - channel name to call, for example "SIP/1310".
application - application to connect to, for example "MeetMe"
data - data to pass to the application, for example "1000|d", may be null.
timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)
callerId - callerId to use for the outgoing channel, may be null.
variables - channel variables to set, may be null.
Returns:
the generated channel
Throws:
NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToExtensionAsync

void originateToExtensionAsync(java.lang.String channel,
                               java.lang.String context,
                               java.lang.String exten,
                               int priority,
                               long timeout,
                               OriginateCallback callback)
                               throws ManagerCommunicationException
Asynchronously generates an outgoing channel to a dialplan entry (extension, context, priority).

Parameters:
channel - channel name to call, for example "SIP/1310".
context - context to connect to
exten - extension to connect to
priority - priority to connect to
timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)
callback - callback to inform about the result
Throws:
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToExtensionAsync

void originateToExtensionAsync(java.lang.String channel,
                               java.lang.String context,
                               java.lang.String exten,
                               int priority,
                               long timeout,
                               CallerId callerId,
                               java.util.Map<java.lang.String,java.lang.String> variables,
                               OriginateCallback callback)
                               throws ManagerCommunicationException
Asynchronously generates an outgoing channel to a dialplan entry (extension, context, priority) and sets an optional map of channel variables.

Parameters:
channel - channel name to call, for example "SIP/1310".
context - context to connect to
exten - extension to connect to
priority - priority to connect to
timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)
callerId - callerId to use for the outgoing channel, may be null.
variables - channel variables to set, may be null.
callback - callback to inform about the result
Throws:
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToApplicationAsync

void originateToApplicationAsync(java.lang.String channel,
                                 java.lang.String application,
                                 java.lang.String data,
                                 long timeout,
                                 OriginateCallback callback)
                                 throws ManagerCommunicationException
Asynchronously generates an outgoing channel to an application.

Parameters:
channel - channel name to call, for example "SIP/1310".
application - application to connect to, for example "MeetMe"
data - data to pass to the application, for example "1000|d", may be null.
timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)
callback - callback to inform about the result
Throws:
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToApplicationAsync

void originateToApplicationAsync(java.lang.String channel,
                                 java.lang.String application,
                                 java.lang.String data,
                                 long timeout,
                                 CallerId callerId,
                                 java.util.Map<java.lang.String,java.lang.String> variables,
                                 OriginateCallback callback)
                                 throws ManagerCommunicationException
Asynchronously generates an outgoing channel to an application and sets an optional map of channel variables.

Parameters:
channel - channel name to call, for example "SIP/1310".
application - application to connect to, for example "MeetMe"
data - data to pass to the application, for example "1000|d", may be null.
timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)
callerId - callerId to use for the outgoing channel, may be null.
variables - channel variables to set, may be null.
callback - callback to inform about the result
Throws:
ManagerCommunicationException - if the originate action cannot be sent to Asterisk

getChannels

java.util.Collection<AsteriskChannel> getChannels()
                                                  throws ManagerCommunicationException
Returns the active channels of the Asterisk server.

Returns:
a Collection of active channels.
Throws:
ManagerCommunicationException - if there is a problem communication with Asterisk

getChannelByName

AsteriskChannel getChannelByName(java.lang.String name)
                                 throws ManagerCommunicationException
Returns a channel by its name.

Parameters:
name - name of the channel to return
Returns:
the channel with the given name or null if there is no such channel.
Throws:
ManagerCommunicationException - if there is a problem communication with Asterisk

getChannelById

AsteriskChannel getChannelById(java.lang.String id)
                               throws ManagerCommunicationException
Returns a channel by its unique id.

Parameters:
id - the unique id of the channel to return
Returns:
the channel with the given unique id or null if there is no such channel.
Throws:
ManagerCommunicationException - if there is a problem communication with Asterisk

getMeetMeRooms

java.util.Collection<MeetMeRoom> getMeetMeRooms()
                                                throws ManagerCommunicationException
Returns the acitve MeetMe rooms on the Asterisk server.

Returns:
a Collection of MeetMeRooms
Throws:
ManagerCommunicationException - if there is a problem communication with Asterisk

getMeetMeRoom

MeetMeRoom getMeetMeRoom(java.lang.String roomNumber)
                         throws ManagerCommunicationException
Returns the MeetMe room with the given number, if the room does not yet exist a new MeetMeRoom object is created.

Parameters:
roomNumber - the number of the room to return
Returns:
the MeetMe room with the given number.
Throws:
ManagerCommunicationException - if there is a problem communication with Asterisk

getQueues

java.util.Collection<AsteriskQueue> getQueues()
                                              throws ManagerCommunicationException
Returns the queues served by the Asterisk server.

Returns:
a Collection of queues.
Throws:
ManagerCommunicationException - if there is a problem communication with Asterisk

getAgents

java.util.Collection<AsteriskAgent> getAgents()
                                              throws ManagerCommunicationException
Return the agents, registered at Asterisk server. (Consider remarks for AsteriskAgent)

Returns:
a Collection of agents
Throws:
ManagerCommunicationException - if there is a problem communication with Asterisk

getVersion

java.lang.String getVersion()
                            throws ManagerCommunicationException
Returns the exact version string of this Asterisk server.

This typically looks like "Asterisk 1.2.9.1-BRIstuffed-0.3.0-PRE-1q built by root @ pbx0 on a i686 running Linux on 2006-06-20 20:21:30 UTC".

Returns:
the version of this Asterisk server
Throws:
ManagerCommunicationException - if the version cannot be retrieved from Asterisk
Since:
0.2

getVersion

int[] getVersion(java.lang.String file)
                 throws ManagerCommunicationException
Returns the CVS revision of a given source file of this Asterisk server.

For example getVersion("app_meetme.c") may return {1, 102} for CVS revision "1.102".

Note that this feature is not available with Asterisk 1.0.x.

You can use this feature if you need to write applications that behave different depending on specific modules being available in a specific version or not.

Parameters:
file - the file for which to get the version like "app_meetme.c"
Returns:
the CVS revision of the file, or null if that file is not part of the Asterisk instance you are connected to (maybe due to a module that provides it has not been loaded) or if you are connected to an Astersion 1.0.x
Throws:
ManagerCommunicationException - if the version cannot be retrieved from Asterisk
Since:
0.2

getGlobalVariable

java.lang.String getGlobalVariable(java.lang.String variable)
                                   throws ManagerCommunicationException
Returns the value of the given global variable.

Parameters:
variable - the name of the global variable to return.
Returns:
the value of the global variable or null if it is not set.
Throws:
ManagerCommunicationException - if the get variable action cannot be sent to Asterisk.
Since:
0.3

setGlobalVariable

void setGlobalVariable(java.lang.String variable,
                       java.lang.String value)
                       throws ManagerCommunicationException
Sets the value of the given global variable.

Parameters:
variable - the name of the global variable to set.
value - the value of the global variable to set.
Throws:
ManagerCommunicationException - if the set variable action cannot be sent to Asterisk.
Since:
0.3

getVoicemailboxes

java.util.Collection<Voicemailbox> getVoicemailboxes()
                                                     throws ManagerCommunicationException
Returns a collection of all voicemailboxes configured for this Asterisk server with the number of new and old messages they contain.

Returns:
a collection of all voicemailboxes configured for this Asterisk server
Throws:
ManagerCommunicationException - if the voicemailboxes can't be retrieved.
Since:
0.3

executeCliCommand

java.util.List<java.lang.String> executeCliCommand(java.lang.String command)
                                                   throws ManagerCommunicationException
Executes a command line interface (CLI) command.

Parameters:
command - the command to execute, for example "sip show peers".
Returns:
a List containing strings representing the lines returned by the CLI command.
Throws:
ManagerCommunicationException - if the command can't be executed.
Since:
0.3
See Also:
CommandAction

isModuleLoaded

boolean isModuleLoaded(java.lang.String module)
                       throws ManagerCommunicationException
Checks whether a module is currently loaded.

Available since Asterisk 1.6

Parameters:
module - name of the module to load (with out without the ".so" extension).
Returns:
true if the module is currently loaded, false otherwise.
Throws:
ManagerCommunicationException - if the module can't be checked.

loadModule

void loadModule(java.lang.String module)
                throws ManagerCommunicationException
Loads a module or subsystem

Available since Asterisk 1.6

Parameters:
module - name of the module to load (including ".so" extension) or subsystem name.
Throws:
ManagerCommunicationException - if the module cannot be loaded.
Since:
1.0.0

unloadModule

void unloadModule(java.lang.String module)
                  throws ManagerCommunicationException
Unloads a module or subsystem.

Available since Asterisk 1.6

Parameters:
module - name of the module to unload (including ".so" extension) or subsystem name.
Throws:
ManagerCommunicationException - if the module cannot be unloaded.
Since:
1.0.0

reloadModule

void reloadModule(java.lang.String module)
                  throws ManagerCommunicationException
Reloads a module or subsystem.

Available since Asterisk 1.6

Parameters:
module - name of the module to reload (including ".so" extension) or subsystem name.
Throws:
ManagerCommunicationException - if the module cannot be reloaded.
Since:
1.0.0

reloadAllModules

void reloadAllModules()
                      throws ManagerCommunicationException
Reloads all currently loaded modules.

Available since Asterisk 1.6

Throws:
ManagerCommunicationException - if the modules cannot be reloaded.
Since:
1.0.0

getConfig

ConfigFile getConfig(java.lang.String filename)
                     throws ManagerCommunicationException
Reads the given Asterisk configuration file.

Parameters:
filename - the filename, for example "voicemail.conf".
Returns:
the configuration file.
Throws:
ManagerCommunicationException - if the command can't be executed.

addAsteriskServerListener

void addAsteriskServerListener(AsteriskServerListener listener)
                               throws ManagerCommunicationException
Adds a listener to this AsteriskServer.

If this server is not yet connected it will be implicitly connected.

Parameters:
listener - the listener to add.
Throws:
ManagerCommunicationException - if the server is not yet connected and the connection or initialization fails.

removeAsteriskServerListener

void removeAsteriskServerListener(AsteriskServerListener listener)
Removes a listener from this Asterisk server.

Parameters:
listener - the listener to remove.

shutdown

void shutdown()
Closes the connection to this server.


initialize

void initialize()
                throws ManagerCommunicationException
Opens the connection to this server.

Throws:
ManagerCommunicationException - if login fails

Asterisk-Java

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