| /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- |
| * |
| * ***** BEGIN LICENSE BLOCK ***** |
| * Version: MPL 1.1/GPL 2.0/LGPL 2.1 |
| * |
| * The contents of this file are subject to the Mozilla Public License Version |
| * 1.1 (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * http://www.mozilla.org/MPL/ |
| * |
| * Software distributed under the License is distributed on an "AS IS" basis, |
| * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License |
| * for the specific language governing rights and limitations under the |
| * License. |
| * |
| * The Original Code is Mozilla Communicator client code, released |
| * March 31, 1998. |
| * |
| * The Initial Developer of the Original Code is |
| * Netscape Communications Corporation. |
| * Portions created by the Initial Developer are Copyright (C) 1998 |
| * the Initial Developer. All Rights Reserved. |
| * |
| * Contributor(s): |
| * |
| * Alternatively, the contents of this file may be used under the terms of |
| * either of the GNU General Public License Version 2 or later (the "GPL"), |
| * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), |
| * in which case the provisions of the GPL or the LGPL are applicable instead |
| * of those above. If you wish to allow use of your version of this file only |
| * under the terms of either the GPL or the LGPL, and not to allow others to |
| * use your version of this file under the terms of the MPL, indicate your |
| * decision by deleting the provisions above and replace them with the notice |
| * and other provisions required by the GPL or the LGPL. If you do not delete |
| * the provisions above, a recipient may use your version of this file under |
| * the terms of any one of the MPL, the GPL or the LGPL. |
| * |
| * ***** END LICENSE BLOCK ***** */ |
| |
| /* |
| * This file is part of the Java-vendor-neutral implementation of LiveConnect |
| * |
| * Publicly exported functions for JavaScript <==> Java communication. |
| * |
| */ |
| |
| #ifndef _JSJAVA_H |
| #define _JSJAVA_H |
| |
| #ifndef jstypes_h___ |
| #include "jstypes.h" |
| #endif |
| |
| JS_BEGIN_EXTERN_C |
| |
| #include "jni.h" /* Java Native Interface */ |
| #include "jsapi.h" /* JavaScript engine API */ |
| |
| #if JS_BYTES_PER_LONG == 8 || JS_BYTES_PER_WORD == 8 |
| typedef jlong lcjsobject; |
| #else |
| typedef jint lcjsobject; |
| #endif |
| |
| /* |
| * A JSJavaVM structure is a wrapper around a JavaVM which incorporates |
| * additional LiveConnect state. |
| */ |
| typedef struct JSJavaVM JSJavaVM; |
| |
| /* LiveConnect and Java state, one per thread */ |
| typedef struct JSJavaThreadState JSJavaThreadState; |
| |
| /* |
| * An opaque type that represents the connection to the Java VM. In stand-alone |
| * Java environments, this may be a JNI JavaVM object; in the browser environment |
| * it is a reference to a JVM plugin. A set of callbacks in the JSJCallbacks |
| * struct allow it to be manipulated. |
| */ |
| #ifdef OJI |
| typedef struct SystemJavaVM SystemJavaVM; |
| #else |
| typedef JavaVM SystemJavaVM; |
| #endif |
| |
| /* |
| * This callback table provides hooks to external functions that implement |
| * functionality specific to the embedding. For example, these callbacks are |
| * necessary in multi-threaded environments or to implement a security |
| * policy. |
| * |
| * Note: The error message returned by errp has to be created by JS_smprintf. |
| * See bug: https://bugzilla.mozilla.org/show_bug.cgi?id=261468. |
| */ |
| typedef struct JSJCallbacks { |
| |
| /* This callback is invoked when there is no JavaScript execution |
| environment (JSContext) associated with the current Java thread and |
| a call is made from Java into JavaScript. (A JSContext is associated |
| with a Java thread by calling the JSJ_SetDefaultJSContextForJavaThread() |
| function.) This callback is only invoked when Java spontaneously calls |
| into JavaScript, i.e. it is not called when JS calls into Java which |
| calls back into JS. |
| |
| This callback can be used to create a JSContext lazily, or obtain |
| one from a pool of available JSContexts. The implementation of this |
| callback can call JSJ_SetDefaultJSContextForJavaThread() to avoid any |
| further callbacks of this type for this Java thread. */ |
| JSContext * (*map_jsj_thread_to_js_context)(JSJavaThreadState *jsj_env, |
| #ifdef OJI |
| void *java_applet_obj, |
| #endif |
| JNIEnv *jEnv, |
| char **errp); |
| |
| /* This callback is invoked whenever a call is made into Java from |
| JavaScript. It's responsible for mapping from a JavaScript execution |
| environment (JSContext) to a Java thread. (A JavaContext can only |
| be associated with one Java thread at a time.) */ |
| JSJavaThreadState * (*map_js_context_to_jsj_thread)(JSContext *cx, |
| char **errp); |
| |
| /* This callback implements netscape.javascript.JSObject.getWindow(), |
| a method named for its behavior in the browser environment, where it |
| returns the JS "Window" object corresponding to the HTML window that an |
| applet is embedded within. More generally, it's a way for Java to get |
| hold of a JS object that has not been explicitly passed to it. */ |
| JSObject * (*map_java_object_to_js_object)(JNIEnv *jEnv, void *pJavaObject, |
| char **errp); |
| |
| /* An interim callback function until the LiveConnect security story is |
| straightened out. This function pointer can be set to NULL. */ |
| JSPrincipals * (*get_JSPrincipals_from_java_caller)(JNIEnv *jEnv, JSContext *pJSContext, void **pNSIPrincipaArray, int numPrincipals, void *pNSISecurityContext); |
| |
| /* The following two callbacks sandwich any JS evaluation performed |
| from Java. They may be used to implement concurrency constraints, e.g. |
| by suspending the current thread until some condition is met. In the |
| browser embedding, these are used to maintain the run-to-completion |
| semantics of JavaScript. It is acceptable for either function pointer |
| to be NULL. */ |
| #ifdef OJI |
| JSBool (*enter_js_from_java)(JNIEnv *jEnv, char **errp, void **pNSIPrincipaArray, int numPrincipals, void *pNSISecurityContext,void* applet_obj); |
| #else |
| JSBool (*enter_js_from_java)(JNIEnv *jEnv, char **errp); |
| #endif |
| void (*exit_js)(JNIEnv *jEnv, JSContext *cx); |
| |
| /* Most LiveConnect errors are signaled by calling JS_ReportError(), but in |
| some circumstances, the target JSContext for such errors is not |
| determinable, e.g. during initialization. In such cases any error |
| messages are routed to this function. If the function pointer is set to |
| NULL, error messages are sent to stderr. */ |
| void (*error_print)(const char *error_msg); |
| |
| /* This enables liveconnect to ask the VM for a java wrapper so that VM gets a chance to |
| store a mapping between a jsobject and java wrapper. So the unwrapping can be done on the |
| VM side before calling nsILiveconnect apis. This saves on a round trip request. */ |
| jobject (*get_java_wrapper)(JNIEnv *jEnv, lcjsobject jsobj); |
| |
| /* This allows liveconnect to unwrap a wrapped JSObject that is passed from java to js. |
| This happens when Java code is passing back to JS an object that it got from JS. */ |
| lcjsobject (*unwrap_java_wrapper)(JNIEnv *jEnv, jobject java_wrapper); |
| |
| /* The following set of methods abstract over the JavaVM object. */ |
| JSBool (*create_java_vm)(SystemJavaVM* *jvm, JNIEnv* *initialEnv, void* initargs); |
| JSBool (*destroy_java_vm)(SystemJavaVM* jvm, JNIEnv* initialEnv); |
| JNIEnv* (*attach_current_thread)(SystemJavaVM* jvm); |
| JSBool (*detach_current_thread)(SystemJavaVM* jvm, JNIEnv* env); |
| SystemJavaVM* (*get_java_vm)(JNIEnv* env); |
| |
| /* Reserved for future use */ |
| void * reserved[10]; |
| } JSJCallbacks; |
| |
| /*===========================================================================*/ |
| |
| /* A flag that denotes that a Java package has no sub-packages other than those |
| explicitly pre-defined at the time of initialization. An access |
| to a simple name within such a package, therefore, must either correspond to |
| one of these explicitly pre-defined sub-packages or to a class within this |
| package. It is reasonable for LiveConnect to signal an error if a simple |
| name does not comply with these criteria. */ |
| #define PKG_SYSTEM 1 |
| |
| /* A flag that denotes that a Java package which might contain sub-packages |
| that are not pre-defined at initialization time, because the sub-packages |
| may not be the same in all installations. Therefore, an access to a simple |
| name within such a a package which does not correspond to either a |
| pre-defined sub-package or to a class, must be assummed to refer to an |
| unknown sub-package. This behavior may cause bogus JavaPackage objects to be |
| created if a package name is misspelled, e.g. sun.oi.net. */ |
| #define PKG_USER 2 |
| |
| /* A Java package defined at initialization time. */ |
| typedef struct JavaPackageDef { |
| const char * name; /* e.g. "java.lang" */ |
| const char * path; /* e.g. "java/lang", or NULL for default */ |
| int flags; /* PKG_USER, PKG_SYSTEM, etc. */ |
| int access; /* JSPROP_READONLY or 0 */ |
| } JavaPackageDef; |
| |
| /*===========================================================================*/ |
| |
| /* The following two convenience functions present a complete, but simplified |
| LiveConnect API which is designed to handle the special case of a single |
| Java-VM, with single-threaded operation, and the use of only one JSContext. |
| The full API is in the section below. */ |
| |
| /* Initialize the provided JSContext by setting up the JS classes necessary for |
| reflection and by defining JavaPackage objects for the default Java packages |
| as properties of global_obj. If java_vm is NULL, a new Java VM is |
| created, using the provided classpath in addition to any default classpath. |
| The classpath argument is ignored, however, if java_vm is non-NULL. */ |
| JS_EXPORT_API(JSBool) |
| JSJ_SimpleInit(JSContext *cx, JSObject *global_obj, |
| SystemJavaVM *java_vm, const char *classpath); |
| |
| /* Free up all resources. Destroy the Java VM if it was created by LiveConnect */ |
| JS_EXPORT_API(void) |
| JSJ_SimpleShutdown(void); |
| |
| /*===========================================================================*/ |
| |
| /* The "full" LiveConnect API, required when more than one thread, Java VM, or |
| JSContext is involved. Initialization pseudocode might go roughly like |
| this: |
| |
| JSJ_Init() // Setup callbacks |
| for each JavaVM { |
| JSJ_ConnectToJavaVM(...) |
| } |
| for each JSContext { |
| JSJ_InitJSContext(...) |
| } |
| for each JS evaluation { |
| run JavaScript code in the JSContext; |
| } |
| */ |
| |
| /* Called once for all instances of LiveConnect to set up callbacks */ |
| JS_EXPORT_API(void) |
| JSJ_Init(JSJCallbacks *callbacks); |
| |
| /* Called once per Java VM, this function initializes the classes, fields, and |
| methods required for Java reflection. If java_vm is NULL, a new Java VM is |
| created according to the create_java_vm callback in the JSJCallbacks, |
| using the provided classpath in addition to any default initargs. |
| The initargs argument is ignored, however, if java_vm is non-NULL. */ |
| JS_EXPORT_API(JSJavaVM *) |
| JSJ_ConnectToJavaVM(SystemJavaVM *java_vm, void* initargs); |
| |
| /* Initialize the provided JSContext by setting up the JS classes necessary for |
| reflection and by defining JavaPackage objects for the default Java packages |
| as properties of global_obj. Additional packages may be pre-defined by |
| setting the predefined_packages argument. (Pre-defining a Java package at |
| initialization time is not necessary, but it will make package lookup faster |
| and, more importantly, will avoid unnecessary network accesses if classes |
| are being loaded over the network.) */ |
| JS_EXPORT_API(JSBool) |
| JSJ_InitJSContext(JSContext *cx, JSObject *global_obj, |
| JavaPackageDef *predefined_packages); |
| |
| /* This function returns a structure that encapsulates the Java and JavaScript |
| execution environment for the current native thread. It is intended to |
| be called from the embedder's implementation of JSJCallback's |
| map_js_context_to_jsj_thread() function. The thread_name argument is only |
| used for debugging purposes and can be set to NULL. The Java JNI |
| environment associated with this thread is returned through the java_envp |
| argument if java_envp is non-NULL. */ |
| JS_EXPORT_API(JSJavaThreadState *) |
| JSJ_AttachCurrentThreadToJava(JSJavaVM *jsjava_vm, const char *thread_name, |
| JNIEnv **java_envp); |
| |
| /* Destructor routine for per-thread JSJavaThreadState structure */ |
| JS_EXPORT_API(JSBool) |
| JSJ_DetachCurrentThreadFromJava(JSJavaThreadState *jsj_env); |
| |
| /* This function is used to specify a particular JSContext as *the* JavaScript |
| execution environment to be used when LiveConnect is accessed from the given |
| Java thread, i.e. when one of the methods of netscape.javascript.JSObject |
| has been called. There can only be one such JS context for any given Java |
| thread at a time. (To multiplex JSContexts among a single thread, this |
| function could be called before Java is invoked on that thread.) The return |
| value is the previous JSContext associated with the given Java thread. |
| |
| If this function has not been called for a thread and a crossing is made |
| into JavaScript from Java, the map_jsj_thread_to_js_context() callback will |
| be invoked to determine the JSContext for the thread. The purpose of the |
| function is to improve performance by avoiding the expense of the callback. |
| */ |
| JS_EXPORT_API(JSContext *) |
| JSJ_SetDefaultJSContextForJavaThread(JSContext *cx, JSJavaThreadState *jsj_env); |
| |
| /* This routine severs the connection to a Java VM, freeing all related resources. |
| It shouldn't be called until the global scope has been cleared in all related |
| JSContexts (so that all LiveConnect objects are finalized) and a JavaScript |
| GC is performed. Otherwise, accessed to free'ed memory could result. */ |
| JS_EXPORT_API(void) |
| JSJ_DisconnectFromJavaVM(JSJavaVM *); |
| |
| /* |
| * Reflect a Java object into a JS value. The source object, java_obj, must |
| * be of type java.lang.Object or a subclass and may, therefore, be an array. |
| */ |
| JS_EXPORT_API(JSBool) |
| JSJ_ConvertJavaObjectToJSValue(JSContext *cx, jobject java_obj, jsval *vp); |
| |
| JS_EXPORT_API(JSBool) |
| JSJ_ConvertJSValueToJavaObject(JSContext *cx, jsval js_val, jobject *vp); |
| |
| JS_EXPORT_API(JSBool) |
| JSJ_IsJSCallApplet(); |
| |
| JS_END_EXTERN_C |
| |
| #endif /* _JSJAVA_H */ |
