js/src/liveconnect/jsjava.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla Communicator client code, released
  17  * March 31, 1998.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1998
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 /*
  41  * This file is part of the Java-vendor-neutral implementation of LiveConnect
  42  *
  43  * Publicly exported functions for JavaScript <==> Java communication.
  44  *
  45  */
  46
  47 #ifndef _JSJAVA_H
  48 #define _JSJAVA_H
  49
  50 #ifndef jstypes_h___
  51 #include "jstypes.h"
  52 #endif
  53
  54 JS_BEGIN_EXTERN_C
  55
  56 #include "jni.h"             /* Java Native Interface */
  57 #include "jsapi.h"           /* JavaScript engine API */
  58
  59 #if JS_BYTES_PER_LONG == 8 || JS_BYTES_PER_WORD == 8
  60 typedef jlong lcjsobject;
  61 #else
  62 typedef jint lcjsobject;
  63 #endif
  64
  65 /*
  66  * A JSJavaVM structure is a wrapper around a JavaVM which incorporates
  67  * additional LiveConnect state.
  68  */
  69 typedef struct JSJavaVM JSJavaVM;
  70
  71 /* LiveConnect and Java state, one per thread */
  72 typedef struct JSJavaThreadState JSJavaThreadState;
  73
  74 /*
  75  * An opaque type that represents the connection to the Java VM. In stand-alone
  76  * Java environments, this may be a JNI JavaVM object; in the browser environment
  77  * it is a reference to a JVM plugin. A set of callbacks in the JSJCallbacks
  78  * struct allow it to be manipulated.
  79  */
  80 #ifdef OJI
  81 typedef struct SystemJavaVM SystemJavaVM;
  82 #else
  83 typedef JavaVM SystemJavaVM;
  84 #endif
  85
  86 /*
  87  * This callback table provides hooks to external functions that implement
  88  * functionality specific to the embedding.  For example, these callbacks are
  89  * necessary in multi-threaded environments or to implement a security
  90  * policy.
  91  *
  92  * Note: The error message returned by errp has to be created by JS_smprintf.
  93  * See bug: https://bugzilla.mozilla.org/show_bug.cgi?id=261468.
  94  */
  95 typedef struct JSJCallbacks {
  96
  97     /* This callback is invoked when there is no JavaScript execution
  98        environment (JSContext) associated with the current Java thread and
  99        a call is made from Java into JavaScript.  (A JSContext is associated
 100        with a Java thread by calling the JSJ_SetDefaultJSContextForJavaThread()
 101        function.)  This callback is only invoked when Java spontaneously calls
 102        into JavaScript, i.e. it is not called when JS calls into Java which
 103        calls back into JS.
 104
 105        This callback can be used to create a JSContext lazily, or obtain
 106        one from a pool of available JSContexts.  The implementation of this
 107        callback can call JSJ_SetDefaultJSContextForJavaThread() to avoid any
 108        further callbacks of this type for this Java thread. */
 109     JSContext *         (*map_jsj_thread_to_js_context)(JSJavaThreadState *jsj_env,
 110 #ifdef OJI
 111                                                         void *java_applet_obj,
 112 #endif
 113                                                         JNIEnv *jEnv,
 114                                                         char **errp);
 115
 116     /* This callback is invoked whenever a call is made into Java from
 117        JavaScript.  It's responsible for mapping from a JavaScript execution
 118        environment (JSContext) to a Java thread.  (A JavaContext can only
 119        be associated with one Java thread at a time.) */
 120     JSJavaThreadState * (*map_js_context_to_jsj_thread)(JSContext *cx,
 121                                                         char **errp);
 122
 123     /* This callback implements netscape.javascript.JSObject.getWindow(),
 124        a method named for its behavior in the browser environment, where it
 125        returns the JS "Window" object corresponding to the HTML window that an
 126        applet is embedded within.  More generally, it's a way for Java to get
 127        hold of a JS object that has not been explicitly passed to it. */
 128     JSObject *          (*map_java_object_to_js_object)(JNIEnv *jEnv, void *pJavaObject,
 129                                                         char **errp);
 130
 131     /* An interim callback function until the LiveConnect security story is
 132        straightened out.  This function pointer can be set to NULL. */
 133     JSPrincipals *      (*get_JSPrincipals_from_java_caller)(JNIEnv *jEnv, JSContext *pJSContext, void **pNSIPrincipaArray, int numPrincipals, void *pNSISecurityContext);
 134
 135     /* The following two callbacks sandwich any JS evaluation performed
 136        from Java.   They may be used to implement concurrency constraints, e.g.
 137        by suspending the current thread until some condition is met.  In the
 138        browser embedding, these are used to maintain the run-to-completion
 139        semantics of JavaScript.  It is acceptable for either function pointer
 140        to be NULL. */
 141 #ifdef OJI
 142     JSBool              (*enter_js_from_java)(JNIEnv *jEnv, char **errp,  void **pNSIPrincipaArray, int numPrincipals, void *pNSISecurityContext,void* applet_obj);
 143 #else
 144     JSBool              (*enter_js_from_java)(JNIEnv *jEnv, char **errp);
 145 #endif
 146     void                (*exit_js)(JNIEnv *jEnv, JSContext *cx);
 147
 148     /* Most LiveConnect errors are signaled by calling JS_ReportError(), but in
 149        some circumstances, the target JSContext for such errors is not
 150        determinable, e.g. during initialization.  In such cases any error
 151        messages are routed to this function.  If the function pointer is set to
 152        NULL, error messages are sent to stderr. */
 153     void                (*error_print)(const char *error_msg);
 154
 155     /* This enables liveconnect to ask the VM for a java wrapper so that VM gets a chance to
 156        store a mapping between a jsobject and java wrapper. So the unwrapping can be done on the
 157        VM side before calling nsILiveconnect apis. This saves on a round trip request. */
 158     jobject             (*get_java_wrapper)(JNIEnv *jEnv, lcjsobject jsobj);
 159
 160     /* This allows liveconnect to unwrap a wrapped JSObject that is passed from java to js.
 161        This happens when Java code is passing back to JS an object that it got from JS. */
 162     lcjsobject          (*unwrap_java_wrapper)(JNIEnv *jEnv, jobject java_wrapper);
 163
 164     /* The following set of methods abstract over the JavaVM object. */
 165     JSBool              (*create_java_vm)(SystemJavaVM* *jvm, JNIEnv* *initialEnv, void* initargs);
 166     JSBool              (*destroy_java_vm)(SystemJavaVM* jvm, JNIEnv* initialEnv);
 167     JNIEnv*             (*attach_current_thread)(SystemJavaVM* jvm);
 168     JSBool              (*detach_current_thread)(SystemJavaVM* jvm, JNIEnv* env);
 169     SystemJavaVM*       (*get_java_vm)(JNIEnv* env);
 170
 171     /* Reserved for future use */
 172     void *              reserved[10];
 173 } JSJCallbacks;
 174
 175 /*===========================================================================*/
 176
 177 /* A flag that denotes that a Java package has no sub-packages other than those
 178    explicitly pre-defined at the time of initialization.  An access
 179    to a simple name within such a package, therefore, must either correspond to
 180    one of these explicitly pre-defined sub-packages or to a class within this
 181    package.  It is reasonable for LiveConnect to signal an error if a simple
 182    name does not comply with these criteria. */
 183 #define PKG_SYSTEM      1
 184
 185 /* A flag that denotes that a Java package which might contain sub-packages
 186    that are not pre-defined at initialization time, because the sub-packages
 187    may not be the same in all installations.  Therefore, an access to a simple
 188    name within such a a package which does not correspond to either a
 189    pre-defined sub-package or to a class, must be assummed to refer to an
 190    unknown sub-package.  This behavior may cause bogus JavaPackage objects to be
 191    created if a package name is misspelled, e.g. sun.oi.net. */
 192 #define PKG_USER        2
 193
 194 /* A Java package defined at initialization time. */
 195 typedef struct JavaPackageDef {
 196     const char *        name;   /* e.g. "java.lang" */
 197     const char *        path;   /* e.g. "java/lang", or NULL for default */
 198     int                 flags;  /* PKG_USER, PKG_SYSTEM, etc. */
 199     int                 access; /* JSPROP_READONLY or 0 */
 200 } JavaPackageDef;
 201
 202 /*===========================================================================*/
 203
 204 /* The following two convenience functions present a complete, but simplified
 205    LiveConnect API which is designed to handle the special case of a single
 206    Java-VM, with single-threaded operation, and the use of only one JSContext.
 207    The full API is in the section below. */
 208
 209 /* Initialize the provided JSContext by setting up the JS classes necessary for
 210    reflection and by defining JavaPackage objects for the default Java packages
 211    as properties of global_obj.  If java_vm is NULL, a new Java VM is
 212    created, using the provided classpath in addition to any default classpath.
 213    The classpath argument is ignored, however, if java_vm is non-NULL. */
 214 JS_EXPORT_API(JSBool)
 215 JSJ_SimpleInit(JSContext *cx, JSObject *global_obj,
 216                SystemJavaVM *java_vm, const char *classpath);
 217
 218 /* Free up all resources.  Destroy the Java VM if it was created by LiveConnect */
 219 JS_EXPORT_API(void)
 220 JSJ_SimpleShutdown(void);
 221
 222 /*===========================================================================*/
 223
 224 /* The "full" LiveConnect API, required when more than one thread, Java VM, or
 225    JSContext is involved.  Initialization pseudocode might go roughly like
 226    this:
 227
 228    JSJ_Init()   // Setup callbacks
 229    for each JavaVM {
 230       JSJ_ConnectToJavaVM(...)
 231    }
 232    for each JSContext {
 233       JSJ_InitJSContext(...)
 234    }
 235    for each JS evaluation {
 236       run JavaScript code in the JSContext;
 237    }
 238  */
 239
 240 /* Called once for all instances of LiveConnect to set up callbacks */
 241 JS_EXPORT_API(void)
 242 JSJ_Init(JSJCallbacks *callbacks);
 243
 244 /* Called once per Java VM, this function initializes the classes, fields, and
 245    methods required for Java reflection.  If java_vm is NULL, a new Java VM is
 246    created according to the create_java_vm callback in the JSJCallbacks,
 247    using the provided classpath in addition to any default initargs.
 248    The initargs argument is ignored, however, if java_vm is non-NULL. */
 249 JS_EXPORT_API(JSJavaVM *)
 250 JSJ_ConnectToJavaVM(SystemJavaVM *java_vm, void* initargs);
 251
 252 /* Initialize the provided JSContext by setting up the JS classes necessary for
 253    reflection and by defining JavaPackage objects for the default Java packages
 254    as properties of global_obj.  Additional packages may be pre-defined by
 255    setting the predefined_packages argument.  (Pre-defining a Java package at
 256    initialization time is not necessary, but it will make package lookup faster
 257    and, more importantly, will avoid unnecessary network accesses if classes
 258    are being loaded over the network.) */
 259 JS_EXPORT_API(JSBool)
 260 JSJ_InitJSContext(JSContext *cx, JSObject *global_obj,
 261                   JavaPackageDef *predefined_packages);
 262
 263 /* This function returns a structure that encapsulates the Java and JavaScript
 264    execution environment for the current native thread.  It is intended to
 265    be called from the embedder's implementation of JSJCallback's
 266    map_js_context_to_jsj_thread() function.  The thread_name argument is only
 267    used for debugging purposes and can be set to NULL.  The Java JNI
 268    environment associated with this thread is returned through the java_envp
 269    argument if java_envp is non-NULL.  */
 270 JS_EXPORT_API(JSJavaThreadState *)
 271 JSJ_AttachCurrentThreadToJava(JSJavaVM *jsjava_vm, const char *thread_name,
 272                               JNIEnv **java_envp);
 273
 274 /* Destructor routine for per-thread JSJavaThreadState structure */
 275 JS_EXPORT_API(JSBool)
 276 JSJ_DetachCurrentThreadFromJava(JSJavaThreadState *jsj_env);
 277
 278 /* This function is used to specify a particular JSContext as *the* JavaScript
 279    execution environment to be used when LiveConnect is accessed from the given
 280    Java thread, i.e. when one of the methods of netscape.javascript.JSObject
 281    has been called.  There can only be one such JS context for any given Java
 282    thread at a time.  (To multiplex JSContexts among a single thread, this
 283    function could be called before Java is invoked on that thread.)  The return
 284    value is the previous JSContext associated with the given Java thread.
 285
 286    If this function has not been called for a thread and a crossing is made
 287    into JavaScript from Java, the map_jsj_thread_to_js_context() callback will
 288    be invoked to determine the JSContext for the thread.  The purpose of the
 289    function is to improve performance by avoiding the expense of the callback.
 290 */
 291 JS_EXPORT_API(JSContext *)
 292 JSJ_SetDefaultJSContextForJavaThread(JSContext *cx, JSJavaThreadState *jsj_env);
 293
 294 /* This routine severs the connection to a Java VM, freeing all related resources.
 295    It shouldn't be called until the global scope has been cleared in all related
 296    JSContexts (so that all LiveConnect objects are finalized) and a JavaScript
 297    GC is performed.  Otherwise, accessed to free'ed memory could result. */
 298 JS_EXPORT_API(void)
 299 JSJ_DisconnectFromJavaVM(JSJavaVM *);
 300
 301 /*
 302  * Reflect a Java object into a JS value.  The source object, java_obj, must
 303  * be of type java.lang.Object or a subclass and may, therefore, be an array.
 304  */
 305 JS_EXPORT_API(JSBool)
 306 JSJ_ConvertJavaObjectToJSValue(JSContext *cx, jobject java_obj, jsval *vp);
 307
 308 JS_EXPORT_API(JSBool)
 309 JSJ_ConvertJSValueToJavaObject(JSContext *cx, jsval js_val, jobject *vp);
 310
 311 JS_EXPORT_API(JSBool)
 312 JSJ_IsJSCallApplet();
 313
 314 JS_END_EXTERN_C
 315
 316 #endif  /* _JSJAVA_H */