Asterisk-Java

Visualizing your dialplan with a graph

A few weeks ago, Matt Gibson posted on the asterisk-users discussion list that he was looking for a GraphViz script he had heard about a few years ago that could generate graphs of Asterisk's extensions.conf file that defines the dialplan. At the time, I had been working on a recently open-sourced application, EgoNet, for a researcher I work with. This application taught me much about social networks, particularly his specialty of egocentric networks, and it also helped me learn a ton about the Java Universal Network/Graph Framework (or JUNG). I immediately thought about combining my experience with JUNG and Asterisk, and wrote a rudimentary (read as: extremely ugly) parser for extensions.conf and generated a crude graph of the sample dialplan.

DefaultAgiServer in JBoss AS 4.x

A recent post to the mailing list asked about how to stop and start a FastAGI server and how folks host Fast AGI servers. I shared some code I wrote for a small MBean that starts and stops a DefaultAgiServer from Asterisk-Java -- see the last FAQ question "Can I have an example of using an AGI server in a container like JBoss?". The MBean uses the JBoss-specific @Management annotation.

I work on a home-grown call center management application (EJBs, JSP webpages, and two standalone Java Swing applications, all talking through JBoss Application Server), and we've already been able to add a couple features with Asterisk-Java that add value and utility to our application. I didn't want to introduce another service to our infrastructure and I also didn't want to write an entirely new Agi server, as Stefan had done a great job on that part. Thus, the above MBean was born.

Comments and suggestions and other examples of how you run your Agi scripts are welcome and encouraged on our mailing lists.

A Visual Overview Of Asterisk-Java

Atlassian has improved the charting features in their latest release of Fisheye. So I had a look at the Asterisk-Java code base to see how it's major packages compare in size. This is what i got:

Let's have a look at the individual packages:

The Manager API

Support for the Manager API (manager) is by far the biggest package in Asterisk-Java. It provides access to a variety of Asterisk features from call control to monitoring and call center management. The size of this package and its steady groth ressemble the groth of features exposed by Asterisk.

The Asterisk Gateway Interface

FastAGI is an easy way to implement IVR applications in Java. The feature set is quite stable over time so we don't see significant changes in the code base. You'll even notice that support for AsyncAGI (i.e. running AGI scripts over the Manager API) was a quick win as it didn't have a significant impact on the overall size of the package.

Parsing Configuration Files

The config package is quite new and supports parsing Asterisk's configuration files. All config files use the same syntax and group up configuration items into contexts. It supports inheritance of contexts, includes and forms the basis for further development like configuration editors or dialplan visualization (stay tuned for more information from Martin on this topic).
Originally developed to parse voicemail meta files the config package is certainly a candidate for future growth.

The Live API

The live API is our own invention and takes integration a step further. Instead of only providing access to the basic features exposed by Asterisk the live API offers real objects with state and behavior that model core concepts found in Asterisk. There are channel objects with state like the current caller id, the progress or hangup reason and methods to redirect channels, start and stop monitoring and much more.
The live API speeds up developers by hiding the sometimes tedious details of the low level Asterisk APIs and has reached a significant size. Next to the config package the live API is under active development and will certainly grow in the future.

Users: Astersik and SugarCRM

Mauro has published an interesting article about Asterisk and SugarCRM integration. A swing popup notifies its user on incoming calls and provides additional information about the customer that is retrieved from SugarCRM.

The sample application serves as a good example on how to use Asterisk's Manager API with Asterisk-Java.

References

Mauro: SugarCRM and Asterisk integration in Java

Preview: Support for AsyncAGI

I've just finished adding support for Asynchronous AGI to Asterisk-Java. AsyncAGI allows you to run AGI scripts through a Manager API connection.

The way AsyncAGI is supported by Asterisk-Java hides the differences in the underlying communication from the users of our library. Your AGI scripts developed for FastAGI will run with AsyncAGI without a change.

To make use of AsyncAGI add the following extension to you dialplan:

exten => 1234,1,Agi(agi:async)

Create a simple AGI script, pass it to AsyncAgiServer and register the AsyncAgiServer as a listener to a ManagerConnection:

public class SampleScript extends BaseAgiScript
{
    public void service(AgiRequest request, AgiChannel channel) throws AgiException
    {
        channel.streamFile("tt-monkeys");
    }

    public static void main(String[] args) throws Exception
    {
        ManagerConnection connection;
        AsyncAgiServer agiServer;

        connection = new DefaultManagerConnection("localhost", "manager", "pa55w0rd");
        agiServer = new AsyncAgiServer(new SampleScript());
        connection.addEventListener(agiServer);
        connection.login();

        while (true)
        {
            Thread.sleep(1000L);
        }
    }
}

To run the sample you need the latest snapshot of Asterisk-Java 1.0.0 (at least 20080404.222056-117) and Asterisk 1.6.0.

References

Moy: Asterisk Asynchronous AGI

Frequently Asked Questions

Thanks to Martin we now have a FAQ section available as part of our documentation.

The FAQ covers the questions we encounter on our mailing lists and that we think will be interesting to a more general audience. Please check them before asking questions to make sure you don't ask questions again that have already been answered before.

If you notice anything we've missed feel free to post a comment or join our mailing list and propose your addition.

References

Asterisk-Java Frequently Asked Questions

Users: Conferencing for snom Phones

Andreas Neugebauer's submission to the snom XML Contest was a conferencing application for Asterisk:

XMLConference uses the Asterisk Manager interface, and shows call-related information on the snom phone display and allows you to interact with these calls.

XMLConference uses Asterisk-Java's implementation of the Manager API to control Asterisk MeetMe rooms and make them available to the snom XML browser. It runs in a standard Java web container like Apache Tomcat.

References

XMLConference inlcudes source code and binaries
The snom XML Contest

AGI scripts in BeanShell

beanizer.org has published an interesting article on how to build an AGI server with Asterisk-Java to run AGI scripts written in BeanShell.

They provide a dispatcher AgiScript that delegates to a BeanShell script and provides some additional convenience functions to make the custom scripts easy to implement.

The advantages of using scripting languages on the JVM along with Asterisk-Java are compelling:

The approach is quite flexible, our script engine doesn't need to be on the same computer the pbx is on, and we can add/modify our scripts on the fly without need for compilation or engine restart.

You might also be interested in our recent posting on writing AGI scripts in Groovy that describes a similar approach with a focus on Groovy.

References

Words Of Praise

While skipping through our referrer list I stumbled upon this comment from a French user:

Ahhhh !!!
Asterisk-Java, quelle belle API. C'est la plus complète parmi celles que l'on puisse trouver pour interroger le manager ou développer des "scripts" AGI.
Coder avec cette API est vraiment d'une simplicité... :-) Bon, c'est Java... On regrettera juste qu'il n'y ai rien vraiment à la hauteur pour d'autres langages.

It seems like even developers not devoted to Java are in love with our library.
Interestingly enough there a quite few developers using other languages than Java who are using our javadocs as a general purpose reference to the Manager and FastAGI API.

Thanks for your kind works, it helps us keep up further enhancing Asterisk-Java.

Asterisk 1.6.0-beta1 Released

Since a few days the first beta of Asterisk 1.6.0 is available for download.

So far, Asterisk-Java seems to work fine with the new release.
If you encounter any problems feel free to post a comment, join our mailing list or post a bug report.

Update 2008-01-29:

...and they followed up with 1.6.0-beta2.

For the 1.4 series they start providing release candidates, an idea that was discussed on the -dev list before and aims at providing better qualitiy for the final production releases:

The release candidate for 1.4.18 is only available via svn. It is available for anyone that would like to help test 1.4.18 over the next couple of days before it gets officially released.

Grab it from http://svn.digium.com/svn/asterisk/tags/1.4.18.