Mod java

From FreeSWITCH Wiki
(Redirected from Java)
Jump to: navigation, search

Contents

Status

mod_java is based on the swig wrapper used for mod_python so look there for any issues.

It's been tested with 1 call with Sun's Java 1.6 running the example script below and found to work.

Warning

NOTE: Sun JDK 1.6.0.05 has a bug which causes freeswitch (among other Java programs) to crash immediately. To avoid problems, use an earlier release of 1.6 or any of the 1.5 JDK series.
NOTE: Also sending the -HUP signal to FreeSWITCH while mod_java is loaded will make FreeSWITCH exit due to the fact the JVM calls exit(); when it receives a HUP.

 


Building mod_java

You need a Java JDK, version 1.5 or greater, to build mod_java (and a JRE of the same version to use it). If ./configure doesn't detect Java, you'll have to pass the --with-java=/path/to/jni.h/directory flag. Something like the following:

./configure --with-java=/usr/java/jdk1.6.0_16/include/

Edit modules.conf.xml and uncomment languages/mod_java javac and jar have to be on your PATH during compilation. make installall

Enabling mod_java

Edit modules.conf.xml and uncomment

 <load module="mod_java"/>

Configuring mod_java

Edit java.conf.xml and fill in the path to your favourite Java 1.5 or greater virtual machine library.

The java.class.path parameter must contain freeswitch.jar and other paths are only necessary when you are not using JAR files, read on. You can create the freeswitch.jar file yourself by using jar command or any of your favorite tool. All the source files are there in <extracted-freeswitch-directory>/src/mod/languages/mod_java/src to build the required jar.

You can add any other options you like; for convenience remote debugging is enabled by default.

Building Java scripts

You need to have freeswitch.jar on your CLASSPATH when using javac.

Invoking mod_java applications

Use one of these in your dialplan:

<action application="java" data="fully.qualified.class.name arg1 arg2 arg3"/>
<action application="java" data="/path/to/file.jar fully.qualified.class.name arg1 arg2 arg3"/>

The first will look for the given class on your CLASSPATH (set in java.conf.xml), the second will look in the given JAR file.

Debugging

By default the remote debugger listens on port 8000 and IP 127.0.0.1. The org.freeswitch.Launcher class in freeswitch.jar is used to launch scripts, so you can put breakpoints on it and from there trace into your code.

Example code

import org.freeswitch.*;
import org.freeswitch.swig.*;

public class PhoneTest implements FreeswitchScript, DTMFCallback, HangupHook
{
    public PhoneTest()
    {
    }

    public String onDTMF(Object object, int i, String arg)
    {
        if (object instanceof String)
            freeswitch.console_log("notice", "DTMF: " + (String)object + " ARG: " + arg + "\n");
        else
            freeswitch.console_log("notice", "WOW GOT AN EVENT: " + object.toString());
        return "true";
    }

    public void onHangup()
    {
        freeswitch.console_log("notice", "HANGUP!\n");
    }

    public void run(String sessionUuid, String args)
    {
        freeswitch.console_log("notice", "UUID: " + sessionUuid + " ARGS: " + args + "\n");
        JavaSession session = null;
        try
            {
                session = new JavaSession(sessionUuid);
                session.setDTMFCallback(this, "TEST");
                session.setHangupHook(this);

                session.answer();
                session.streamFile(args, 0);
                session.hangup("");
            }
        finally
            {
                if (session != null)
                    session.delete();
            }
    }
}

Notes

If you want to be aware of channel hang up then your java class should implement interface org.freeswitch.HangupHook. Method

org.freeswitch.HangupHook.onHangup() is called not only when channel is being hanged up but also when it's being transferred. In this method you should shutdown you java-application
javaSession.destroy()
to release the given channel else general call processing will be blocked with your app.

FAQ

Q: Does mod_java run in a single JVM or does it spawn a JVM per call?

A: There is a single in-process JVM, and each FreeSWITCH thread is attached to it before calling into Java (using the invocation API) and detached afterwards.