core, lib, modules: restructured source code tree
[sip-router] / src / modules / app_java / README
1 app_java Module
2
3 Konstantin Mosesov
4
5 Edited by
6
7 Konstantin Mosesov
8
9    Copyright © 2013, 2014 Konstantin Mosesov
10      __________________________________________________________________
11
12    Table of Contents
13
14    1. Admin Guide
15
16         1. Overview
17         2. Dependencies
18
19               2.1. Kamailio Modules
20               2.2. External Libraries or Applications
21
22         3. Java runtime
23
24               3.1. JRE or JDK is required to use this module
25
26         4. Parameters
27
28               4.1. class_name (string)
29               4.2. child_init_method (string)
30               4.3. java_options (string)
31               4.4. force_cmd_exec (int)
32
33         5. Functions
34
35               5.1. Common requirements
36               5.2. java_method_exec(method, method_signature, [param1[,
37                       param2[, ...]]])
38
39               5.3. java_staticmethod_exec(method, method_signature,
40                       [param1[, param2[, ...]]])
41
42               5.4. java_s_method_exec(method, method_signature, [param1[,
43                       param2[, ...]]])
44
45               5.5. java_s_staticmethod_exec(method, method_signature,
46                       [param1[, param2[, ...]]])
47
48         6. Java Module API
49
50               6.1. Minimal program skeleton
51
52    List of Examples
53
54    1.1. Set class_name parameter
55    1.2. Set child_init_method parameter
56    1.3. Set java_options parameter
57    1.4. Set java_options parameter (live configuration)
58    1.5. Set java_options parameter (verbose configuration)
59    1.6. Set java_options parameter (debug configuration)
60    1.7. Set force_cmd_exec parameter
61    1.8. Signature: "V"
62    1.9. Signature: "Ljava/lang/String;I"
63    1.10. Signature: "ZB"
64    1.11. Signature: "V"
65    1.12. Signature: "Ljava/lang/String;I"
66    1.13. Signature: "ZB"
67    1.14. Signature: "V"
68    1.15. Signature: "Ljava/lang/String;I"
69    1.16. Signature: "ZB"
70    1.17. Signature: "V"
71    1.18. Signature: "Ljava/lang/String;I"
72    1.19. Signature: "ZB"
73    1.20. Minimal program skeleton
74
75 Chapter 1. Admin Guide
76
77    Table of Contents
78
79    1. Overview
80    2. Dependencies
81
82         2.1. Kamailio Modules
83         2.2. External Libraries or Applications
84
85    3. Java runtime
86
87         3.1. JRE or JDK is required to use this module
88
89    4. Parameters
90
91         4.1. class_name (string)
92         4.2. child_init_method (string)
93         4.3. java_options (string)
94         4.4. force_cmd_exec (int)
95
96    5. Functions
97
98         5.1. Common requirements
99         5.2. java_method_exec(method, method_signature, [param1[, param2[,
100                 ...]]])
101
102         5.3. java_staticmethod_exec(method, method_signature, [param1[,
103                 param2[, ...]]])
104
105         5.4. java_s_method_exec(method, method_signature, [param1[,
106                 param2[, ...]]])
107
108         5.5. java_s_staticmethod_exec(method, method_signature, [param1[,
109                 param2[, ...]]])
110
111    6. Java Module API
112
113         6.1. Minimal program skeleton
114
115 1. Overview
116
117    This module allows execution of Java compiled classes from the Kamailio
118    config file, exporting functions to access the SIP message from Java
119    using the Java Native Interface (JNI).
120
121 2. Dependencies
122
123    2.1. Kamailio Modules
124    2.2. External Libraries or Applications
125
126 2.1. Kamailio Modules
127
128    The following modules must be loaded before this module:
129      * none.
130
131 2.2. External Libraries or Applications
132
133    The following packages are runtime libraries, required to launch
134      * java-common Base of all Java packages.
135      * default-jre Standard Java or Java compatible Runtime.
136      * gcj-jre Java runtime environment using GIJ/classpath.
137      * libgcj12 (>=12) Java runtime library for use with gcj.
138
139    The following packages are optional, required for development
140      * ant Java based build tool like make.
141      * ant-contrib Collection of tasks, types and other tools for Apache
142        Ant.
143      * ant-gcj Java based build tool like make (GCJ).
144      * default-jdk Standard Java or Java compatible Development Kit
145      * gcj-jdk gcj and classpath development tools for Java(TM)
146      * libgcj13-dev (>=12) Java development headers for use with gcj
147      * jdk JDK Development Kit (either oracle jdk or openjdk)
148
149    The following libraries or applications must be compiled before running
150    Kamailio with this module loaded:
151
152    The following packages are runtime libraries, required to launch
153      * <class_name>.class
154      * kamailio.jar
155
156 3. Java runtime
157
158    3.1. JRE or JDK is required to use this module
159
160 3.1. JRE or JDK is required to use this module
161
162    Java runtime library (JRE and JDK for building app_java) is required to
163    use this module.
164
165 4. Parameters
166
167    4.1. class_name (string)
168    4.2. child_init_method (string)
169    4.3. java_options (string)
170    4.4. force_cmd_exec (int)
171
172 4.1. class_name (string)
173
174    The class name should have the same compiled file name. If the value is
175    "Kamailio", then the compiled file should be named as "Kamailio.class".
176
177    Default value is “Kamailio”.
178
179    Example 1.1. Set class_name parameter
180 ...
181 modparam("app_java", "class_name", "Kamailio")
182 ...
183
184 4.2. child_init_method (string)
185
186    TBD.
187
188    Default value is “child_init”.
189
190    Example 1.2. Set child_init_method parameter
191 ...
192 modparam("app_java", "child_init_method", "my_mod_init")
193 ...
194
195 4.3. java_options (string)
196
197    Java options for Java Virtual Machine. For more info read java docs
198
199    Default value is “-Djava.compiler=NONE”.
200
201    Example 1.3. Set java_options parameter
202 ...
203 modparam("app_java", "java_options", "-Djava.compiler=NONE")
204 ...
205
206    Example 1.4. Set java_options parameter (live configuration)
207 ...
208 # Assumes "application java folder" is located at /opt/kamailio/java
209 modparam("app_java", "java_options", "-Djava.compiler=NONE
210     -Djava.class.path=/path/to/kamailio/modules:/opt/kamailio/java:
211     /opt/kamailio/java/kamailio.jar")
212 ...
213
214    Example 1.5. Set java_options parameter (verbose configuration)
215 ...
216 # Assumes "application java folder" is located at /opt/kamailio/java
217 modparam("app_java", "java_options", "-verbose:gc,class,jni
218     -Djava.compiler=NONE -Djava.class.path=/path/to/kamailio/modules:
219     /opt/kamailio/java:/opt/kamailio/java/kamailio.jar")
220 ...
221
222    Example 1.6. Set java_options parameter (debug configuration)
223 ...
224 # Assumes "application java folder" is located at /opt/kamailio/java
225 modparam("app_java", "java_options", "-Xdebug -verbose:gc,class,jni
226     -Djava.compiler=NONE -Djava.class.path=/path/to/kamailio/modules:
227     /opt/kamailio/java:/opt/kamailio/java/kamailio.jar")
228 ...
229
230 4.4. force_cmd_exec (int)
231
232    This parameter forces execution a kamailio comnmand with java native
233    method “KamExec”. # Note: this is an untested yet feature, may cause
234    (but may not) a memory leaks if used from embedded languages.
235
236    Default value is “0 (off)”.
237
238    Example 1.7. Set force_cmd_exec parameter
239 ...
240 modparam("app_java", "force_cmd_exec", 1)
241 ...
242
243 5. Functions
244
245    5.1. Common requirements
246    5.2. java_method_exec(method, method_signature, [param1[, param2[,
247           ...]]])
248
249    5.3. java_staticmethod_exec(method, method_signature, [param1[,
250           param2[, ...]]])
251
252    5.4. java_s_method_exec(method, method_signature, [param1[, param2[,
253           ...]]])
254
255    5.5. java_s_staticmethod_exec(method, method_signature, [param1[,
256           param2[, ...]]])
257
258 5.1.  Common requirements
259
260    Each function has a required parameter “method_signature”. For more
261    info see Determine the signature of a method. Signature represents the
262    variable type. The mapping between the Java type and C type is
263                 Type     Chararacter
264                 boolean      Z
265                 byte         B
266                 char         C
267                 double       D
268                 float        F
269                 int          I
270                 long         J
271                 object       L
272                 short        S
273                 void         V
274                 Note that to specify an object, the "L" is followed by the
275                 object's class name and ends with a semi-colon, ';' .
276
277    app_java supports the following signatures:
278                 Primitives: Z,B,C,D,F,I,J,L,S,V
279                 Objects:
280                         Ljava/lang/Boolean;
281                         Ljava/lang/Byte;
282                         Ljava/lang/Character;
283                         Ljava/lang/Double;
284                         Ljava/lang/Float;
285                         Ljava/lang/Integer;
286                         Ljava/lang/Long;
287                         Ljava/lang/Short;
288                         Ljava/lang/String;
289                         NULL parameter: V
290
291         Each parameter passed to function will be cast according to given signat
292 ure.
293
294         Parameters are optional, ommitting a parameter meant the passed value is
295  NULL.
296         Parameters count should be exactly the same as signature count.
297         Note 1: Arrays representation (symbol '[') is not supported yet.
298         Note 2: You shall use a correct signature, e.g. the following examples o
299 f
300         combinations are invalid:
301         java_method_exec("ExampleMethod", "ZI", "False");
302         java_method_exec("ExampleMethod", "LI", "something", "5");
303
304 5.2. java_method_exec(method, method_signature, [param1[, param2[, ...]]])
305
306    Executes a java class method method. Parameter method_signature is
307    required.
308      * Example 1.8. Signature: "V"
309        Kamailio prototype
310 java_method_exec("ExampleMethod", "V");
311        Java prototype
312 public int ExampleMethod();
313        Example of usage:
314 # Kamailio
315 java_method_exec("ExampleMethod", "V");
316
317 # Java
318 public int ExampleMethod()
319 {
320     ... do something;
321     return 1;
322 }
323      * Example 1.9. Signature: "Ljava/lang/String;I"
324        Kamailio prototype
325 java_method_exec("ExampleMethod", "Ljava/lang/String;I", "Hello world", "5");
326        Java prototype
327 public int ExampleMethod(String param1, int param2);
328        In the above scenario parameter 2 ("5") will be cast to integer
329        representation.
330        Example of usage:
331 # Kamailio
332 java_method_exec("ExampleMethod", "Ljava/lang/String;I", "$mb", "$ml");
333
334 # Java
335 public int ExampleMethod(String SipMessageBuffer, int SipMessageLenght)
336 {
337     ... do something with buffer;
338     return 1;
339 }
340      * Example 1.10. Signature: "ZB"
341        Kamailio prototype
342 java_method_exec("ExampleMethod", "ZB", "true", "0x05");
343        Java prototype
344 public int ExampleMethod(boolean param1, byte param2);
345        In the above scenario parameter 1 ("true") will be cast to boolean
346        representation.
347        Example of usage:
348 # Kamailio
349 java_method_exec("ExampleMethod", "ZB", "true", "0x05");
350
351 # Java
352 public int ExampleMethod(boolean flagSet, byte bFlag);
353 {
354     if (flagSet)
355     {
356         ... do something with flags;
357     }
358
359     return 1;
360 }
361
362 5.3. java_staticmethod_exec(method, method_signature, [param1[, param2[,
363 ...]]])
364
365    Executes a Java static method method. Parameter method_signature is
366    required.
367      * Example 1.11. Signature: "V"
368        Kamailio prototype
369 java_staticmethod_exec("ExampleMethod", "V");
370        Java prototype
371 public static int ExampleMethod();
372        Example of usage:
373 # Kamailio
374 java_staticmethod_exec("ExampleMethod", "V");
375
376 # Java
377 public static int ExampleMethod()
378 {
379     ... do something;
380     return 1;
381 }
382      * Example 1.12. Signature: "Ljava/lang/String;I"
383        Kamailio prototype
384 java_staticmethod_exec("ExampleMethod", "Ljava/lang/String;I", "Hello world", "5
385 ");
386        Java prototype
387 public static int ExampleMethod(String param1, int param2);
388        In the above scenario parameter 2 ("5") will be cast to integer
389        representation.
390        Example of usage:
391 # Kamailio
392 java_staticmethod_exec("ExampleMethod", "Ljava/lang/String;I", "$mb", "$ml");
393
394 # Java
395 public static int ExampleMethod(String SipMessageBuffer, int SipMessageLenght)
396 {
397     ... do something with buffer;
398     return 1;
399 }
400      * Example 1.13. Signature: "ZB"
401        Kamailio prototype
402 java_staticmethod_exec("ExampleMethod", "ZB", "true", "0x05");
403        Java prototype
404 public static int ExampleMethod(boolean param1, byte param2);
405        In the above scenario parameter 1 ("true") will be cast to boolean
406        representation.
407        Example of usage:
408 # Kamailio
409 java_staticmethod_exec("ExampleMethod", "ZB", "true", "0x05");
410
411 # Java
412 public static int ExampleMethod(boolean flagSet, byte bFlag);
413 {
414     if (flagSet)
415     {
416         ... do something with flags;
417     }
418
419     return 1;
420 }
421
422 5.4. java_s_method_exec(method, method_signature, [param1[, param2[, ...]]])
423
424    Executes a Java class synchronized method method. Parameter
425    method_signature is required.
426
427    For more info see Synchronized Methods
428      * Example 1.14. Signature: "V"
429        Kamailio prototype
430 java_s_method_exec("ExampleMethod", "V");
431        Java prototype
432 public synchronized int ExampleMethod();
433        Example of usage:
434 # Kamailio
435 java_s_method_exec("ExampleMethod", "V");
436
437 # Java
438 public synchronized int ExampleMethod()
439 {
440     ... do something;
441     return 1;
442 }
443      * Example 1.15. Signature: "Ljava/lang/String;I"
444        Kamailio prototype
445 java_s_method_exec("ExampleMethod", "Ljava/lang/String;I", "Hello world", "5");
446        Java prototype
447 public synchronized int ExampleMethod(String param1, int param2);
448        In the above scenario parameter 2 ("5") will be cast to integer
449        representation.
450        Example of usage:
451 # Kamailio
452 java_s_method_exec("ExampleMethod", "Ljava/lang/String;I", "$mb", "$ml");
453
454 # Java
455 public synchronized int ExampleMethod(String SipMessageBuffer, int SipMessageLen
456 ght)
457 {
458     ... do something with buffer;
459     return 1;
460 }
461      * Example 1.16. Signature: "ZB"
462        Kamailio prototype
463 java_s_method_exec("ExampleMethod", "ZB", "true", "0x05");
464        Java prototype
465 public synchronized int ExampleMethod(boolean param1, byte param2);
466        In the above scenario parameter 1 ("true") will be cast to boolean
467        representation.
468        Example of usage:
469 # Kamailio
470 java_s_method_exec("ExampleMethod", "ZB", "true", "0x05");
471
472 # Java
473 public synchronized int ExampleMethod(boolean flagSet, byte bFlag);
474 {
475     if (flagSet)
476     {
477         ... do something with flags;
478     }
479
480     return 1;
481 }
482
483 5.5. java_s_staticmethod_exec(method, method_signature, [param1[, param2[,
484 ...]]])
485
486    Executes a java synchronized static method method. Parameter
487    method_signature is required.
488
489    For more info see Synchronized Methods
490      * Example 1.17. Signature: "V"
491        Kamailio prototype
492 java_s_staticmethod_exec("ExampleMethod", "V");
493        Java prototype
494 public static synchronized int ExampleMethod();
495        Example of usage:
496 # Kamailio
497 java_s_staticmethod_exec("ExampleMethod", "V");
498
499 # Java
500 public static synchronized int ExampleMethod()
501 {
502     ... do something;
503     return 1;
504 }
505      * Example 1.18. Signature: "Ljava/lang/String;I"
506        Kamailio prototype
507 java_s_staticmethod_exec("ExampleMethod", "Ljava/lang/String;I", "Hello world",
508 "5");
509        Java prototype
510 public static synchronized int ExampleMethod(String param1, int param2);
511        In the above scenario parameter 2 ("5") will be cast to integer
512        representation.
513        Example of usage:
514 # Kamailio
515 java_s_staticmethod_exec("ExampleMethod", "Ljava/lang/String;I", "$mb", "$ml");
516
517 # Java
518 public static synchronized int ExampleMethod(String SipMessageBuffer, int SipMes
519 sageLenght)
520 {
521     ... do something with buffer;
522     return 1;
523 }
524      * Example 1.19. Signature: "ZB"
525        Kamailio prototype
526 java_s_staticmethod_exec("ExampleMethod", "ZB", "true", "0x05");
527        Java prototype
528 public static synchronized int ExampleMethod(boolean param1, byte param2);
529        In the above scenario parameter 1 ("true") will be cast to boolean
530        representation.
531        Example of usage:
532 # Kamailio
533 java_s_staticmethod_exec("ExampleMethod", "ZB", "true", "0x05");
534
535 # Java
536 public static synchronized int ExampleMethod(boolean flagSet, byte bFlag);
537 {
538     if (flagSet)
539     {
540         ... do something with flags;
541     }
542
543     return 1;
544 }
545
546 6. Java Module API
547
548    6.1. Minimal program skeleton
549
550 6.1. Minimal program skeleton
551
552    Example 1.20. Minimal program skeleton
553
554 import org.siprouter.*;
555 import org.siprouter.NativeInterface.*;
556
557 public class Kamailio extends NativeMethods
558 {
559     /* Here you should specify a full path to app_java.so */
560     static
561     {
562         System.load("/opt/kamailio/lib/kamailio/modules/app_java.so");
563     }
564
565     /* Constructor. Do not remove !!! */
566     public Kamailio()
567     {
568     }
569
570     /*
571         This method should be executed for each children process, immediately af
572 ter forking.
573         Required. Do not remove !!!
574     */
575     public int child_init(int rank)
576     {
577         return 1;
578     }
579 }