Java ESL Client
This page documents the org.freeswitch.esl.client library maintained in the freeswitch-contrib git repository. See Java ESL page for overview of other options for using Java with the FreeSWITCH Event Socket.
- Licensed under Apache License version 2 http://www.apache.org/licenses/LICENSE-2.0
- Runtime dependency on Netty (Apache License) and SLF4j (MIT License) libraries
- No native library runtime dependencies
- ESL Inbound and Outbound support, see Event Socket and Event Socket Outbound.
- OSGi ready
- Built using maven
Getting Java ESL library
Binary jar files
Current released version
Each of these artifacts is signed with GPG key 1024D/74B7C72A (david.varnes [at] gmail [dot] com), which allows you to verify that the binary files you download are the same as those originally uploaded.
Download the artifacts directly from:
This is the hosted repository maintained by Sonatype for OSS projects. The files are automatically synced from there to the maven central repository
From maven central repository
Assuming you are using a build tool that can resolve dependencies from the maven 2 central repository, add the following to your project pom.xml
<dependencies> ... <dependency> <groupId>org.freeswitch.esl.client</groupId> <artifactId>org.freeswitch.esl.client</artifactId> <version>0.9.2</version> </dependency> ... </dependencies>
Note: The netty dependency is not available from the maven 2 central repository. Either:
- Follow the instructions in the netty website, or
- In your maven build activate the profile 'jboss-public-repository' which is in the org.freeswitch.esl.client pom, and will add the appropriate jboss repository to your build. ie: run
mvn install -Pjboss-public-repository
If you download and install the jar(s) manually, you must also supply the following jars on your Java classpath
- netty-3.2.1.Final.jar for async socket comms
- slf4j-api-1.6.1.jar for logging
- An slf4j implementation, use slf4j-nop.jar if no logging required.
Building from source in contrib git
The binary artifacts described above can of course be built from latest git HEAD (or TAG) using the following steps.
Build dependency on maven tool
A Java build tool analogous in some ways to 'autotools' and 'make' for the main FreeSWITCH code, this library is built using the maven build tool.
Installing maven is beyond the scope of this page, just use the latest available from the link, and it is also packaged for some of the major Linux distributions.
Maven will download the two compile dependencies (netty and slf4j-api) and the test dependency (logback) for you, as well as compile the java classes, run unit tests and assemble the 'jar' archive file.
Checkout from git
Must first install git. The code can be obtained from the freeswitch-contrib git repository. This command gets that repository (you get all the other good stuff in freeswitch-contrib too).
$ git clone git://git.freeswitch.org/freeswitch-contrib.git
Compiling, running tests and making jar
Assuming 'mvn' is on path.
$ cd freeswitch-contrib/dvarnes/java/esl-client $ mvn install
If this is the first time you have run the maven tool, it will take some time as it downloads a seemingly endless set of jars from the central maven repository. This will only happen the first time, subsequent builds will be much faster.
Note: some tests will try to connect to a running FreeSWITCH installation on the default port 8021 and password. See Configuration section of Event_Socket. These tests will not be run in a normal maven build, you will need to run them however you usually invoke junit test cases (IDE etc).
These tests try to connect to a host called 'freeswitch-test', so add an entry to your hosts file that points 'freeswitch-test' to a host that with a listening ESL socket, can be localhost.
For general usage of the ESL, browse the wiki, some links below. Each of the different wiki pages for various language bindings and clients have useful snippets and clues.
Chapter 9 of the FreeSWITCH Book also introduces events and the ESL.
Inbound client usage
A simple 'unit' test is included in the src/test/java directory of the source:
This test assumes that it can connect to a FreeSWITCH with the default socket port and password at a host called 'freeswitch-test' in your hosts file.
Note that the test source is not included in the packaged jar, it is available from the git repository.
Outbound socket client usage
A very simple example is implemented as an example included in the main client jar:
See the class
with an example of how to run it in the Outbound 'unit' test (really an application example) in the the src/test/java source directory.
In order to make the test work, configure an extension in a running FreeSWITCH similar to
<extension> <condition field="destination_number" expression="444"> <action application="socket" data="192.168.100.88:8084 async full"/> </condition> </extension>
where the IP address needs to be the address that the FreeSWITCH will connect to your running test. Then run the test, which gives you 45 seconds to make a call to extension 444 and watch the information logged to the console, before the call is hung up, and then the test will end (thus closing the outbound socket client).
Note that the unit test source described above is not included in the packaged jar, it is available from the git repository.
An application developer would need to extend (most importantly) the
and (trivially) the
classes with their own logic, and invoke the
TODO - set up module under FreeSWITCH Jira
As at 30 August 2010
- Add the content of this section to Jira
- Fill in the TODO items in this doco page
- Complete some more examples
- Complete the items in TODO.txt in root of project source
This java library was created and is maintained as a spare time effort.
You can donate to the author via paypal to david.varnes [at] gmail [dot] com