change log updated
[public/netxms.git] / include / nxjava.h
1 /*
2 ** NetXMS - Network Management System
3 ** Copyright (C) 2003-2017 Victor Kirhenshtein
4 **
5 ** This program is free software; you can redistribute it and/or modify
6 ** it under the terms of the GNU Lesser General Public License as published by
7 ** the Free Software Foundation; either version 3 of the License, or
8 ** (at your option) any later version.
9 **
10 ** This program is distributed in the hope that it will be useful,
11 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
12 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 ** GNU General Public License for more details.
14 **
15 ** You should have received a copy of the GNU Lesser General Public License
16 ** along with this program; if not, write to the Free Software
17 ** Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 **
19 ** File: nxjava.h
20 **
21 **/
22
23 #ifndef _nxjava_h_
24 #define _nxjava_h_
25
26 #ifdef _WIN32
27 #ifdef LIBNXJAVA_EXPORTS
28 #define LIBNXJAVA_EXPORTABLE __declspec(dllexport)
29 #else
30 #define LIBNXJAVA_EXPORTABLE __declspec(dllimport)
31 #endif
32 #else /* _WIN32 */
33 #define LIBNXJAVA_EXPORTABLE
34 #endif
35
36 #include <nms_common.h>
37 #include <nms_util.h>
38 #include <nxconfig.h>
39 #include <jni.h>
40 #include <unicode.h>
41
42 /**
43 * Error codes
44 */
45 enum JavaBridgeError
46 {
47 NXJAVA_SUCCESS = 0,
48 NXJAVA_JVM_LOAD_FAILED = 1,
49 NXJAVA_NO_ENTRY_POINT = 2,
50 NXJAVA_CANNOT_CREATE_JVM = 3,
51 NXJAVA_APP_CLASS_NOT_FOUND = 4,
52 NXJAVA_APP_ENTRY_POINT_NOT_FOUND = 5
53 };
54
55 /**
56 * Get error message from error code
57 */
58 const TCHAR LIBNXJAVA_EXPORTABLE *GetJavaBridgeErrorMessage(JavaBridgeError error);
59
60 /**
61 * Convert Java string to C string.
62 * Result string is dynamically allocated and must be disposed by calling free().
63 */
64 TCHAR LIBNXJAVA_EXPORTABLE *CStringFromJavaString(JNIEnv *env, jstring jstr);
65
66 /**
67 * Convert Java string to C string.
68 * Result string is in static buffer
69 */
70 TCHAR LIBNXJAVA_EXPORTABLE *CStringFromJavaString(JNIEnv *env, jstring jstr, TCHAR *buffer, size_t bufferLen);
71
72 /**
73 * Convert wide character C string to Java string.
74 */
75 jstring LIBNXJAVA_EXPORTABLE JavaStringFromCStringW(JNIEnv *env, const WCHAR *str);
76
77 /**
78 * Convert C string in current code page to Java string.
79 */
80 jstring LIBNXJAVA_EXPORTABLE JavaStringFromCStringA(JNIEnv *env, const char *str);
81
82 /**
83 * Convert C string to Java string.
84 */
85 #ifdef UNICODE
86 #define JavaStringFromCString JavaStringFromCStringW
87 #else
88 #define JavaStringFromCString JavaStringFromCStringA
89 #endif
90
91 /**
92 * Convert C string in system locale code page to Java string.
93 */
94 jstring LIBNXJAVA_EXPORTABLE JavaStringFromCStringSysLocale(JNIEnv *env, const char *str);
95
96 /**
97 * Create StringList from Java string array
98 */
99 StringList LIBNXJAVA_EXPORTABLE *StringListFromJavaArray(JNIEnv *curEnv, jobjectArray a);
100
101 /**
102 * Find Java runtime module. Search algorithm is following:
103 * 1. Windows only - check for bundled JRE in bin\jre
104 * 2. Check for bundled JRE in $NETXMS_HOME/bin/jre (Windows) or $NETXMS_HOME/lib/jre (non-Windows)
105 * 3. Windows only - check JRE location in registry
106 * 3. Check $JAVA_HOME
107 * 4. Check $JAVA_HOME/jre
108 * 5. Check JDK location specified at compile time
109 *
110 * @param buffer buffer for result
111 * @param size buffer size in characters
112 * @return buffer on success or NULL on failure
113 */
114 TCHAR LIBNXJAVA_EXPORTABLE *FindJavaRuntime(TCHAR *buffer, size_t size);
115
116 /**
117 * Create Java virtual machine
118 *
119 * @param jvmPath path to JVM library
120 * @param jar application JAR - path should be relative to NetXMS library directory (can be NULL)
121 * @param syslibs list of system jar files (should be terminated with NULL pointer, can be NULL)
122 * @param usercp user defined class path (can be NULL)
123 * @param vmOptions additional VM options
124 * @param env points where JNI environment for current thread will be stored
125 * @return NXJAVA_SUCCESS if VM created successfully or appropriate error code
126 */
127 JavaBridgeError LIBNXJAVA_EXPORTABLE CreateJavaVM(const TCHAR *jvmPath, const TCHAR *jar, const TCHAR **syslibs, const TCHAR *usercp, StringList *vmOptions, JNIEnv **env);
128
129 /**
130 * Destroy Java virtual machine
131 */
132 void LIBNXJAVA_EXPORTABLE DestroyJavaVM();
133
134 /**
135 * Attach current thread to Java VM
136 *
137 * @return JNI environment for current thread or NULL on failure
138 */
139 JNIEnv LIBNXJAVA_EXPORTABLE *AttachThreadToJavaVM();
140
141 /**
142 * Detach current thread from Java VM
143 */
144 void LIBNXJAVA_EXPORTABLE DetachThreadFromJavaVM();
145
146 /**
147 * Start Java application. This is helper method for starting Java applications
148 * from command line wrapper. Application class should contain entry point with
149 * the following signature:
150 *
151 * public static void main(String[])
152 *
153 * @param env JNI environment for current thread
154 * @param appClass application class name
155 * @param argc number of command line arguments
156 * @param argv pointers to arguments in (expected to be encoded using system locale code page)
157 * @return NXJAVA_SUCCESS on success or appropriate error code
158 */
159 JavaBridgeError LIBNXJAVA_EXPORTABLE StartJavaApplication(JNIEnv *env, const char *appClass, int argc, char **argv);
160
161 /**
162 * Create global reference to Java class
163 *
164 * @param env JNI environment for current thread
165 * @param className Java class name
166 * @return Java class object
167 */
168 jclass LIBNXJAVA_EXPORTABLE CreateJavaClassGlobalRef(JNIEnv *env, const char *className);
169
170 /**
171 * Create Java Config object (wrapper around C++ Config class)
172 *
173 * @param env JNI environment for current thread
174 * @param config C++ Config object
175 * @return Java wrapper object or NULL on failure
176 */
177 jobject LIBNXJAVA_EXPORTABLE CreateConfigJavaInstance(JNIEnv *env, Config *config);
178
179 #endif /* _nxjava_h_ */