netscape.javascript.JSObject and passed to Java.
When a JavaScript object is sent to Java, the runtime engine creates a Java wrapper of type JSObject; when a JSObject is sent from Java to JavaScript, the runtime engine unwraps it to its original JavaScript object type. The JSObject class provides an interface for invoking JavaScript methods and examining JavaScript properties.
Table 9.1 The LiveConnect Objects
| Object |
Description
|
|
| A wrapped Java object, accessed from within JavaScript code.
| |
|---|
NOTE: Because Java is a strongly typed language and JavaScript is weakly typed, the JavaScript runtime engine converts argument values into the appropriate data types for the other language when you use LiveConnect. See "Data Type Conversions" on page 147 for complete information.In some ways, the existence of the LiveConnect objects is transparent, because you interact with Java in a fairly intuitive way. For example, you can create a Java
String object and assign it to the JavaScript variable myString by using the new operator with the Java constructor, as follows:
var myString = new java.lang.String("Hello world")
In the previous example, the variable myString is a JavaObject because it holds an instance of the Java object String. As a JavaObject, myString has access to the public instance methods of java.lang.String and its superclass, java.lang.Object. These Java methods are available in JavaScript as methods of the JavaObject, and you can call them as follows:
myString.length() // returns 11
java, sun, or netscape packages, you access it with the Packages object. For example, suppose the Redwood corporation uses a Java package called redwood to contain various Java classes that it implements. To create an instance of the HelloWorld class in redwood, you access the constructor of the class as follows:
var red = new Packages.redwood.HelloWorld()You can also access classes in the default package (that is, classes that don't explicitly name a package). For example, if the HelloWorld class is directly in the
CLASSPATH and not in a package, you can access it as follows:
var red = new Packages.HelloWorld()The LiveConnect
java, sun, and netscape objects provide shortcuts for commonly used Java packages. For example, you can use the following:
var myString = new java.lang.String("Hello world")
instead of the longer version:
var myString = new Packages.java.lang.String("Hello world")
JavaArray. For example, the following code creates the JavaArray x with ten elements of type int:
x = java.lang.reflect.Array.newInstance(java.lang.Integer, 10)Like the JavaScript
Array object, JavaArray has a length property which returns the number of elements in the array. Unlike Array.length, JavaArray.length is a read-only property, because the number of elements in a Java array are fixed at the time of creation.
JavaPackage and JavaClass objects. In the earlier example about the Redwood corporation, for example, the reference Packages.redwood is a JavaPackage object. Similarly, a reference such as java.lang.String is a JavaClass object.
Most of the time, you don't have to worry about the JavaPackage and JavaClass objects--you just work with Java packages and classes, and LiveConnect creates these objects transparently.
In JavaScript 1.3 and earlier, JavaClass objects are not automatically converted to instances of java.lang.Class when you pass them as parameters to Java methods--you must create a wrapper around an instance of java.lang.Class. In the following example, the forName method creates a wrapper object theClass, which is then passed to the newInstance method to create an array.
// JavaScript 1.3In JavaScript 1.4 and later, you can pass a
theClass = java.lang.Class.forName("java.lang.String")
theArray = java.lang.reflect.Array.newInstance(theClass, 5)
JavaClass object directly to a method, as shown in the following example:
// JavaScript 1.4
theArray = java.lang.reflect.Array.newInstance(java.lang.String, 5)
char. For example, you can pass the string "H" to the Character constructor as follows:
c = new java.lang.Character("H")
In JavaScript 1.3 and earlier, you must pass such methods an integer which corresponds to the Unicode value of the character. For example, the following code also assigns the value "H" to the variable c:
c = new java.lang.Character(72)
try...catch statement.
For example, suppose you are using the Java forName method to assign the name of a Java class to a variable called theClass. The forName method throws an exception if the value you pass it does not evaluate to the name of a Java class. Place the forName assignment statement in a try block to handle the exception, as follows:
function getClass(javaClassName) {
try {
var theClass = java.lang.Class.forName(javaClassName);
} catch (e) {
return ("The Java exception is " + e);
}
return theClass
}
In this example, if javaClassName evaluates to a legal class name, such as "java.lang.String", the assignment succeeds. If javaClassName evaluates to an invalid class name, such as "String", the getClass function catches the exception and returns something similar to the following:
The Java exception is java.lang.ClassNotFoundException: StringSee "Exception Handling Statements" on page 81 for more information about JavaScript exceptions.
netscape.javascript package into your Java file. This package defines the following classes:
netscape.javascript.JSObject allows Java code to access JavaScript methods and properties.netscape.javascript.JSException allows Java code to handle JavaScript errors.CLASSPATH of the JDK compiler in either of the following ways:
CLASSPATH environment variable to specify the path and name of .jar or .zip file.-classpath command line parameter.java40.jar file in the Program\Java\Classes directory beneath the Navigator directory. You can specify an environment variable in Windows NT by double-clicking the System icon in the Control Panel and creating a user environment variable called CLASSPATH with a value similar to the following:
D:\Navigator\Program\Java\Classes\java40.jarSee the Sun JDK documentation for more information about
CLASSPATH.
NOTE: Because Java is a strongly typed language and JavaScript is weakly typed, the JavaScript runtime engine converts argument values into the appropriate data types for the other language when you use LiveConnect. See "Data Type Conversions" on page 147 for complete information.
netscape.javascript.JSObject. When you call a method in your Java code, you can pass it a JavaScript object as one of its argument. To do so, you must define the corresponding formal parameter of the method to be of type JSObject.
Also, any time you use JavaScript objects in your Java code, you should put the call to the JavaScript object inside a try...catch statement which handles exceptions of type netscape.javascript.JSException. This allows your Java code to handle errors in JavaScript code execution which appear in Java as exceptions of type JSException.
JavaDog. As shown in the following code, the JavaDog constructor takes the JavaScript object jsDog, which is defined as type JSObject, as an argument:
import netscape.javascript.*;Notice that the
public class JavaDog
{
public String dogBreed;
public String dogColor;
public String dogSex;
// define the class constructor
public JavaDog(JSObject jsDog)
{
// use try...catch to handle JSExceptions here
this.dogBreed = (String)jsDog.getMember("breed");
this.dogColor = (String)jsDog.getMember("color");
this.dogSex = (String)jsDog.getMember("sex");
}
}
getMember method of JSObject is used to access the properties of the JavaScript object. The previous example uses getMember to assign the value of the JavaScript property jsDog.breed to the Java data member JavaDog.dogBreed.
NOTE: A more realistic example would place the call toTo get a better sense of howgetMemberinside atry...catchstatement to handle errors of typeJSException. See "Handling JavaScript Exceptions in Java" on page 144 for more information.
getMember works, look at the definition of the custom JavaScript object Dog:
function Dog(breed,color,sex) {
this.breed = breed
this.color = color
this.sex = sex
}
You can create a JavaScript instance of Dog called gabby as follows:
gabby = new Dog("lab","chocolate","female")
If you evaluate gabby.color, you can see that it has the value "chocolate". Now suppose you create an instance of JavaDog in your JavaScript code by passing the gabby object to the constructor as follows:
javaDog = new Packages.JavaDog(gabby)If you evaluate
javaDog.dogColor, you can see that it also has the value "chocolate", because the getMember method in the Java constructor assigns dogColor the value of gabby.color.
try...catch statement. The JavaScript exception is available to your Java code as an instance of netscape.javascript.JSException.
JSException is a Java wrapper around any exception type thrown by JavaScript, similar to the way that instances of JSObject are wrappers for JavaScript objects. Use JSException when you are evaluating JavaScript code in Java.
When you are evaluating JavaScript code in Java, the following situations can cause run-time errors:
throw statement.eTest evaluates the string jsCode that you pass to it. You can respond to either type of run-time error the evaluation causes by implementing an exception handler such as the following:
import netscape.javascript.JSObject;In this example, the code in the
import netscape.javascript.JSException;
public class eTest {
public static Object doit(JSObject obj, String jsCode) {
try {
obj.eval(jsCode);
} catch (JSException e) {
if (e.getWrappedException()==null)
return e;
return e.getWrappedException();
}
return null;
}
}
try block attempts to evaluate the string jsCode that you pass to it. Let's say you pass the string "myFunction()" as the value of jsCode. If myFunction is not defined as a JavaScript function, the JavaScript interpreter cannot evaluate jsCode. The interpreter generates an error message, the Java handler catches the message, and the doit method returns an instance of netscape.javascript.JSException.
However, suppose myFunction is defined in JavaScript as follows:
function myFunction() {
try {
if (theCondition == true) {
return "Everything's ok";
} else {
throw "JavaScript error occurred" ;
}
} catch (e) {
if (canHandle == true) {
handleIt();
} else {
throw e;
}
}
}
If theCondition is false, the function throws an exception. The exception is caught in the JavaScript code, and if canHandle is true, JavaScript handles it. If canHandle is false, the exception is rethrown, the Java handler catches it, and the doit method returns a Java string:
JavaScript error occurredSee "Exception Handling Statements" on page 81 for complete information about JavaScript exceptions.
JSException class had three public constructors which optionally took a string argument, specifying the detail message or other information for the exception. The getWrappedException method was not available.
Use a try...catch statement such as the following to handle LiveConnect exceptions in JavaScript 1.3 and earlier versions:
try {
global.eval("foo.bar = 999;");
} catch (Exception e) {
if (e instanceof JSException) {
jsCodeFailed()";
} else {
otherCodeFailed();
}
}
In this example, the eval statement fails if foo is not defined. The catch block executes the jsCodeFailed method if the eval statement in the try block throws a JSException; the otherCodeFailed method executes if the try block throws any other error.
netscape.javascript.JSObject are always converted to instances of java.lang.Object. The rules for converting these return values are also described in these sections.
For example, if JSObject.eval returns a JavaScript number, you can find the rules for converting this number to an instance of java.lang.Object in "Number Values" on page 147.
| Java parameter type |
Conversion rules
The exact value is transferred to Java without rounding and without a loss of magnitude or sign.
|
|
|
|
| |
|---|
java.lang.String, the number is converted to a string. Use the == operator to compare the result of this conversion with other string values.
| Java parameter type |
Conversion rules
|
|
|
|
| |
|---|
java.lang.String, the Boolean is converted to a string. Use the == operator to compare the result of this conversion with other string values.
| Java parameter type |
Conversion rules
|
| All values are converted to numbers as described in ECMA-262.
|
| |
|---|
| Java parameter type |
Conversion rules
The value is converted to an instance of java.lang.String whose value is the string "undefined".
|
|
| |
|---|
java.lang.String, the undefined value is converted to a string. Use the == operator to compare the result of this conversion with other string values.
| Java parameter type |
Conversion rules
|
|
|
| |
|---|
JavaArray or JavaObject as a parameter to a Java method, Java simply unwraps the object; in a few situations, the object is coerced into another data type according to the rules described in the following table:
| Java parameter type |
Conversion rules
Any interface or class that is assignment-compatible with the unwrapped object.
|
| The object is unwrapped, and either of the following situations occur:
| |
|---|
unwrappedObject instanceof parameterType
JavaClass object as a parameter to a Java method, Java converts the object according to the rules described in the following table:
| Java parameter type |
Conversion rules
|
|
The
|
| |
|---|
| Java parameter type |
Conversion rules
The object is wrapped in a new instance of
|
The object is converted to a value using the logic of the
| |
|---|
netscape.javascript.JSObject is converted to the original JavaScript object.Array object: you can access it with the syntax arrayName[index] (where index is an integer), and determine its length with arrayName.length.toString method on the original object.doubleValue method, if possible, and fails otherwise.booleanValue method, if possible, and fails otherwise.String objects also correspond to JavaScript wrappers. If you call a JavaScript method that requires a JavaScript string and pass it this wrapper, you'll get an error. Instead, convert the wrapper to a JavaScript string by appending the empty string to it, as shown here:
var JavaString = JavaObj.methodThatReturnsAString();
var JavaScriptString = JavaString + "";
Last Updated: 10/29/98 15:51:13