Introduction

This is the README file for the JavaScript LiveConnect Version 2 ("LC2") implementation.  It consists of build conventions and instructions, source code conventions, and a brief file-by-file description of the source.

This document assumes basic familiarity with JSRef, the reference implementation of JavaScript, and with the LiveConnect technology  (LiveConnect allows JavaScript and Java virtual machines to be connected.  It enables JavaScript to access Java fields, invoke Java methods and makes it possible for Java to access JavaScript object properties and evaluate JavaScript.  More information on LiveConnect can be found by searching the index on Netscape's DevEdge site.)

JSRef project/makefiles build a library or DLL containing the JavaScript runtime (compiler, interpreter, decompiler, garbage collector, atom manager, standard classes).  The LiveConnect project/makefiles build a library that links both with JSRef and with a Java Virtual Machine (JVM) that implements the Java Native Interface (JNI), as specified by JavaSoft.  It then compiles a small "shell" program and links that with the library to make an interpreter that can be used interactively and with test scripts.

Scott Furman, 4/8/98

Compatibility

Unlike this release, all previous versions of LiveConnect appeared only as a component of Netscape Navigator, not as a standalone module.  The variants of LiveConnect that appeared in Navigator versions 3.x and 4.x all behave much the same, modulo bugs.  For brevity we refer to this classic version of LiveConnect as "LC1" and this most recent release as "LC2".  The following incompatibilities with LC1 are known:

New Features

Several minor features have been added to this release of LiveConnect.  These features were not available in the versions of LiveConnect that were integrated with Netscape Naviagtor versions 4.x and earlier.
  • The Java methods of java.lang.Object are now invokeable methods of JavaArray objects, matching the behavior of arrays when accessed from Java.  (Java arrays are a subclass of java.lang.Object.) For example, Java's getClass() and hashCode() methods can now be called on JavaArray objects.  (In prior versions of LiveConnect, the methods of java.lang.Object were only inherited by non-array Java objects.)
  • Note that this change has caused the string representation of JavaArray objects to change.  Previously, the JavaArray toString() method always printed "[object JavaArray]" for all JavaArray's.  Now, the Java java.lang.Object.toString() method is called to convert JavaArray objects to strings, just as with other, non-array Java objects that are accessible via LiveConnect.  java.lang.Object.toString()is defined in the Java Language Specification to return the value of the following expression:

    getClass().getName() + '@' + Integer.toHexString(hashCode())
     

  • A one-character string is now an acceptable match for an argument to a Java method of type char.  (In earlier versions of LiveConnect, the only acceptable match for a char had to be a JavaScript value that was convertible to a number.)  For example, the following is now possible:
  • c = new java.lang.Character("F")
     

  • A JavaClass object is now an acceptable match for an argument to a Java method of type java.lang.Class.  For example, you can now write:
  • java.lang.reflect.Array.newInstance(java.lang.String, 3)

    instead of the more verbose:

    jls = java.lang.Class.forName("java.lang.String")
    java.lang.reflect.Array.newInstance(jls, 3)
     

    Build conventions

    Update your JVM's CLASSPATH to point to the liveconnect/classes subdirectory.  If you do not, LiveConnect will still operate but with the limitation that JS objects may not be passed as arguments of Java methods and it will not be possible to call from Java into JavaScript, i.e. the netscape.javascript.JSObject class will be inaccessible.  Another downside of operating without these classes is that Java error messages will not include a Java stack trace, when one is available.  If your CLASSPATH is set improperly, you will see a message like, "initialization error: Can't load class netscape/javascript/JSObject" when starting a LiveConnect debug build.

    By default, LiveConnect is not re-entrant.  To enable multi-threaded execution, define the JS_THREADSAFE cpp macro and flesh out the stubs and required headers in jslock.c/.h.  See the JS API docs for more.  JSRef must also be built with JS_THREADSAFE.
     

    Naming and coding conventions:

    The LiveConnect API

    All public LiveConnect entry points and callbacks are documented in jsjava.h, the header file that exports those functions.
     

    File Walk-through

     
    jsjava.h LiveConnect's only public header file.  Defines all public API entry points, callbacks and types. 
    jsj_private.h LiveConnect internal header file for intra-module sharing of functions and types
    jsj.c Public LiveConnect API entry points and initialization code
    jsj_array.c Read and write elements of a Java array, performing needed conversions to/from JS types.
    jsj_class.c Construct and manipulate JavaClassDescriptor structs, which are the native representation for Java classes.  JavaClassDescriptors are used to describe the methods and fields of a class, including their type signatures, and include a reference to the peer java.lang.Class object.  Since each Java object has a class, there is a JavaClassDescriptor associated with the JavaScript reflection of each Java Object.
    jsj_convert.c Convert between Java and JavaScript values of all types, which may require calling routines in other files to wrap JS objects as Java objects and vice-versa.
    jsj_field.c Reflect Java fields as properties of JavaObject objects and implement getter/setter access to those fields.
    jsj_JavaArray.c Implementation of the JavaScript JavaArray class.  Instances of JavaArray are used to reflect Java arrays.
    jsj_JavaClass.c Implementation of the JavaScript JavaClass class.   Instances of JavaClass are used to reflect Java classes.
    jsj_JavaObject.c Implementation of the JavaScript JavaObject class.   Instances of JavaObject are used to reflect Java objects, except for Java arrays, although some of the code in this file is used by the JavaArray code.
    jsj_JavaMember.c Implementation of the JavaScript JavaMember class.  JavaMember's are a strange beast required only to handle the special case of a public field and a public method that appear in the same Java class and which have the same name.
    jsj_JavaPackage.c Implementation of the JavaScript JavaPackage class.   Instances of JavaPackage are used to reflect Java packages.  The JS properties of a JavaPackage are either nested JavaPackage objects or a JavaClass object.
    jsj_JSObject.c Implementation of the native methods for the  netscape.javascript.JSObject Java class, which are used for calling into JavaScript from Java.  It also contains the code that wraps JS objects as instances of  netscape.javascript.JSObject and the code that handles propagation of exceptions both into and out of Java.
    jsj_method.c Reflect Java methods as properties of JavaObject objects and make it possible to invoke those methods.  Includes overloaded method resolution and argument/return-value conversion code.
    jsj_utils.c Low-level utility code for reporting errors, etc.