Before continuing, we need to understand a little about ARI 🤔

ARI is an asynchronous API that allows developers to build communications applications by exposing the raw primitive objects in Asterisk - channels, bridges, endpoints, media, etc. - through an intuitive REST interface. The state of the objects being controlled by the user are conveyed via JSON events over a WebSocket. ( From the Asterisk Wiki )

ARI is quite a low level API, which means the application you build with ARI needs to take on a lot of responsibilities for those raw primitive objects. Your application should be reacting to state changes on those objects, there are 3 ways to get the state changes:

1. By creating the object using the API
2. By using the Stasis Dialplan application
3. By subscribing to the object using the API.

First off we'll need to setup Asterisk, then we can get into the Java code 😀
(:spiral_notepad: the Examples has a vagrant box which does the setup automatically 😎)

Edit /etc/asterisk/ari.conf and create a user ari4java that we will use for connecting.

[general]
enabled = yes

[ari4java]
type = user
read_only = no
password = yothere
password_format = plain

Edit /etc/asterisk/http.conf and turn on the embedded HTTP server.

[general]
enabled=yes
bindaddr=0.0.0.0  
bindport=8088

Reload Asterisk and connect to its CLI; if all goes well you should see:

localhost*CLI> ari show users
r/o?  Username
----  --------
No    ari4java

We suggest using Gradle, so in your build.gradle

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'ch.loway.oss.ari4java:ari4java:+'
    implementation 'ch.qos.logback:logback-classic:1.2.10'
}

ARI ari = ARI.build("http://192.168.56.44:8088/", "test-app", "ari4java", "yothere", AriVersion.IM_FEELING_LUCKY);

Assuming 192.168.56.44 is the IP of your Asterisk server. Using AriVersion.IM_FEELING_LUCKY is not recommended as we try determine the version by connecting to Asterisk. It is better to use a specific version like AriVersion.ARI_5_0_0 see the Asterisk Version to ARI Version page. (It's just easier for examples to use AriVersion.IM_FEELING_LUCKY).

ARI produces events that your application needs to respond to this is how

ari.events().eventWebsocket("test-app").execute(new AriWSCallback<Message>() {new AriWSCallback<List<Channel>>() {
    @Override
    public void onSuccess(List<Channel> result) {
        // code to handle the result ...
    }
    @Override
    public void onFailure(RestException e) {
        e.printStackTrace();
    }
    @Override
    public void onConnectionEvent(AriConnectionEvent event) {
        // if you wish to know the status (connected/disconnected) of the WS connection
    }
});

There is also an AriWSHelper abstract class that helps you get all the events as separate methods. It's also advised to offload the work to an ExecutorService (aka thread pool) to avoid the Netty WorkerGroup exhaustion.

final ExecutorService threadPool = Executors.newFixedThreadPool(10);
ari.events().eventWebsocket(APP_NAME).execute(new AriWSHelper() {
    @Override
    public void onSuccess(Message message) {
        threadPool.execute(() -> super.onSuccess(message));
    }

    @Override
    protected void onStasisStart(StasisStart message) {
        // code to handle Stasis Start...
    }
});

The easiest thing we can do is a synchronous query to list active channels.

List<Channel> channels = ari.channels().list().execute();

Please note that what we get back is Java objects, not just JSON blobs. Everything is strongly typed.

A non-blocking way is also available by supplying a callback to the execute.

ari.channels().list().execute(new AriCallback<List<Channel>>() {
    @Override
    public void onSuccess(List<Channel> result) {
        // code to handle the result ...
    }
    @Override
    public void onFailure(RestException e) {
        e.printStackTrace();
    }
});

💥 Happy hacking! 😎