Using the LiveConnect Classes

Accessing JavaScript with JSObject

For example, suppose you are working with the Java class called 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.*;

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");
    }
}

Notice that the 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 to getMember inside a try...catch statement to handle errors of type JSException. See Handling JavaScript Exceptions in Java for more information.

To get a better sense of how 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.

Handling JavaScript Exceptions in Java

When JavaScript code called from Java fails at run time, it throws an exception. If you are calling the JavaScript code from Java, you can catch this exception in a 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:

• The JavaScript code is not evaluated, either due to a JavaScript compilation error or to some other error that occurred at run time. The JavaScript interpreter generates an error message that is converted into an instance of JSException.
• Java successfully evaluates the JavaScript code, but the JavaScript code executes an unhandled throw statement. JavaScript throws an exception that is wrapped as an instance of JSException. Use the getWrappedException method of JSException to unwrap this exception in Java.

For example, suppose the Java object 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;
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;
    }
}

In this example, the code in the 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 occurred

See Exception Handling Statements for complete information about JavaScript exceptions.

Backward Compatibility

In JavaScript 1.3 and earlier versions, the 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.