Asterisk-Java

The Asterisk-Java package consists of a set of Java classes that allow you to easily build Java applications that interact with an Asterisk PBX Server. Asterisk-Java supports both interfaces that Asterisk provides for this scenario: The FastAGI protocol and the Manager API.

The FastAGI implementation supports all commands currently available from Asterisk.

The Manager API implementation supports receiving events from the Asterisk server (e.g. call progess, registered peers, channel state) and sending actions to Asterisk (e.g. originate call, agent login/logoff, start/stop voice recording).

A complete list of the available events and actions is available in the javadocs.

Asterisk-Java is available under Apache license from http://asterisk-java.org/.

News

09/05/2007:
Asterisk-Java 0.3.1 has been released.

07/01/2007:
Asterisk-Java 0.3 has been released.

02/12/2006:
Asterisk-Java 0.3-m2 has been released.

08/26/2006:
Asterisk-Java 0.3-m1 has been released.
The 0.3-m1 milestone release focuses on ease of use and provides the new org.asteriskjava.live package that takes care of the lowlevel action and event handling of the Manager API and offers an intuitive API for Java developers. Asterisk-Java has been updated to take advantage of the new features of Java 5.0 and therfore requires a Java Virtual Machine of at least version 1.5.0. The package name has been changed from net.sf.asterisk to org.asteriskjava.

11/27/2005:
Asterisk-Java 0.2 has been released.
Since 0.2-rc2 some minor bugs have been fixed and support for several last minute additions to Asterisk 1.2 has been added.

10/29/2005:
The 0.2-rc2 release candidate focuses on the new features of the Asterisk 1.2 series though it still supports Asterisk 1.0.x.
The changes include

• Bug fix for variables in OriginateAction (AJ-15)
• Support for FaxReceived event from spandsp (AJ-20)
• Better integration with Spring Framework via SimpleMappingStrategy and AGIServerThread

08/31/2005:
The 0.2-rc1 release candidate focuses on the new features of Asterisk 1.2-beta1 though it still supports Asterisk 1.0.x.
The changes include

• Support for the new Actions, Events and Commands of Asterisk 1.2
• New support for event generating Actions, i.e. Actions that send their result as a series of Event rather than the usual ManagerResults. See the sendEventGeneratingAction() methods in ManagerConnection for more information.
• New base class for AGI scripts that allows you write cleaner AGI scripts as you don't have to pass the channel variable to all methods.
• New convenience constructors for manager actions
• Some minor bug fixes

References

Asterisk-Java is used in several commercial environments and by the following Open Source projects:

• Asterisk-IM: A plugin for the Jive Messenger XMPP (jabber) server. It provides integrated presence between your IM client and phone, notification of incoming calls by IM and originate calls from supported IM clients.
• Asterisk Desktop Manager (ADM): A desktop application that will allow for automatic on-call volume reduction, one click dial from clipboard, integrated phonebook and more.

Examples

The following HelloAGIScript shows how a simple AGI script implemented using Asterisk-java might look like:

import net.sf.asterisk.fastagi.AGIChannel;
import net.sf.asterisk.fastagi.AGIException;
import net.sf.asterisk.fastagi.AGIRequest;
import net.sf.asterisk.fastagi.BaseAGIScript;

public class HelloAGIScript extends BaseAGIScript
{
    public void service(AGIRequest request, AGIChannel channel)
            throws AGIException
    {
        // Answer the channel...
        answer();
		
        // ...say hello...
        streamFile("welcome");
		
        // ...and hangup.
        hangup();
    }
}

Sending an action via the Manager API is also quite easy:

import java.io.IOException;

import net.sf.asterisk.manager.AuthenticationFailedException;
import net.sf.asterisk.manager.ManagerConnection;
import net.sf.asterisk.manager.ManagerConnectionFactory;
import net.sf.asterisk.manager.TimeoutException;
import net.sf.asterisk.manager.action.OriginateAction;
import net.sf.asterisk.manager.response.ManagerResponse;

public class HelloManager
{
    private ManagerConnection managerConnection;

    public HelloManager() throws IOException
    {
        ManagerConnectionFactory factory = new ManagerConnectionFactory();

        this.managerConnection = factory.getManagerConnection("localhost",
                "manager", "pa55w0rd");
    }

    public void run() throws IOException, AuthenticationFailedException,
            TimeoutException
    {
        OriginateAction originateAction;
        ManagerResponse originateResponse;

        originateAction = new OriginateAction();
        originateAction.setChannel("SIP/John");
        originateAction.setContext("default");
        originateAction.setExten("1300");
        originateAction.setPriority(new Integer(1));
        originateAction.setTimeout(new Integer(30000));

        // connect to Asterisk and log in
        managerConnection.login();

        // send the originate action and wait for a maximum of 30 seconds for Asterisk
        // to send a reply
        originateResponse = managerConnection.sendAction(originateAction, 30000);

        // print out whether the originate succeeded or not
        System.out.println(originateResponse.getResponse());

        // and finally log off and disconnect
        managerConnection.logoff();
    }

    public static void main(String[] args) throws Exception
    {
        HelloManager helloManager;

        helloManager = new HelloManager();
        helloManager.run();
    }
}

For a discussion of these examples see the Tutorial.

See also

• Asterisk AGI
• FastAGI: Run AGI remotely over TCP socket: agi://
• Asterisk manager API
• OrderlyCalls (successor to JAGIServer) offers full support for FastAGI and Manager in an easy-to-use Named Service environment. Includes Web Deployer for developing integrated VOIP-HTML applications.
• Another Java framework for FastAGI: http://tanesha.net/Wiki/JastAgi.html

---

Go back to Asterisk