Back to index

lightning-sunbird  0.9+nobinonly
jsjava.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
00002  *
00003  * ***** BEGIN LICENSE BLOCK *****
00004  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00005  *
00006  * The contents of this file are subject to the Mozilla Public License Version
00007  * 1.1 (the "License"); you may not use this file except in compliance with
00008  * the License. You may obtain a copy of the License at
00009  * http://www.mozilla.org/MPL/
00010  *
00011  * Software distributed under the License is distributed on an "AS IS" basis,
00012  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00013  * for the specific language governing rights and limitations under the
00014  * License.
00015  *
00016  * The Original Code is Mozilla Communicator client code, released
00017  * March 31, 1998.
00018  *
00019  * The Initial Developer of the Original Code is
00020  * Netscape Communications Corporation.
00021  * Portions created by the Initial Developer are Copyright (C) 1998
00022  * the Initial Developer. All Rights Reserved.
00023  *
00024  * Contributor(s):
00025  *
00026  * Alternatively, the contents of this file may be used under the terms of
00027  * either of the GNU General Public License Version 2 or later (the "GPL"),
00028  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00029  * in which case the provisions of the GPL or the LGPL are applicable instead
00030  * of those above. If you wish to allow use of your version of this file only
00031  * under the terms of either the GPL or the LGPL, and not to allow others to
00032  * use your version of this file under the terms of the MPL, indicate your
00033  * decision by deleting the provisions above and replace them with the notice
00034  * and other provisions required by the GPL or the LGPL. If you do not delete
00035  * the provisions above, a recipient may use your version of this file under
00036  * the terms of any one of the MPL, the GPL or the LGPL.
00037  *
00038  * ***** END LICENSE BLOCK ***** */
00039  
00040 /*
00041  * This file is part of the Java-vendor-neutral implementation of LiveConnect
00042  *
00043  * Publicly exported functions for JavaScript <==> Java communication.
00044  *
00045  */
00046  
00047 #ifndef _JSJAVA_H
00048 #define _JSJAVA_H
00049 
00050 #ifndef jstypes_h___
00051 #include "jstypes.h"
00052 #endif
00053 
00054 JS_BEGIN_EXTERN_C
00055 
00056 #include "jni.h"             /* Java Native Interface */
00057 #include "jsapi.h"           /* JavaScript engine API */
00058 
00059 #if JS_BYTES_PER_LONG == 8
00060 typedef jlong lcjsobject;
00061 #else
00062 typedef jint lcjsobject;
00063 #endif
00064 
00065 /*
00066  * A JSJavaVM structure is a wrapper around a JavaVM which incorporates
00067  * additional LiveConnect state.
00068  */
00069 typedef struct JSJavaVM JSJavaVM;
00070 
00071 /* LiveConnect and Java state, one per thread */
00072 typedef struct JSJavaThreadState JSJavaThreadState;
00073 
00074 /*
00075  * An opaque type that represents the connection to the Java VM. In stand-alone
00076  * Java environments, this may be a JNI JavaVM object; in the browser environment
00077  * it is a reference to a JVM plugin. A set of callbacks in the JSJCallbacks
00078  * struct allow it to be manipulated.
00079  */
00080 #ifdef OJI
00081 typedef struct SystemJavaVM SystemJavaVM;
00082 #else
00083 typedef JavaVM SystemJavaVM;
00084 #endif
00085 
00086 /*
00087  * This callback table provides hooks to external functions that implement
00088  * functionality specific to the embedding.  For example, these callbacks are
00089  * necessary in multi-threaded environments or to implement a security
00090  * policy.
00091  */
00092 typedef struct JSJCallbacks {
00093 
00094     /* This callback is invoked when there is no JavaScript execution
00095        environment (JSContext) associated with the current Java thread and
00096        a call is made from Java into JavaScript.  (A JSContext is associated
00097        with a Java thread by calling the JSJ_SetDefaultJSContextForJavaThread()
00098        function.)  This callback is only invoked when Java spontaneously calls
00099        into JavaScript, i.e. it is not called when JS calls into Java which
00100        calls back into JS.
00101        
00102        This callback can be used to create a JSContext lazily, or obtain
00103        one from a pool of available JSContexts.  The implementation of this
00104        callback can call JSJ_SetDefaultJSContextForJavaThread() to avoid any
00105        further callbacks of this type for this Java thread. */
00106     JSContext *         (*map_jsj_thread_to_js_context)(JSJavaThreadState *jsj_env,
00107 #ifdef OJI
00108                                                         void *java_applet_obj,
00109 #endif
00110                                                         JNIEnv *jEnv,
00111                                                         char **errp);
00112 
00113     /* This callback is invoked whenever a call is made into Java from
00114        JavaScript.  It's responsible for mapping from a JavaScript execution
00115        environment (JSContext) to a Java thread.  (A JavaContext can only
00116        be associated with one Java thread at a time.) */
00117     JSJavaThreadState * (*map_js_context_to_jsj_thread)(JSContext *cx,
00118                                                         char **errp);
00119                                                         
00120     /* This callback implements netscape.javascript.JSObject.getWindow(),
00121        a method named for its behavior in the browser environment, where it
00122        returns the JS "Window" object corresponding to the HTML window that an
00123        applet is embedded within.  More generally, it's a way for Java to get
00124        hold of a JS object that has not been explicitly passed to it. */
00125     JSObject *          (*map_java_object_to_js_object)(JNIEnv *jEnv, void *pJavaObject,
00126                                                         char **errp);
00127         
00128     /* An interim callback function until the LiveConnect security story is
00129        straightened out.  This function pointer can be set to NULL. */
00130     JSPrincipals *      (*get_JSPrincipals_from_java_caller)(JNIEnv *jEnv, JSContext *pJSContext, void **pNSIPrincipaArray, int numPrincipals, void *pNSISecurityContext);
00131     
00132     /* The following two callbacks sandwich any JS evaluation performed
00133        from Java.   They may be used to implement concurrency constraints, e.g.
00134        by suspending the current thread until some condition is met.  In the
00135        browser embedding, these are used to maintain the run-to-completion
00136        semantics of JavaScript.  It is acceptable for either function pointer
00137        to be NULL. */
00138 #ifdef OJI
00139     JSBool              (*enter_js_from_java)(JNIEnv *jEnv, char **errp,  void **pNSIPrincipaArray, int numPrincipals, void *pNSISecurityContext,void* applet_obj);
00140 #else
00141     JSBool              (*enter_js_from_java)(JNIEnv *jEnv, char **errp);
00142 #endif
00143     void                (*exit_js)(JNIEnv *jEnv, JSContext *cx);
00144 
00145     /* Most LiveConnect errors are signaled by calling JS_ReportError(), but in
00146        some circumstances, the target JSContext for such errors is not
00147        determinable, e.g. during initialization.  In such cases any error
00148        messages are routed to this function.  If the function pointer is set to
00149        NULL, error messages are sent to stderr. */
00150     void                (*error_print)(const char *error_msg);
00151 
00152     /* This enables liveconnect to ask the VM for a java wrapper so that VM gets a chance to
00153        store a mapping between a jsobject and java wrapper. So the unwrapping can be done on the
00154        VM side before calling nsILiveconnect apis. This saves on a round trip request. */
00155     jobject             (*get_java_wrapper)(JNIEnv *jEnv, lcjsobject jsobj);
00156 
00157     /* This allows liveconnect to unwrap a wrapped JSObject that is passed from java to js. 
00158        This happens when Java code is passing back to JS an object that it got from JS. */
00159     lcjsobject          (*unwrap_java_wrapper)(JNIEnv *jEnv, jobject java_wrapper);
00160 
00161     /* The following set of methods abstract over the JavaVM object. */
00162     JSBool              (*create_java_vm)(SystemJavaVM* *jvm, JNIEnv* *initialEnv, void* initargs);
00163     JSBool              (*destroy_java_vm)(SystemJavaVM* jvm, JNIEnv* initialEnv);
00164     JNIEnv*             (*attach_current_thread)(SystemJavaVM* jvm);
00165     JSBool              (*detach_current_thread)(SystemJavaVM* jvm, JNIEnv* env);
00166     SystemJavaVM*       (*get_java_vm)(JNIEnv* env);
00167 
00168     /* Reserved for future use */
00169     void *              reserved[10];
00170 } JSJCallbacks;
00171 
00172 /*===========================================================================*/
00173 
00174 /* A flag that denotes that a Java package has no sub-packages other than those
00175    explicitly pre-defined at the time of initialization.  An access
00176    to a simple name within such a package, therefore, must either correspond to
00177    one of these explicitly pre-defined sub-packages or to a class within this
00178    package.  It is reasonable for LiveConnect to signal an error if a simple
00179    name does not comply with these criteria. */
00180 #define PKG_SYSTEM      1
00181 
00182 /* A flag that denotes that a Java package which might contain sub-packages
00183    that are not pre-defined at initialization time, because the sub-packages
00184    may not be the same in all installations.  Therefore, an access to a simple
00185    name within such a a package which does not correspond to either a
00186    pre-defined sub-package or to a class, must be assummed to refer to an
00187    unknown sub-package.  This behavior may cause bogus JavaPackage objects to be
00188    created if a package name is misspelled, e.g. sun.oi.net. */
00189 #define PKG_USER        2
00190 
00191 /* A Java package defined at initialization time. */
00192 typedef struct JavaPackageDef {
00193     const char *        name;   /* e.g. "java.lang" */
00194     const char *        path;   /* e.g. "java/lang", or NULL for default */
00195     int                 flags;  /* PKG_USER, PKG_SYSTEM, etc. */
00196     int                 access; /* JSPROP_READONLY or 0 */            
00197 } JavaPackageDef;
00198 
00199 /*===========================================================================*/
00200 
00201 /* The following two convenience functions present a complete, but simplified
00202    LiveConnect API which is designed to handle the special case of a single 
00203    Java-VM, with single-threaded operation, and the use of only one JSContext.
00204    The full API is in the section below. */
00205 
00206 /* Initialize the provided JSContext by setting up the JS classes necessary for
00207    reflection and by defining JavaPackage objects for the default Java packages
00208    as properties of global_obj.  If java_vm is NULL, a new Java VM is
00209    created, using the provided classpath in addition to any default classpath.
00210    The classpath argument is ignored, however, if java_vm is non-NULL. */
00211 JS_EXPORT_API(JSBool)
00212 JSJ_SimpleInit(JSContext *cx, JSObject *global_obj,
00213                SystemJavaVM *java_vm, const char *classpath);
00214 
00215 /* Free up all resources.  Destroy the Java VM if it was created by LiveConnect */
00216 JS_EXPORT_API(void)
00217 JSJ_SimpleShutdown(void);
00218 
00219 /*===========================================================================*/
00220 
00221 /* The "full" LiveConnect API, required when more than one thread, Java VM, or
00222    JSContext is involved.  Initialization pseudocode might go roughly like
00223    this:
00224 
00225    JSJ_Init()   // Setup callbacks
00226    for each JavaVM {
00227       JSJ_ConnectToJavaVM(...)
00228    }
00229    for each JSContext {
00230       JSJ_InitJSContext(...)
00231    }
00232    for each JS evaluation {
00233       run JavaScript code in the JSContext;
00234    }
00235  */
00236 
00237 /* Called once for all instances of LiveConnect to set up callbacks */
00238 JS_EXPORT_API(void)
00239 JSJ_Init(JSJCallbacks *callbacks);
00240 
00241 /* Called once per Java VM, this function initializes the classes, fields, and
00242    methods required for Java reflection.  If java_vm is NULL, a new Java VM is
00243    created according to the create_java_vm callback in the JSJCallbacks,
00244    using the provided classpath in addition to any default initargs.
00245    The initargs argument is ignored, however, if java_vm is non-NULL. */
00246 JS_EXPORT_API(JSJavaVM *)
00247 JSJ_ConnectToJavaVM(SystemJavaVM *java_vm, void* initargs);
00248 
00249 /* Initialize the provided JSContext by setting up the JS classes necessary for
00250    reflection and by defining JavaPackage objects for the default Java packages
00251    as properties of global_obj.  Additional packages may be pre-defined by
00252    setting the predefined_packages argument.  (Pre-defining a Java package at
00253    initialization time is not necessary, but it will make package lookup faster
00254    and, more importantly, will avoid unnecessary network accesses if classes
00255    are being loaded over the network.) */
00256 JS_EXPORT_API(JSBool)
00257 JSJ_InitJSContext(JSContext *cx, JSObject *global_obj,
00258                   JavaPackageDef *predefined_packages);
00259    
00260 /* This function returns a structure that encapsulates the Java and JavaScript
00261    execution environment for the current native thread.  It is intended to
00262    be called from the embedder's implementation of JSJCallback's
00263    map_js_context_to_jsj_thread() function.  The thread_name argument is only
00264    used for debugging purposes and can be set to NULL.  The Java JNI
00265    environment associated with this thread is returned through the java_envp
00266    argument if java_envp is non-NULL.  */
00267 JS_EXPORT_API(JSJavaThreadState *)
00268 JSJ_AttachCurrentThreadToJava(JSJavaVM *jsjava_vm, const char *thread_name,
00269                               JNIEnv **java_envp);
00270 
00271 /* Destructor routine for per-thread JSJavaThreadState structure */
00272 JS_EXPORT_API(JSBool)
00273 JSJ_DetachCurrentThreadFromJava(JSJavaThreadState *jsj_env);
00274 
00275 /* This function is used to specify a particular JSContext as *the* JavaScript
00276    execution environment to be used when LiveConnect is accessed from the given
00277    Java thread, i.e. when one of the methods of netscape.javascript.JSObject
00278    has been called.  There can only be one such JS context for any given Java
00279    thread at a time.  (To multiplex JSContexts among a single thread, this
00280    function could be called before Java is invoked on that thread.)  The return
00281    value is the previous JSContext associated with the given Java thread.
00282 
00283    If this function has not been called for a thread and a crossing is made
00284    into JavaScript from Java, the map_jsj_thread_to_js_context() callback will
00285    be invoked to determine the JSContext for the thread.  The purpose of the 
00286    function is to improve performance by avoiding the expense of the callback.
00287 */
00288 JS_EXPORT_API(JSContext *)
00289 JSJ_SetDefaultJSContextForJavaThread(JSContext *cx, JSJavaThreadState *jsj_env);
00290 
00291 /* This routine severs the connection to a Java VM, freeing all related resources.
00292    It shouldn't be called until the global scope has been cleared in all related
00293    JSContexts (so that all LiveConnect objects are finalized) and a JavaScript
00294    GC is performed.  Otherwise, accessed to free'ed memory could result. */
00295 JS_EXPORT_API(void)
00296 JSJ_DisconnectFromJavaVM(JSJavaVM *);
00297 
00298 /*
00299  * Reflect a Java object into a JS value.  The source object, java_obj, must
00300  * be of type java.lang.Object or a subclass and may, therefore, be an array.
00301  */
00302 JS_EXPORT_API(JSBool)
00303 JSJ_ConvertJavaObjectToJSValue(JSContext *cx, jobject java_obj, jsval *vp);
00304 
00305 JS_EXPORT_API(JSBool)
00306 JSJ_ConvertJSValueToJavaObject(JSContext *cx, jsval js_val, jobject *vp);
00307 
00308 JS_EXPORT_API(JSBool)
00309 JSJ_IsJSCallApplet();
00310 
00311 JS_END_EXTERN_C
00312 
00313 #endif  /* _JSJAVA_H */