Developers Guide

Where do I start?

The API documentation contains information on all the classes that form OrderlyCalls.

The Example Applications contain useful example code.

The licensing guide describes the classes you're most likely to need to use.

AGI or Manager?

Astersisk supports two integration protocols, FastAGI and Manager.

Some functions are available over both protocols.

In general, AGI only provides support for handling individual calls, wheras Manager contains commands that can affect Asterisk more broadly.

There are a number of known problems, particularly involving message collision, where using Manager has been known to crash Asterisk. These problems are not caused by OrderlyCalls, which implements a message queue to try to prevent collisions.

Therefore, in general, if you are writing an application to handle calls, you should use AGI wherever possible. You should only use Manager where no AGI function exists that does what you need it to do.

AGI and Manager can be used in conjunction using OrderlyCalls - please see the ExampleProcessor class for example code.

Where should I put my classes?

In general you should not add your own classes to orderlycalls.jar; instead you should create your own jars or directories for your own classes. This means that you (and people using your code) can update OrderlyCalls independently of the rest of your system.

Where should I put my settings?

Initialisation settings should go in OrderlyCalls.xml. You may need to extend the Settings class to read any additional settings you need.

Servlet (Tomcat) Guide

In addition to working as a stand-alone application server, OrderlyCalls is designed to work inside J2EE servlet containers such as Apache Tomcat.

This distribution contains a .war file that, when deployed, will instantiate and initialise your OrderlyCalls services, which can then be accessed from inside your own servlets.

The source for the .war is in the src/jsp directory, and the war is compiled from scratch by the ant build script.

The .war contains a copy of OrderlyCalls.xml, which is copied from the root ORDERLYCALLS_HOME directory when the .war is compiled - this means you shouldn't make changes to the OrderlyCalls.xml file inside src/jsp/WEB-INF, as these will be overwritten by ant.

Using OrderlyCalls.war

When deployed, orderlycalls.war initialises the OrderlyCalls services on context-start using the OrderlyCallsWebDeployer. This is configured inside WEB-INF/web.xml. If you're deploying orderlycalls.war, you do not have to initialise your own services - this is done for you.

You can add your own services for initialisation by OrderlyCallsWebDeployer by including them in OrderlyCalls.xml. You'll need to include any additional classes in the WEB-INF/src directory of the orderlycalls.war file, or in a jar inside TOMCAT_HOME/common/lib, in order for Tomcat to be able to find them for OrderlyCalls.

Using your own .war files

You can use OrderlyCalls.war to initialise your services, then access them from inside other .wars/contexts.

Alternatively, you can include the classes and configuration data in other .war files; in this case you must take responsibility for creating and initialising the necessary Settings and Service objects, and adding them to the OrderlyCalls framework using OrderlyCalls.addService().

Accessing OrderlyCalls Services

Typically, you'll configure your services inside OrderlyCalls.xml. You can then access them from any context by calling OrderlyCalls.getService(name).

Please see the example jsp pages and code for further details.