1 <?xml version="1.0" encoding='utf-8'?>
3 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
4 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
6 <!-- Include general documentation entities -->
7 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
12 <!-- Module User's Guide -->
16 <title>&adminguide;</title>
18 <!-- Section Overview -->
20 <title>Overview</title>
22 This module allows execution of Java compiled classes from the &kamailio;
23 config file, exporting functions to access the SIP message from Java
24 using the Java Native Interface (JNI).
27 <!-- end op section Overview -->
29 <!-- Section Dependencies -->
31 <title>Dependencies</title>
32 <!-- Section Modules -->
34 <title>&kamailio; Modules</title>
36 The following modules must be loaded before this module:
40 <emphasis>none</emphasis>.
46 <!-- End of section Modules -->
48 <!-- Section External Libraries or Applications -->
50 <title>External Libraries or Applications</title>
53 The following libraries or applications must be installed before running
54 &kamailio; with this module loaded:
57 <para><emphasis>The following packages are runtime libraries, required to launch</emphasis></para>
58 <listitem override="disc"><para><emphasis>java-common</emphasis> Base of all Java packages.</para></listitem>
59 <listitem override="disc"><para><emphasis>default-jre</emphasis> Standard Java or Java compatible Runtime.</para></listitem>
60 <listitem override="disc"><para><emphasis>gcj-jre</emphasis> Java runtime environment using GIJ/classpath.</para></listitem>
61 <listitem override="disc"><para><emphasis>libgcj12 (>=12)</emphasis> Java runtime library for use with gcj.</para></listitem>
64 <para><emphasis>The following packages are optional, required for development</emphasis></para>
65 <listitem override="box"><para><emphasis>ant</emphasis> Java based build tool like make.</para></listitem>
66 <listitem override="box"><para><emphasis>ant-contrib</emphasis> Collection of tasks, types and other tools for Apache Ant.</para></listitem>
67 <listitem override="box"><para><emphasis>ant-gcj</emphasis> Java based build tool like make (GCJ).</para></listitem>
68 <listitem override="box"><para><emphasis>default-jdk</emphasis> Standard Java or Java compatible Development Kit</para></listitem>
69 <listitem override="box"><para><emphasis>gcj-jdk</emphasis> gcj and classpath development tools for Java(TM)</para></listitem>
70 <listitem override="box"><para><emphasis>libgcj13-dev (>=12)</emphasis> Java development headers for use with gcj</para></listitem>
71 <listitem override="box"><para><emphasis>jdk</emphasis> JDK Development Kit (either oracle jdk or openjdk)</para></listitem>
75 The following libraries or applications must be compiled before
76 running &kamailio; with this module loaded:
78 <para><emphasis>The following packages are runtime libraries, required to launch</emphasis></para>
79 <listitem override="circle"><para><emphasis><class_name></emphasis>.class</para></listitem>
80 <listitem override="circle"><para><emphasis>&kamailiobinary;</emphasis>.jar</para></listitem>
84 <!-- end of section External Libraries or Applications -->
86 <!-- end of section Dependencies -->
88 <!-- Section Java Runtime -->
90 <title>Java runtime</title>
92 <title>JRE or JDK is required to use this module</title>
93 <para>Java runtime library (JRE and JDK for building app_java) is required to use this module.</para>
96 <!-- end of section Java Runtime -->
98 <!-- Section Parameters -->
100 <title>Parameters</title>
103 <section id="app_java.p.class_name">
104 <title><varname>class_name</varname> (string)</title>
106 The class name should have the same compiled file name.
107 If the value is <emphasis>"&kamailio;"</emphasis>, then the compiled file should be named as <emphasis>"&kamailio;.class"</emphasis>.
111 Default value is <quote>&kamailio;</quote>.
115 <title>Set <varname>class_name</varname> parameter</title>
116 <programlisting format="linespecific">
118 modparam("app_java", "class_name", "&kamailio;")
124 <!-- child_init_method -->
125 <section id="app_java.p.child_init_method">
126 <title><varname>child_init_method</varname> (string)</title>
132 Default value is <quote>child_init</quote>.
136 <title>Set <varname>child_init_method</varname> parameter</title>
137 <programlisting format="linespecific">
139 modparam("app_java", "child_init_method", "my_mod_init")
145 <!-- java_options -->
146 <section id="app_java.p.java_option">
147 <title><varname>java_options</varname> (string)</title>
149 Java options for Java Virtual Machine.
150 For more info read <ulink url="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/java.html"><citetitle>java docs</citetitle></ulink>
154 Default value is <quote>-Djava.compiler=NONE</quote>.
158 <title>Set <varname>java_options</varname> parameter</title>
159 <programlisting format="linespecific">
161 modparam("app_java", "java_options", "-Djava.compiler=NONE")
166 <title>Set <varname>java_options</varname> parameter (live configuration)</title>
167 <programlisting format="linespecific">
169 # Assumes "application java folder" is located at /opt/kamailio/java
170 modparam("app_java", "java_options", "-Djava.compiler=NONE
171 -Djava.class.path=/path/to/kamailio/modules:/opt/kamailio/java:
172 /opt/kamailio/java/kamailio.jar")
177 <title>Set <varname>java_options</varname> parameter (verbose configuration)</title>
178 <programlisting format="linespecific">
180 # Assumes "application java folder" is located at /opt/kamailio/java
181 modparam("app_java", "java_options", "-verbose:gc,class,jni
182 -Djava.compiler=NONE -Djava.class.path=/path/to/kamailio/modules:
183 /opt/kamailio/java:/opt/kamailio/java/kamailio.jar")
188 <title>Set <varname>java_options</varname> parameter (debug configuration)</title>
189 <programlisting format="linespecific">
191 # Assumes "application java folder" is located at /opt/kamailio/java
192 modparam("app_java", "java_options", "-Xdebug -verbose:gc,class,jni
193 -Djava.compiler=NONE -Djava.class.path=/path/to/kamailio/modules:
194 /opt/kamailio/java:/opt/kamailio/java/kamailio.jar")
200 <!-- force_cmd_exec -->
201 <section id="app_java.p.force_cmd_exec">
202 <title><varname>force_cmd_exec</varname> (int)</title>
204 This parameter forces execution a &kamailiobinary; comnmand with java native method <quote>KamExec</quote>.
205 # Note: this is an untested yet feature, may cause (but may not) a memory leaks if used from embedded languages.
209 Default value is <quote>0 (off)</quote>.
213 <title>Set <varname>force_cmd_exec</varname> parameter</title>
214 <programlisting format="linespecific">
216 modparam("app_java", "force_cmd_exec", 1)
222 <!-- End of section Parameters -->
224 <!-- Section Functions -->
226 <title>Functions</title>
228 <!-- Section Common requirements -->
233 <para>Each function has a required parameter <quote>method_signature</quote>. For more info
234 see <ulink url="http://www.rgagnon.com/javadetails/java-0286.html"
235 ><citetitle>Determine the signature of a method</citetitle></ulink>.
236 Signature represents the variable type. The mapping between the Java type and C type
238 <programlisting format="linespecific">
250 Note that to specify an object, the "L" is followed by the
251 object's class name and ends with a semi-colon, ';' .
254 <para> app_java supports the following signatures:
255 <programlisting format="linespecific">
256 Primitives: Z,B,C,D,F,I,J,L,S,V
260 Ljava/lang/Character;
269 Each parameter passed to function will be cast according to given signature.
271 Parameters are optional, ommitting a parameter meant the passed value is NULL.
272 Parameters count should be exactly the same as signature count.
273 Note 1: Arrays representation (symbol '[') is not supported yet.
274 Note 2: You shall use a correct signature, e.g. the following examples of
275 combinations are invalid:
276 java_method_exec("ExampleMethod", "ZI", "False");
277 java_method_exec("ExampleMethod", "LI", "something", "5");
283 <!-- End of section Common Requirements -->
285 <!-- Section java_method_exec -->
286 <section id="app_java.f.java_method_exec">
287 <title>java_method_exec(method, method_signature, [param1[, param2[, ...]]])</title>
288 <para>Executes a java class method <emphasis>method</emphasis>. Parameter <emphasis>method_signature</emphasis> is required.</para>
292 <title>Signature: "V"</title>
293 <para>&kamailio; prototype</para>
294 <programlisting format="linespecific">java_method_exec("ExampleMethod", "V");</programlisting>
295 <para>Java prototype</para>
296 <programlisting format="linespecific">public int ExampleMethod();</programlisting>
297 <para>Example of usage:</para>
298 <programlisting format="linespecific">
300 java_method_exec("ExampleMethod", "V");
303 public int ExampleMethod()
314 <title>Signature: "Ljava/lang/String;I"</title>
315 <para>&kamailio; prototype</para>
316 <programlisting format="linespecific">java_method_exec("ExampleMethod", "Ljava/lang/String;I", "Hello world", "5");</programlisting>
317 <para>Java prototype</para>
318 <programlisting format="linespecific">public int ExampleMethod(String param1, int param2);</programlisting>
319 <para>In the above scenario parameter 2 ("5") will be cast to integer representation.</para>
320 <para>Example of usage:</para>
321 <programlisting format="linespecific">
323 java_method_exec("ExampleMethod", "Ljava/lang/String;I", "$mb", "$ml");
326 public int ExampleMethod(String SipMessageBuffer, int SipMessageLenght)
328 ... do something with buffer;
337 <title>Signature: "ZB"</title>
338 <para>&kamailio; prototype</para>
339 <programlisting format="linespecific">java_method_exec("ExampleMethod", "ZB", "true", "0x05");</programlisting>
340 <para>Java prototype</para>
341 <programlisting format="linespecific">public int ExampleMethod(boolean param1, byte param2);</programlisting>
342 <para>In the above scenario parameter 1 ("true") will be cast to boolean representation.</para>
343 <para>Example of usage:</para>
344 <programlisting format="linespecific">
346 java_method_exec("ExampleMethod", "ZB", "true", "0x05");
349 public int ExampleMethod(boolean flagSet, byte bFlag);
353 ... do something with flags;
364 <!-- end of section java_method_exec -->
366 <!-- Section java_staticmethod_method_exec -->
367 <section id="app_java.f.java_staticmethod_exec">
368 <title>java_staticmethod_exec(method, method_signature, [param1[, param2[, ...]]])</title>
369 <para>Executes a Java static method <emphasis>method</emphasis>. Parameter <emphasis>method_signature</emphasis> is required.</para>
373 <title>Signature: "V"</title>
374 <para>&kamailio; prototype</para>
375 <programlisting format="linespecific">java_staticmethod_exec("ExampleMethod", "V");</programlisting>
376 <para>Java prototype</para>
377 <programlisting format="linespecific">public static int ExampleMethod();</programlisting>
378 <para>Example of usage:</para>
379 <programlisting format="linespecific">
381 java_staticmethod_exec("ExampleMethod", "V");
384 public static int ExampleMethod()
395 <title>Signature: "Ljava/lang/String;I"</title>
396 <para>&kamailio; prototype</para>
397 <programlisting format="linespecific">java_staticmethod_exec("ExampleMethod", "Ljava/lang/String;I", "Hello world", "5");</programlisting>
398 <para>Java prototype</para>
399 <programlisting format="linespecific">public static int ExampleMethod(String param1, int param2);</programlisting>
400 <para>In the above scenario parameter 2 ("5") will be cast to integer representation.</para>
401 <para>Example of usage:</para>
402 <programlisting format="linespecific">
404 java_staticmethod_exec("ExampleMethod", "Ljava/lang/String;I", "$mb", "$ml");
407 public static int ExampleMethod(String SipMessageBuffer, int SipMessageLenght)
409 ... do something with buffer;
418 <title>Signature: "ZB"</title>
419 <para>&kamailio; prototype</para>
420 <programlisting format="linespecific">java_staticmethod_exec("ExampleMethod", "ZB", "true", "0x05");</programlisting>
421 <para>Java prototype</para>
422 <programlisting format="linespecific">public static int ExampleMethod(boolean param1, byte param2);</programlisting>
423 <para>In the above scenario parameter 1 ("true") will be cast to boolean representation.</para>
424 <para>Example of usage:</para>
425 <programlisting format="linespecific">
427 java_staticmethod_exec("ExampleMethod", "ZB", "true", "0x05");
430 public static int ExampleMethod(boolean flagSet, byte bFlag);
434 ... do something with flags;
445 <!-- end of section java_staticmethod_exec -->
447 <!-- Section java_s_method_exec -->
448 <section id="app_java.f.java_s_method_exec">
449 <title>java_s_method_exec(method, method_signature, [param1[, param2[, ...]]])</title>
450 <para>Executes a Java class synchronized method <emphasis>method</emphasis>. Parameter <emphasis>method_signature</emphasis> is required.</para>
451 <para>For more info see <ulink url="http://docs.oracle.com/javase/tutorial/essential/concurrency/syncmeth.html"><citetitle>Synchronized Methods</citetitle></ulink></para>
455 <title>Signature: "V"</title>
456 <para>&kamailio; prototype</para>
457 <programlisting format="linespecific">java_s_method_exec("ExampleMethod", "V");</programlisting>
458 <para>Java prototype</para>
459 <programlisting format="linespecific">public synchronized int ExampleMethod();</programlisting>
460 <para>Example of usage:</para>
461 <programlisting format="linespecific">
463 java_s_method_exec("ExampleMethod", "V");
466 public synchronized int ExampleMethod()
477 <title>Signature: "Ljava/lang/String;I"</title>
478 <para>&kamailio; prototype</para>
479 <programlisting format="linespecific">java_s_method_exec("ExampleMethod", "Ljava/lang/String;I", "Hello world", "5");</programlisting>
480 <para>Java prototype</para>
481 <programlisting format="linespecific">public synchronized int ExampleMethod(String param1, int param2);</programlisting>
482 <para>In the above scenario parameter 2 ("5") will be cast to integer representation.</para>
483 <para>Example of usage:</para>
484 <programlisting format="linespecific">
486 java_s_method_exec("ExampleMethod", "Ljava/lang/String;I", "$mb", "$ml");
489 public synchronized int ExampleMethod(String SipMessageBuffer, int SipMessageLenght)
491 ... do something with buffer;
500 <title>Signature: "ZB"</title>
501 <para>&kamailio; prototype</para>
502 <programlisting format="linespecific">java_s_method_exec("ExampleMethod", "ZB", "true", "0x05");</programlisting>
503 <para>Java prototype</para>
504 <programlisting format="linespecific">public synchronized int ExampleMethod(boolean param1, byte param2);</programlisting>
505 <para>In the above scenario parameter 1 ("true") will be cast to boolean representation.</para>
506 <para>Example of usage:</para>
507 <programlisting format="linespecific">
509 java_s_method_exec("ExampleMethod", "ZB", "true", "0x05");
512 public synchronized int ExampleMethod(boolean flagSet, byte bFlag);
516 ... do something with flags;
527 <!-- end of section java_s_method_exec -->
529 <!-- Section java_s_staticmethod_exec -->
530 <section id="app_java.f.java_s_staticmethod_exec">
531 <title>java_s_staticmethod_exec(method, method_signature, [param1[, param2[, ...]]])</title>
532 <para>Executes a java synchronized static method <emphasis>method</emphasis>. Parameter <emphasis>method_signature</emphasis> is required.</para>
533 <para>For more info see <ulink url="http://docs.oracle.com/javase/tutorial/essential/concurrency/syncmeth.html"><citetitle>Synchronized Methods</citetitle></ulink></para>
537 <title>Signature: "V"</title>
538 <para>&kamailio; prototype</para>
539 <programlisting format="linespecific">java_s_staticmethod_exec("ExampleMethod", "V");</programlisting>
540 <para>Java prototype</para>
541 <programlisting format="linespecific">public static synchronized int ExampleMethod();</programlisting>
542 <para>Example of usage:</para>
543 <programlisting format="linespecific">
545 java_s_staticmethod_exec("ExampleMethod", "V");
548 public static synchronized int ExampleMethod()
559 <title>Signature: "Ljava/lang/String;I"</title>
560 <para>&kamailio; prototype</para>
561 <programlisting format="linespecific">java_s_staticmethod_exec("ExampleMethod", "Ljava/lang/String;I", "Hello world", "5");</programlisting>
562 <para>Java prototype</para>
563 <programlisting format="linespecific">public static synchronized int ExampleMethod(String param1, int param2);</programlisting>
564 <para>In the above scenario parameter 2 ("5") will be cast to integer representation.</para>
565 <para>Example of usage:</para>
566 <programlisting format="linespecific">
568 java_s_staticmethod_exec("ExampleMethod", "Ljava/lang/String;I", "$mb", "$ml");
571 public static synchronized int ExampleMethod(String SipMessageBuffer, int SipMessageLenght)
573 ... do something with buffer;
582 <title>Signature: "ZB"</title>
583 <para>&kamailio; prototype</para>
584 <programlisting format="linespecific">java_s_staticmethod_exec("ExampleMethod", "ZB", "true", "0x05");</programlisting>
585 <para>Java prototype</para>
586 <programlisting format="linespecific">public static synchronized int ExampleMethod(boolean param1, byte param2);</programlisting>
587 <para>In the above scenario parameter 1 ("true") will be cast to boolean representation.</para>
588 <para>Example of usage:</para>
589 <programlisting format="linespecific">
591 java_s_staticmethod_exec("ExampleMethod", "ZB", "true", "0x05");
594 public static synchronized int ExampleMethod(boolean flagSet, byte bFlag);
598 ... do something with flags;
609 <!-- end of section java_s_method_exec -->
612 <!-- End of section Functions -->
614 <!-- Section Java API-->
616 <title>Java Module API</title>
619 <!-- Section Minimal program skeleton -->
621 <title>Minimal program skeleton</title>
624 <title>Minimal program skeleton</title>
626 <programlisting format="linespecific">
627 import org.siprouter.*;
628 import org.siprouter.NativeInterface.*;
630 public class Kamailio extends NativeMethods
632 /* Here you should specify a full path to app_java.so */
635 System.load("/opt/kamailio/lib/kamailio/modules/app_java.so");
638 /* Constructor. Do not remove !!! */
644 This method should be executed for each children process, immediately after forking.
645 Required. Do not remove !!!
647 public int child_init(int rank)
655 <!-- End of section Minimal program skeleton -->
658 <!-- End of section Java API -->