Activities are a new layer in to Asterisk-Java 2.0.

Traditionally when communicating with Asterisk you sent Actions and received Events and responses. These raw asterisk tools allow fantastic control over Asterisk but they are complicated and often counter intuitive.

The aim of Activities is to hide the details behind Actions and Events and make working with Asterisk simple and intuitive.

Lets have a look at the range of Activities available and how you access them. The Getting Started guide provides a detailed example of how to write your first activity and there is example code in the asterisk-java project under the package:

package org.asteriskjava.examples.activities;

Activities are accessed via the java 'PBX' interface.

PBX pbx = PBXFactory.getActivePBX();

Most activities have both a synchronous and an asynchronous method. The synchronous method is for quick and dirty functions but real programs should normally use the asynchronous method as the synchronous methods can result in your code hanging for long periods of time whilst a pbx action completes.

You probably notice a few unfamiliar classes and interfaces when you start using Activities:

• Call
• Channel
• EndPoint
• Trunk

Along with activities we have introduce a set of classes and interfaces that are designed to better encapsulate a number of key concepts in asterisk java.

Traditionally 'channels' have been passed around as strings such as 'sip/100'. The problem with this method is that we can't take advantage of Java's type checking and we end up having lots of duplicated string manipulation logic for channels. In many cases the asterisk-java events actually confuse channels and endpoints which makes it easy to mis-use the interfaces.

For clarity:

Call - holds one or more channels that are bridged.

Channel - is an entity representing part of a call. A connected call is normally composed of two channels. The Channel essentially wraps an Asterisk channel.

EndPoint - is a dial target such as an extension number or a phone number.

Trunk - A trunk that you dial through. Typically this is a SIP or ISDN trunk such as SIP/default.

The Channel and EndPoint interface remove the above noted difficulties as well as delivering a collection of useful methods that can be performed on each of these interfaces.

The second problem with passing channels with strings is that channels can be renamed during the life of a call. Many asterisk-java applications fail to recognize that channels can be renamed (unless you us sjSIP available in Asterisk 13 in which case renaming goes away). Channel renames are temporary states that a channel goes through (during actions like transfers) but if you try to perform an operation on a channel whilst it is being renamed your action will fail. To fix this problem Activities actually use a ChannelProxy class which wraps a ChannelImpl class. When you receive a Channel you are actually receiving an ChannelProxy which then wraps the ChannelImpl. The power of the ChannelProxy is that it manages the underlying Asterisk channel through any rename events so that you can always be certain that if you manipulate a Channel your action will actually succeed even if a rename is in progress.