js/src/liveconnect/README.html

   1 <!-- ***** BEGIN LICENSE BLOCK *****
   2    - Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3    -
   4    - The contents of this file are subject to the Mozilla Public License Version
   5    - 1.1 (the "License"); you may not use this file except in compliance with
   6    - the License. You may obtain a copy of the License at
   7    - http://www.mozilla.org/MPL/
   8    -
   9    - Software distributed under the License is distributed on an "AS IS" basis,
  10    - WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11    - for the specific language governing rights and limitations under the
  12    - License.
  13    -
  14    - The Original Code is Mozilla Communicator client code, released
  15    - March 31, 1998.
  16    -
  17    - The Initial Developer of the Original Code is
  18    - Netscape Communications Corporation.
  19    - Portions created by the Initial Developer are Copyright (C) 1998-1999
  20    - the Initial Developer. All Rights Reserved.
  21    -
  22    - Contributor(s):
  23    -
  24    - Alternatively, the contents of this file may be used under the terms of
  25    - either of the GNU General Public License Version 2 or later (the "GPL"),
  26    - or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27    - in which case the provisions of the GPL or the LGPL are applicable instead
  28    - of those above. If you wish to allow use of your version of this file only
  29    - under the terms of either the GPL or the LGPL, and not to allow others to
  30    - use your version of this file under the terms of the MPL, indicate your
  31    - decision by deleting the provisions above and replace them with the notice
  32    - and other provisions required by the GPL or the LGPL. If you do not delete
  33    - the provisions above, a recipient may use your version of this file under
  34    - the terms of any one of the MPL, the GPL or the LGPL.
  35    -
  36    - ***** END LICENSE BLOCK ***** -->
  37
  38 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
  39 <html>
  40 <head>
  41    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  42    <meta name="Author" content="Scott Furman">
  43    <meta name="GENERATOR" content="Mozilla/4.5 [en] (WinNT; I) [Netscape]">
  44    <title>README for LiveConnect</title>
  45 </head>
  46 <body>
  47 This is the README file for the JavaScript LiveConnect
  48 Version 3 ("LC3") implementation.
  49 <h2>
  50 Table of Contents</h2>
  51
  52 <blockquote><a href="#Introduction">Introduction</a>
  53 <br><a href="#New_Features">New features</a>
  54 <br><a href="#Compatibility">Compatibility</a>
  55 <br><a href="#Limitations">Limitations/Bugs/To-Do</a>
  56 <br><a href="#Build_conventions">Build conventions</a>
  57 <br><a href="#coding_conventions">Naming and coding conventions</a>
  58 <br><a href="#API">The LiveConnect API</a>
  59 <br><a href="#sample_shell_interaction">Sample LiveConnect shell interactions</a></blockquote>
  60
  61 <h2>
  62 <a NAME="Introduction"></a>Introduction</h2>
  63 <span CLASS=LXRLONGDESC> <span CLASS=LXRSHORTDESC>LiveConnect is a library that
  64 permits JavaScript and Java virtual machines to interoperate.</span> Specifically,
  65 it enables JavaScript to access Java fields, invoke Java methods and enables Java
  66 to access JavaScript object properties and evaluate arbitrary JavaScript.</span>
  67 LiveConnect was originally an integrated feature of both the Netscape Navigator
  68 browser and Netscape's server-side JavaScript. Now, it is a standalone library
  69 that can be embedded within other projects, such as the Mozilla browser. More
  70 information on LiveConnect can be found by <a href="http://developer.netscape.com/find/find.cgi?scope=LiveConnect&browse-category=&ui=sr&chunk-size=&page=1&taxonomy=DevEdge+Online">searching
  71 the index on Netscape's DevEdge site</a>.&nbsp; This README assumes basic familiarity
  72 with <a href="http://lxr.mozilla.org/mozilla/source/js/src/README.html">JSRef</a>,
  73 the reference implementation of JavaScript, and with the LiveConnect technology.
  74 <p>The JSRef project/makefiles (located in another directory) build a library
  75   or DLL containing the JavaScript runtime (compiler, interpreter, decompiler,
  76   garbage collector, atom manager, standard classes).&nbsp; The LiveConnect project/makefiles
  77   build a library that links with both JSRef and any Java Virtual Machine (JVM)
  78   that implements the Java Native Interface (JNI), as specified by JavaSoft.&nbsp;
  79   It then compiles a small "shell" example program and links that with the library
  80   to make an interpreter that can be used interactively and with test scripts.&nbsp;
  81   See the <a href="#sample_shell_interaction">sample shell interactions</a>.
  82 <p><i>Scott Furman, 10/31/98</i>
  83 <h2>
  84 <a NAME="New_Features"></a>New features</h2>
  85 The following features were not available in the versions of LiveConnect that
  86 were integrated with Netscape Navigator versions 4.x and earlier.&nbsp; For information
  87 on LiveConnect version 1, which was used in Navigator versions 3 and 4, and Enterprise
  88 Server 3, see <a href="http://developer.netscape.com/find/find.cgi?scope=LiveConnect&browse-category=&ui=sr&chunk-size=&page=1&taxonomy=DevEdge+Online">Netscape's
  89 DevEdge site</a> or any number of 3rd-party publications.)
  90 <h4> LiveConnect version 3 (8/31/99)</h4>
  91
  92 <ul>
  93   <li> In previous versions of LiveConnect, when more than one overloaded Java
  94     method was compatible with the types of arguments in an invocation from JS,
  95     the choice of Java method was made arbitrarily, by using the first one enumerated
  96     by the Java reflection APIs.&nbsp; Unfortunately, the ordering of methods
  97     when enumerating is not governed by any specification, so differences between
  98     JVM vendors could lead to inconsistencies in LiveConnect behavior.&nbsp; Now,
  99     a <a href="http://www.mozilla.org/js/liveconnect/lc3_method_overloading.html">JVM-independent
 100     set of rules</a> is used to choose among a set of overloaded methods.&nbsp;&nbsp;
 101     Informally, the method with Java parameter types that most&nbsp; closely match
 102     the JavaScript types is chosen.<BR>
 103     <BR>
 104   </li>
 105   <li> The weak correspondence between the JS language typing system and Java's
 106     may result in ambiguity and/or shadowing when resolving among overloaded Java
 107     methods, even when using LC3's improved method overload resolution algorithm
 108     (see above).&nbsp; For example, JS's number type can map to a Java method
 109     argument that has any floating-point or integral types: byte, char, short,
 110     int, long, float, double.&nbsp;&nbsp; If necessary, it is now possible to
 111     bypass the method overload resolution process and explicitly specify the method
 112     to be invoked:</li>
 113   <BR>
 114   <br>
 115   &nbsp;
 116   <ul>
 117     <tt>myPrintMethod = java.io.PrintStream["print(double)"];</tt> <br>
 118     <tt>myPrintMethod(13);</tt>
 119   </ul>
 120   <br>
 121   <li> Static methods can now be invoked using either the class name or a reference
 122     to an instance of the class.&nbsp; (Older versions of LiveConnect allow only
 123     the former.)<BR>
 124     <BR>
 125   </li>
 126   <li> It is no longer necessary to convert Java Strings to JS strings before
 127     using them as the receivers of JS string methods, which is typically done
 128     by appending an empty string to the Java string, e.g.
 129     <BLOCKQUOTE>
 130       <P> <tt>&nbsp;&nbsp;&nbsp; s = new java.lang.String("foo")</tt> // s contains
 131         a Java string<br>
 132         <tt>&nbsp;&nbsp;&nbsp; s = s + "";&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 133         </tt>// s is now a JS string <br>
 134         <tt>&nbsp;&nbsp;&nbsp; m = s.match(/o?/)</tt> </P>
 135     </BLOCKQUOTE>
 136   </li>
 137   <p>The explicit conversion to a JS string is no longer required because <i>java.lang.String</i>
 138     objects are treated as a special case that "inherit" all the methods of JS
 139     strings, i.e. so that the second statement in the example above is now superfluous.<BR>
 140     <BR>
 141   <li> Similarly, JavaArray objects "inherit" the methods of JS's <tt>Array.prototype</tt>,
 142     so it is possible to apply many, though not all, of the JS array utility methods
 143     such as <tt>reverse()</tt> and <tt>join()</tt> to JavaArray objects.<BR>
 144     <BR>
 145   </li>
 146   <li> There is now support for the <tt>instanceof</tt> and <tt>in</tt> operators.&nbsp;
 147     These operators are currently proposed for inclusion in the ECMA-2 standard.<BR>
 148     <BR>
 149   </li>
 150   <li> LiveConnect has been extended to take advantage of JavaScript exceptions,
 151     a language feature that debuted in JavaScript 1.4.&nbsp; Now, when JavaScript
 152     calls into Java, any Java exceptions are converted to JS exceptions which
 153     can be caught using JS try-catch statements.&nbsp; Similarly, JS exceptions
 154     are propagated to Java wrapped in an instance of <i>netscape.javascript.JSException</i>.<BR>
 155     <BR>
 156   </li>
 157   <li>JavaScript Array objects can now be passed to Java methods that expect a
 158     Java array as an argument. <BR>
 159     LiveConnect will create a new Java array of the appropriate type with a length
 160     equal to that of the JS Array object. Each element of the Java array is filled
 161     in by converting the corresponding element of the JS array, including undefined
 162     elements, to an equivalent Java value. Note: Since the contents of the JS
 163     array are copied, side-effects made by the invoked Java method to the Java
 164     array will not be reflected in the JS array argument. </li>
 165 </ul>
 166
 167 <h4>
 168 LiveConnect version 2 (7/31/98)</h4>
 169
 170 <blockquote>
 171   <li> The Java methods of <i>java.lang.Object</i> are now invokeable methods
 172     of <tt><font size=+1>JavaArray</font></tt> objects, matching the behavior
 173     of arrays when accessed from Java<i>.</i>&nbsp; (Java arrays are a subclass
 174     of <i>java.lang.Object</i>.) For example, Java's <tt>getClass()</tt> and <tt>hashCode()</tt>
 175     methods can now be called on <tt>JavaArray</tt> objects.&nbsp; (In prior versions
 176     of LiveConnect, the methods of <i>java.lang.Object</i> were only inherited
 177     by non-array Java objects.)</li>
 178
 179   <p>Note that this change has caused the string representation of JavaArray objects
 180     to change.&nbsp; Previously, the JavaArray toString() method always printed
 181     "<tt><font size=+1>[object JavaArray]"</font></tt> for all <tt>JavaArray</tt>'s.&nbsp;
 182     Now, the Java <tt>java.lang.Object.toString()</tt> method is called to convert
 183     JavaArray objects to strings, just as with other, non-array Java objects that
 184     are accessible via LiveConnect. <tt>java.lang.Object.toString()</tt>is defined
 185     in the <i>Java Language Specification</i> to return the value of the following
 186     expression:
 187   <p><tt><font size=-1>getClass().getName() + '@' + Integer.toHexString(hashCode())</font></tt><BR>
 188     <br>
 189     &nbsp;
 190   <li> A one-character string is now an acceptable match for an argument to a
 191     Java method of type <tt>char</tt>.&nbsp; (In earlier versions of LiveConnect,
 192     the only acceptable match for a <tt>char</tt> had to be a JavaScript value
 193     that was convertible to a number.)&nbsp; For example, the following is now
 194     possible:</li>
 195
 196   <p><tt><font size=-1>c = new java.lang.Character("F")</font></tt><BR>
 197     <br>
 198     &nbsp;
 199 <li>
 200 A JavaClass object is now an acceptable match for an argument to a Java
 201 method of type <i>java.lang.Class</i>.&nbsp; For example, you can now write:</li>
 202
 203 <p><tt><font size=-1>java.lang.reflect.Array.newInstance(java.lang.String,
 204 3)</font></tt>
 205 <p>instead of the more verbose:
 206   <p><tt><font size=-1>jls = java.lang.Class.forName("java.lang.String")</font></tt>
 207     <br>
 208     <tt><font size=-1>java.lang.reflect.Array.newInstance(jls, 3)</font></tt>
 209   <p><br>
 210     &nbsp;
 211 </blockquote>
 212
 213 <h2>
 214 <a NAME="Compatibility"></a>Compatibility</h2>
 215 Unlike this standalone/component release, all previous versions of LiveConnect
 216 appeared only as an integrated feature of Netscape Navigator or the Enterprise
 217 Server.&nbsp; The variants of LiveConnect that appeared in Navigator versions
 218 3.x and 4.x all behave much the same, modulo bugs.&nbsp; For brevity we refer
 219 to this classic version of LiveConnect as "LC1" (LiveConnect version 1) and this
 220 most recent release as "LC3".&nbsp; With a few exceptions LC3 provides a superset
 221 of LC1 features. (There was an intermediate LiveConnect release known as "LC2"
 222 in 7/98, but it was not used in any products.)
 223 <ul>
 224   <li> As in LC1, JavaScript objects appear to Java as instances of <i>netscape.javascript.JSObject</i>.&nbsp;
 225     In LC1, two <i>JSObject</i>'s could be tested for equality, i.e. to see if
 226     they refer to the same instance, by using the `==' operator.&nbsp; Instead,
 227     developers must now use the <tt>equals()</tt>method of <i>netscape.javascript.JSObject</i>
 228     for comparison, a method that overrides <tt>java.lang.Object.equals()</tt>.&nbsp;
 229     Note that using <tt>equals()</tt> instead of `==' will work the same in all
 230     versions of LiveConnect, including LC3</li>
 231   <p>[It is not possible to replicate the identity behavior of the `==' operator
 232     that LC1 provides without the use of "weak" references, i.e. references that
 233     do not contribute to making a Java object reachable for purposes of garbage
 234     collection, but which nonetheless allow reference to an object as long as
 235     it is reachable by other means.&nbsp; The use of weak references is not portable,
 236     however.&nbsp; It is not part of the JNI or JDK 1.1 and it is not provided
 237     on all JVMs.&nbsp; The JDK1.2 release includes standard support for weak references.]<BR>
 238     <br>
 239     &nbsp;
 240   <li> It's possible that, in a set of overloaded Java methods, more than one
 241     method is compatible with the types of the actual arguments in a call from
 242     JavaScript to Java via LiveConnect.&nbsp; LC1 and LC2 resolved these ambiguities
 243     in a simplistic manner, by simply invoking whatever method was enumerated
 244     first by the JVM.&nbsp; The enumeration order of reflected methods using <i>java.lang.reflect</i>&nbsp;
 245     is not specified by Sun and may differ among vendor's JVMs, i.e. enumeration
 246     could be in order of classfile appearance, hashtable order, etc.&nbsp; Hence,
 247     the Java method chosen when there is more than one compatible method may vary
 248     depending on the JVM.&nbsp; With the Netscape and Sun JVMs, it is possible
 249     to change the behavior of an LC1/LC2 program by changing the order that Java
 250     methods appear in a source file, thus changing the method enumeration order.</li>
 251   <p>In LC3, a new method overload resolution algorithm is used.&nbsp; Informally,
 252     the method with Java parameter types that most&nbsp; closely match the JavaScript
 253     types is chosen.&nbsp; You can read all the gorey details in the <a href="http://www.mozilla.org/js/liveconnect/lc3_method_overloading.html">spec</a>.<BR>
 254     <br>
 255     &nbsp;
 256   <li> There are several minor changes in error handling to make LiveConnect more
 257     conformant to ECMAScript.&nbsp; These include, for example, making any attempt
 258     to delete JavaObject, JavaClass or JavaPackage properties fail silently, rather
 259     than causing an error.&nbsp; Also, some error messages have been changed to
 260     be more informative.&nbsp; These changes should generally be backward-compatible
 261     with LC1 because few programs that use LiveConnect will depend on the exact
 262     behavior of LiveConnect when handling errors.</li>
 263 </ul>
 264
 265 <h2> <a NAME="Limitations"></a>Limitations/Bugs/To-Do<BR>
 266 </h2>
 267 <ul>
 268   <li> The efficiency of calling Java methods leaves something to be desired,
 269     due to the convoluted nature of implementing native methods for JS.&nbsp;
 270     JS_CloneFunctionObject() is called for every Java method invocation and the
 271     inability to store private data in a JSFunction object requires that the method
 272     table be searched twice instead of once for every invocation.<BR>
 273     <BR>
 274   </li>
 275   <li> When Java objects are referenced from JS, they are entered into a hash
 276     table, so as to ensure that the same JS Object wrapper is used every time
 277     a particular Java object is reflected into JS.&nbsp; In this way, the behavior
 278     of the JS '==' and '===' operators are preserved.&nbsp; Unfortunately, the
 279     hash table may grow quite large (objects are only removed from the hash table
 280     when finalized).&nbsp; In thread-safe systems, the hash table must be locked
 281     when accessed, leading to slow performance. One alternate solution would be
 282     to make it possible to overload JS's equality-test operators, so that the
 283     hash table would no longer be required.<BR>
 284     <BR>
 285   </li>
 286   <li> Initially, JavaClassDescriptor objectswere reference-counted to permit
 287     free'ing of unused descriptors.&nbsp; However, it's relatively common to develop
 288     cycles in the graph of JavaClassDescriptors, which leads to unused JavaClassDescriptors
 289     that have non-zero reference counts. For that reason, JavaClassDescriptors
 290     are not free'ed until JSJ_Shutdown().&nbsp; Luckily, the amount of memory
 291     used by JavaClassDescriptors tends to be relatively small.<BR>
 292     <BR>
 293   </li>
 294   <li> The LiveConnect API is designed to allow multiple JVMs to be used simultaneously
 295     in the same executable (although each JSContext is limited to interaction
 296     with at most one JVM).&nbsp; However, the API is not fully implemented.&nbsp;
 297     For example, many global variables will need to become members of the JSJavaVM
 298     struct so that they are stored on a per-JVM basis.<BR>
 299     <BR>
 300   </li>
 301   <li> Java and JavaScript use independent garbage collection systems. A reference
 302     between the two worlds must, therefore, take the form of a GC root. It's possible
 303     to create uncollectable objects when cyclic graphs cross the boundary between
 304     JS and Java, e.g. a JS object that refers to a Java object that refers back
 305     to the original JS object. There is no simple solution to this dual-GC problem.
 306     Luckily, such cyclic object graphs are extremely rare. </li>
 307 </ul>
 308
 309 <h2>
 310 <a NAME="Build_conventions"></a>Build conventions</h2>
 311 <P>The following directions are for building the standalone version of LiveConnect.
 312   To build the version that's used in the Mozilla browser, see the <A HREF="http://www.mozilla.org/docs/">Mozilla
 313   build documentation</A>.</P>
 314 <P>On all platforms, you must update your JVM's <tt>CLASSPATH</tt> to point to
 315   the <tt>js/src/liveconnect/classes</tt> subdirectory.&nbsp; If you do not, LiveConnect
 316   will still operate but with the limitation that JS objects may not be passed
 317   as arguments of Java methods and it will not be possible to call from Java into
 318   JavaScript, i.e. the <i>netscape.javascript.JSObject</i> class will be inaccessible.&nbsp;
 319   Another downside of operating without these classes is that Java error messages
 320   will not include a Java stack trace, when one is available.&nbsp; If your <tt>CLASSPATH</tt>
 321   is set improperly, you will see a message like, "<tt>initialization error: Can't
 322   load class netscape/javascript/JSObject</tt>" when starting a LiveConnect debug
 323   build. </P>
 324 <p>By default, all platforms build a version of LiveConnect that is <i>not</i>
 325   threadsafe.&nbsp; If you require thread-safety, you must also populate the <tt>mozilla/dist</tt>
 326   directory with <a href="http://www.mozilla.org/docs/tplist/catCode/nsprdesc.htm">NSPR</a>
 327   headers and libraries.&nbsp; (NSPR implements a portable threading library,
 328   among other things.&nbsp; The source is downloadable via <a href="http://www.mozilla.org/cvs.html">CVS</a>
 329   from <tt><a href="http://lxr.mozilla.org/mozilla/source/nsprpub">mozilla/nsprpub</a></tt>.)&nbsp;
 330   Next, you must define <tt>JS_THREADSAFE</tt> when building LiveConnect, either
 331   on the command-line (gmake/nmake) or in a universal header file.&nbsp; Note
 332   that JSRef must also be built with <tt>JS_THREADSAFE</tt>.
 333 <p>One important note about building on Windows: There are two independent build
 334   systems (in addition to the Mozilla browser build system). One of them uses
 335   the IDE project files and the other uses gmake and makefiles. The former will
 336   be preferred by most for debugging and the latter is more complete, since it
 337   builds the necessary Java classes in addition to compiling the LiveConnect C
 338   code.
 339 <ul><b>Windows</b>
 340 <ul>
 341 <li>
 342 Build the JS runtime and interpreter, <tt>js32.dll</tt>, by using the
 343 <a href="http://lxr.mozilla.org/mozilla/source/js/src/README.html#Build">normal
 344 JSRef build procedure</a>.</li>    <li> Set the <tt>JDK</tt> environment variable to point to the top-level JDK directory,
 345       e.g. <tt>D:\jdk1.1.5</tt>.&nbsp; This is used to establish paths for header
 346       file inclusion, linking and execution.&nbsp; If you are not using Sun's
 347       JVM, the project files may require manual tweaking to set these paths correctly.</li>
 348
 349     <li> Use MSVC 5 or MSVC 6 with the <tt>LiveConnectShell.dsw</tt> project file.&nbsp;
 350       <font color="#993300">NOTE: makefile.win is an nmake file used only for
 351       building the JS-engine in the Mozilla browser.&nbsp; Don't attempt to use
 352       it to build the standalone JS-engine.</font></li>
 353
 354 <li>
 355 The output files (DLLs and executables) are placed in either the <tt>js\src\liveconnect\Debug</tt>
 356 or the <tt>js\src\liveconnect\Release</tt> directory.</li>
 357
 358 <li>
 359 The LiveConnect-enabled shell is named <tt>lcshell.exe</tt> and appears
 360 in the output directory.</li>
 361
 362 <li>
 363 You must have the JVM DLL in your <tt><font size=+1>PATH</font></tt> environment
 364 variable in order to run.&nbsp; If you are using the Sun JDK, the DLL appears
 365 in the JDK's bin directory, e.g. <tt>D:\jdk1.1.5\bin\javai_g.dll</tt>.</li>
 366
 367 <li>
 368 Use any Java compiler to compile the java source files in the <tt>js\src\liveconnect\classes\netscape\javascript</tt>
 369 directory.</li>
 370
 371     <li> Update your JVM's <tt>CLASSPATH</tt> to point to the <tt>js\src\liveconnect\classes</tt>
 372       subdirectory.&nbsp; (See above)<br>
 373 <BR></li>
 374 </ul>
 375 <b>Mac OS</b>
 376 <ul>
 377 <li>
 378 Using CodeWarrior Pro 3 is recommended, though the project files will probably
 379 also work with CodeWarrior Pro 4.</li>
 380
 381 <li>
 382 Install Apple's JVM, MRJ 2.0 (or later), and the <a href="ftp://dev.apple.com/devworld/Java/MRJSDK2.0.1EarlyAccess4.hqx">MRJ
 383 SDK v2.0.1ea4</a>.&nbsp; Note: You do not need to install MRJ if you are
 384 running a recent version of MacOS 8, since it is shipped with the OS.</li>
 385
 386 <li>
 387 Copy the folders <tt>CIncludes</tt> &amp; <tt>Libraries</tt> from the SDK's
 388 <tt>Interfaces&amp;Libraries</tt> directory to <tt>js:src:liveconnect:macbuild:JavaSession</tt>.</li>
 389
 390 <li>
 391 Build the LiveConnect test application, <tt>LiveConnectShell</tt>, with
 392 <tt>js:src:liveconnect:macbuild:LiveConnectShell.mcp</tt>.</li>
 393
 394 <li>
 395 Build <tt>liveconnect.jar</tt> with <tt>js:src:liveconnect:macbuild:LiveConnect.mcp</tt>.</li>
 396
 397 <li>
 398 Make an alias to <tt>liveconnect.jar</tt> and place it in "<tt>{SystemFolder}Extensions:MRJ
 399 Libraries:MRJClasses</tt>".<br>
 400 <BR></li>
 401 </ul>
 402   <b>Unix</b> (also works on Windows)
 403   <ul>
 404     <li> <font color="#000000">Use '<tt>gmake -f Makefile.ref</tt>' to build.
 405       To compile optimized code, pass <tt>BUILD_OPT=1</tt> on the gmake command
 406       line or preset it in the environment or <tt>Makefile.ref</tt>.&nbsp; </font><font color="#990000">NOTE:
 407       Do not attempt to use <tt>Makefile</tt> to build.&nbsp; This file is used
 408       only for building LiveConnect in the Mozilla browser.</font></li>
 409     <li> <font color="#000000">Each platform on which LiveConnect is built must
 410       have a *.mk configuration file in the <tt>js/src/liveconnect/config</tt>
 411       directory.&nbsp; The configuration file specifies the JVM headers/libraries
 412       used and allows for customization of command-line options.&nbsp; To date,
 413       the build system has been tested on Solaris, AIX, HP/UX, OSF, IRIX, x86
 414       Linux and Windows NT. Most platforms will work with either the vendor compiler
 415       or gcc.</font></li>
 416     <li>Update your JVM's <tt><font size=+1>CLASSPATH</font></tt> to point to
 417       the <tt>js/src/liveconnect/classes</tt> subdirectory.&nbsp; (See above)</li>
 418   </ul>
 419 </ul>
 420
 421 <h2>
 422 <a NAME="coding_conventions"></a>Naming and coding conventions:</h2>
 423
 424 <ul>
 425 <li>
 426 Public function names begin with JSJ_ followed by capitalized "intercaps",&nbsp;
 427 e.g. JSJ_ConnectToJavaVM.</li>
 428
 429 <li>
 430 Extern but library-private function names use a jsj_ prefix and mixed case,
 431 e.g. jsj_LookupSymbol.</li>
 432
 433 <li>
 434 Most static function names have unprefixed, underscore-separated names:
 435 get_char.</li>
 436
 437 <li>
 438 But static native methods of JS objects have intercaps names, e.g., JavaObject_getProperty().</li>
 439
 440 <li>
 441 And library-private and static data use underscores, not intercaps (but
 442 library-private data do use a js_ prefix).</li>
 443
 444 <li>
 445 Scalar type names are lowercase and js-prefixed: jsdouble.</li>
 446
 447 <li>
 448 Aggregate type names are JS-prefixed and mixed-case: JSObject.</li>
 449
 450 <li>
 451 Macros are generally ALL_CAPS and underscored, to call out potential side
 452 effects, multiple uses of a formal argument, etc.</li>
 453
 454 <li>
 455 Four spaces of indentation per statement nesting level.&nbsp; The files
 456 are space-filled, so adjusting of your tab setting should be unnecessary.</li>
 457
 458 <li>
 459 I don't bow down to the ancient "80 columns per line" gods, since most
 460 of us are not using vt100's to read source code.&nbsp; My rule of thumb
 461 is to use no more than 95 columns per line, but exceptions are made to
 462 format tables or table-like code.</li>
 463
 464 <li>
 465 DLL entry points have their return type expanded within a JS_EXPORT_API()&nbsp;
 466 macro call, to get the right Windows secret type qualifiers in the right
 467 places for both 16- and 32-bit builds.</li>
 468
 469 <h2>
 470 <a NAME="API"></a>The LiveConnect API</h2>
 471 All public LiveConnect entry points and callbacks are documented in
 472 <A HREF=http://lxr.mozilla.org/mozilla/source/js/src/liveconnect/jsjava.h>jsjava.h</A>,
 473 the header file that exports those functions.
 474 <br>&nbsp;
 475 <h2>
 476 <a NAME="File_walkthrough"></a>File walk-through</h2>
 477 &nbsp;
 478 <table BORDER=3 CELLSPACING=0 CELLPADDING=4 >
 479 <tr>
 480 <td>jsjava.h</td>
 481
 482 <td>LiveConnect's only public header file.&nbsp; Defines all public API
 483 entry points, callbacks and types.&nbsp;</td>
 484 </tr>
 485
 486 <tr>
 487 <td>jsj_private.h</td>
 488
 489 <td>LiveConnect internal header file for intra-module sharing of functions
 490 and types.</td>
 491 </tr>
 492
 493 <tr>
 494 <td>jsj.c</td>
 495
 496 <td>Public LiveConnect API entry points and initialization code. Handling
 497 of multiple threads and multiple JVMs.</td>
 498 </tr>
 499
 500 <tr>
 501 <td>jsj_array.c</td>
 502
 503 <td>Read and write elements of a Java array, performing needed conversions
 504 to/from JS types.</td>
 505 </tr>
 506
 507 <tr>
 508 <td>jsj_class.c</td>
 509
 510 <td>Construct and manipulate JavaClassDescriptor structs, which are the
 511 native representation for Java classes.&nbsp; JavaClassDescriptors are
 512 used to describe the methods and fields of a class, including their type
 513 signatures, and include a reference to the peer <i>java.lang.Class</i>
 514 object.&nbsp; Since each Java object has a class, there is a JavaClassDescriptor
 515 associated with the JavaScript reflection of each Java Object.</td>
 516 </tr>
 517
 518 <tr>
 519 <td>jsj_convert.c</td>
 520
 521 <td>Convert between Java and JavaScript values of all types, which may
 522 require calling routines in other files to wrap JS objects as Java objects
 523 and vice-versa.</td>
 524 </tr>
 525
 526 <tr>
 527 <td>jsj_field.c</td>
 528
 529 <td>Reflect Java fields as properties of JavaObject objects and implement
 530 getter/setter access to those fields.</td>
 531 </tr>
 532
 533 <tr>
 534 <td>jsj_JavaArray.c</td>
 535
 536 <td>Implementation of the JavaScript JavaArray class.&nbsp; Instances of
 537 JavaArray are used to reflect Java arrays.</td>
 538 </tr>
 539
 540 <tr>
 541 <td>jsj_JavaClass.c</td>
 542
 543 <td>Implementation of the JavaScript JavaClass class.&nbsp;&nbsp; Instances
 544 of JavaClass are used to reflect Java classes.</td>
 545 </tr>
 546
 547 <tr>
 548 <td>jsj_JavaObject.c</td>
 549
 550 <td>Implementation of the JavaScript JavaObject class.&nbsp;&nbsp; Instances
 551 of JavaObject are used to reflect Java objects, except for Java arrays,
 552 although some of the code in this file is used by the JavaArray code.</td>
 553 </tr>
 554
 555 <tr>
 556 <td>jsj_JavaMember.c</td>
 557
 558 <td>Implementation of the JavaScript JavaMember class.&nbsp; JavaMember's
 559 are a strange beast required only to handle the special case of a public
 560 field and a public method that appear in the same Java class and which
 561 have the same name.</td>
 562 </tr>
 563
 564 <tr>
 565 <td>jsj_JavaPackage.c</td>
 566
 567 <td>Implementation of the JavaScript JavaPackage class.&nbsp;&nbsp; Instances
 568 of JavaPackage are used to reflect Java packages.&nbsp; The JS properties
 569 of a JavaPackage are either nested JavaPackage objects or a JavaClass object.</td>
 570 </tr>
 571
 572 <tr>
 573 <td>jsj_JSObject.c</td>
 574
 575 <td>Implementation of the native methods for the&nbsp; <i>netscape.javascript.JSObject</i>
 576 Java class, which are used for calling into JavaScript from Java.&nbsp;
 577 It also contains the code that wraps JS objects as instances of&nbsp; <i>netscape.javascript.JSObject
 578 </i>and
 579 the code that handles propagation of exceptions both into and out of Java.</td>
 580 </tr>
 581
 582 <tr>
 583 <td>jsj_method.c</td>
 584
 585 <td>Reflect Java methods as properties of JavaObject objects and make it
 586 possible to invoke those methods.&nbsp; Includes overloaded method resolution
 587 and argument/return-value conversion code.</td>
 588 </tr>
 589
 590 <tr>
 591 <td>jsj_utils.c</td>
 592
 593 <td>Low-level utility code for reporting errors, etc.</td>
 594 </tr>
 595 </table>
 596
 597 <h2>
 598 <a NAME="sample_shell_interaction"></a>Sample LiveConnect shell interactions</h2>
 599
 600 <h4>
 601 Java packages, classes and constructors</h4>
 602 <tt>js> java</tt>
 603 <br><tt>[JavaPackage java]</tt>
 604 <br><tt>js> awt = java.awt</tt>
 605 <br><tt>[JavaPackage java.awt]</tt>
 606 <br><tt>js> Rectangle = awt.Rectangle</tt>
 607 <br><tt>[JavaClass java.awt.Rectangle]</tt>
 608 <h4>
 609 Java instance fields and methods</h4>
 610 <tt>js> r = new java.awt.Rectangle(34, 23)</tt>
 611 <br><tt>java.awt.Rectangle[x=0,y=0,width=34,height=23]</tt>
 612 <br><tt>js> r.width - r.height</tt>
 613 <br><tt>11</tt>
 614 <br><tt>js> r.x = 7; r.y = 4</tt>
 615 <br><tt>4</tt>
 616 <br><tt>js> r</tt>
 617 <br><tt>java.awt.Rectangle[x=7,y=4,width=34,height=23]</tt>
 618 <br><tt>js> r.grow(3)</tt>
 619 <br><tt>There is no Java method java.awt.Rectangle.grow that matches JavaScript
 620 argument types (number).</tt>
 621 <br><tt>Candidate methods with the same name are:</tt>
 622 <br><tt>&nbsp;&nbsp; void grow(int, int)</tt>
 623 <p><tt>js> r.grow(3, 3)</tt>
 624 <br><tt>js> r</tt>
 625 <br><tt>java.awt.Rectangle[x=4,y=1,width=40,height=29]</tt>
 626 <h4>
 627 Java arrays</h4>
 628 <tt>js> s = new java.lang.String("mastiff")</tt>
 629 <br><tt>mastiff</tt>
 630 <br><tt>js> c = s.toCharArray()</tt>
 631 <br><tt>[C@298e9b</tt>
 632 <br><tt>js> c[0] = "b"; c[4] = "a"; c[5] = "r"; c[6] = "d"</tt>
 633 <br><tt>d</tt>
 634 <br><tt>js> s2 = new java.lang.String(c)</tt>
 635 <br><tt>bastard</tt>
 636 <h4>
 637 Java static fields and methods</h4>
 638 <tt>js> java.lang.reflect.Modifier.ABSTRACT</tt>
 639 <br><tt>1024</tt>
 640 <br><tt>js> java.lang.Math.sin(3) + 2</tt>
 641 <br><tt>2.1411200080598674</tt>
 642 <h4>
 643 Explicit resolution of overloaded Java methods</h4>
 644 <tt>js> x = "23"</tt>
 645 <br><tt>23</tt>
 646 <br><tt>js> java.lang.Math.abs(x)</tt>
 647 <br><tt>The choice of static Java method java.lang.Math.abs matching JavaScript
 648 argument types (string) is ambiguous.</tt>
 649 <br><tt>Candidate methods are:</tt>
 650 <br><tt>&nbsp;&nbsp; long abs(long)</tt>
 651 <br><tt>&nbsp;&nbsp; float abs(float)</tt>
 652 <br><tt>&nbsp;&nbsp; double abs(double)</tt>
 653 <br><tt>&nbsp;&nbsp; int abs(int)</tt>
 654 <br><tt>js> abs = java.lang.Math["abs(int)"]</tt>
 655 <p><tt>function abs(int)() {</tt>
 656 <br><tt>&nbsp;&nbsp;&nbsp; [native code]</tt>
 657 <br><tt>}</tt>
 658 <p><tt>js> abs(x)</tt>
 659 <br><tt>23</tt>
 660 <h4>
 661 Public Method/field enumeration</h4>
 662 <tt>js> out = java.lang.System.out</tt>
 663 <br><tt>java.io.PrintStream@2980f5</tt>
 664 <br><tt>js> for (m in out) print(m)</tt>
 665 <br><tt>println</tt>
 666 <br><tt>print</tt>
 667 <br><tt>checkError</tt>
 668 <br><tt>close</tt>
 669 <br><tt>flush</tt>
 670 <br><tt>write</tt>
 671 <br><tt>wait</tt>
 672 <br><tt>notifyAll</tt>
 673 <br><tt>notify</tt>
 674 <br><tt>toString</tt>
 675 <br><tt>equals</tt>
 676 <br><tt>hashCode</tt>
 677 <br><tt>getClass</tt>
 678 <br><tt>js> for (m in java.lang.String) print(m)</tt>
 679 <br><tt>copyValueOf</tt>
 680 <br><tt>valueOf</tt>
 681 <h4>
 682 'instanceof' and 'in' operators</h4>
 683 <tt>js> s = new java.lang.String("foop")</tt>
 684 <br><tt>foop</tt>
 685 <br><tt>js> s instanceof java.lang.Class</tt>
 686 <br><tt>false</tt>
 687 <br><tt>js> s instanceof java.lang.Object</tt>
 688 <br><tt>true</tt>
 689 <br><tt>js> "valueOf" in s</tt>
 690 <br><tt>true</tt>
 691 <br><tt>js> "NoSuchThing" in s</tt>
 692 <br><tt>false</tt>
 693 <h4>
 694 Applying JavaScript string methods to Java strings</h4>
 695 <tt>js> s = new java.lang.String("The rain in Spain falls mainly on my
 696 head.")</tt>
 697 <br><tt>The rain in Spain falls mainly on my head.</tt>
 698 <br><tt>js> s.match(/Spain.*my/)</tt>
 699 <br><tt>Spain falls mainly on my</tt>
 700 <h4>
 701 Applying JavaScript array methods to Java arrays</h4>
 702 <tt>js> s = new java.lang.String("JavaScript")</tt>
 703 <br><tt>JavaScript</tt>
 704 <br><tt>js> c = s.toCharArray()</tt>
 705 <br><tt>[C@298aef</tt>
 706 <br><tt>js> c.reverse()</tt>
 707 <br><tt>[C@298aef</tt>
 708 <br><tt>js> new java.lang.String(c)</tt>
 709 <br><tt>tpircSavaJ</tt>
 710 <br>&nbsp;
 711 </body>
 712 </html>