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:
-
As in LC1, JavaScript objects appear to Java as instances of netscape.javascript.JSObject.
In LC1, two JSObject's could be tested for equality, i.e. to see
if they refer to the same instance, by using the `==' operator. Instead,
developers must now use the equals()method of netscape.javascript.JSObject
for comparison, a method that overrides java.lang.Object.equals().
Using equals() instead of `==' should work the same on both LC1
and LC2.
It is not possible to replicate the identity behavior of the `==' operator
that LC1 provides without the use of "weak" references, i.e. references
that do not contribute to making a Java object reachable for purposes of
garbage collection, but which nonetheless allow reference to an object
as long as it is reachable by other means. The use of weak references
is not portable, however. It is not part of the JNI or the JDK and
it is not provided on all JVMs. The JDK1.2 release will include standard
support for weak references.
-
It's possible that, in a set of overloaded Java methods, more than one
method is compatible with the types of the actual arguments in a call from
JavaScript via LiveConnect. LC1 resolved these ambiguities in a simplistic
manner, by simply invoking whatever method was enumerated first by the
JVM. The enumeration order of reflected methods using java.lang.reflect
is not specified by Sun and may differ among vendor's JVMs, i.e. enumeration
could be in order of classfile appearance, hashtable order, etc.
With the Netscape and Sun JVMs, it is possible to change the behavior of
an LC1 program by changing the order that Java methods appear in a source
file, thus changing the method enumeration order. Hence, the Java
method chosen when there is more than one compatible method may vary depending
on the JVM.
A future release of LiveConnect will provide a new algorithm for overloaded
Java method resolution that is both independent of the JVM used and more
likely than LC1 to invoke the method that the developer expects.
-
There are several minor changes in error handling to make LiveConnect more
conformant to ECMAScript. These include, for example, making any
attempt to delete JavaObject, JavaClass or JavaPackage properties fail
silently, rather than causing an error. Also, some error messages
have been changed to be more informative. These changes should generally
be backward-compatible with LC1 because few programs that use LiveConnect
will depend on the exact behavior of LiveConnect when handling errors.
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.
Windows
-
Use MSDEV5.0 with the LiveConnectShell.dsw
project file.
-
You must first build the JS runtime, js32.dll, by using the normal JSRef
build procedure.
-
Identify the JVM that you are linking against by setting the JDK
environment variable to point to the top-level JDK directory, e.g. D:\jdk1.1.5.
This is used to establish paths for header file inclusion, linking and
execution. If you are not using Sun's JVM, the project files may
require manual tweaking to set these paths correctly.
-
The output files (DLLs and executables) are placed in the js/ref/liveconnect/Debug
or js/ref/liveconnect/Release directories.
-
The LiveConnect-enabled shell is named lcshell.exe
and appears in the output directory.
-
You must have the JVM DLL in your PATH environment
variable in order to run. If you are using the Sun JDK, the DLL appears
in the JDK's bin directory.
-
Use any Java compiler to compile the java source files in the js/ref/liveconnect/classes/netscape/javascript
directory.
Mac OS
-
Using CodeWarrior Pro 3 is recommended. With some modifications,
the project files can be made to work with CodeWarrior Pro 2. The
CodeWarrior project files are js/ref/liveconnect/macbuild/LiveConnect.mcp,
js/ref/liveconnect/macbuild/LiveConnectShell.mcp,
and js/ref/macbuild/JSRef.mcp.
-
Install Apple's JVM, MRJ 2.0 (or later), and the MRJ
SDK v2.0.1ea4. Note: You do not need to install MRJ if you are
running a recent version of MacOS 8, since it is shipped with the OS.
-
Copy the folders CIncludes & Libraries from the SDK's Interfaces&Libraries
directory to js/ref/liveconnect/macbuild/JavaSession.
-
Build the JavaScript test application, JSRef,
with js/ref/macbuild/JSRef.mcp.
-
Build the LiveConnect test application, LiveConnectShell,
with js/ref/liveconnect/macbuild/LiveConnectShell.mcp.
-
Build liveconnect.jar with js/ref/liveconnect/macbuild/LiveConnect.mcp.
-
Make an alias to liveconnect.jar and place
it in "{SystemFolder}Extensions:MRJ Libraries:MRJClasses".
Unix
-
Use vendor cc or gcc for compiling,
and use gmake for building.
-
Makefile has only been tested on Solaris 5.5. To build on other platforms
you must add a .mk file to the ref/liveconnect/config subdir.
Naming and coding conventions:
-
Public function names begin with JSJ_ followed by capitalized "intercaps",
e.g. JSJ_ConnectToJavaVM.
-
Extern but library-private function names use a jsj_ prefix and mixed case,
e.g. jsj_LookupSymbol.
-
Most static function names have unprefixed, underscore-separated names:
get_char.
-
But static native methods of JS objects have intercaps names, e.g., JavaObject_getProperty().
-
And library-private and static data use underscores, not intercaps (but
library-private data do use a js_ prefix).
-
Scalar type names are lowercase and js-prefixed: jsdouble.
-
Aggregate type names are JS-prefixed and mixed-case: JSObject.
-
Macros are generally ALL_CAPS and underscored, to call out potential side
effects, multiple uses of a formal argument, etc.
-
Four spaces of indentation per statement nesting level. The files
are space-filled, so adjusting of your tab setting should be unnecessary.
-
DLL entry points have their return type expanded within a PR_PUBLIC_API()
macro call, to get the right Windows secret type qualifiers in the right
places for both 16- and 32-bit builds.
-
Callback functions that might be called from a DLL are similarly macroized
with PR_STATIC_CALLBACK (if the function otherwise would be static to hide
its name) or PR_CALLBACK (this macro takes no type argument; it should
be used after the return type and before the function name).
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. |