[Contents]   [Index]

LiveConnect communication

LiveConnect enables communication between JavaScript and Java applets in a page and between JavaScript and plug-ins loaded on a page.

This chapter tells you how to use the LiveConnect feature of Netscape Navigator, and it assumes that you are familiar with Java programming. The chapter contains the following sections:

For the Netscape packages reference, see Chapter 12, "The Netscape packages."

For the HTML syntax for applets and plug-ins, see "Applet" or "Plugin".


Enabling LiveConnect

LiveConnect is enabled by default in Navigator 3.0. For LiveConnect to work, both Java and JavaScript must be enabled. To confirm they are enabled, choose Network Preferences from the Options menu, then choose the Languages tab.

To disable either Java or JavaScript, uncheck the checkboxes; if you do this, LiveConnect will not work.


The Java Console

The Java Console is a Navigator window that displays Java messages. When you use the class variables out or err in java.lang.System to output a message, the message appears in the Console. To display the Java Console, choose Show Java Console from the Options menu.

You can use the Java Console to present messages to users, or to trace the values of variables at different places in a program's execution.

For example, the following Java code displays the message "Hello, world!" in the Java Console:

public void init() {
   System.out.println("Hello, world!")
}

About the Netscape packages

Navigator 3.0 contains a java_30 file that includes the following Java packages:

The new java and sun packages replace packages in the Sun 1.0.2 Java Development Kit (JDK). These packages have been tested by Sun, and similar security enhancements will be implemented in future releases of the Sun JDK. Use these packages until the Sun JDK provides these security enhancements.

The file java_30 contains the following netscape packages:

These packages are documented in Chapter 12, "The Netscape packages."

In addition, java_30 contains some other netscape packages:

These packages are not documented because they are implemented the same as the original Sun packages.

Using the Netscape packages

The java_30 file is delivered in the Programjavaclasses directory beneath the Navigator directory. To access the packages in java_30, place the file in the classpath of the JDK compiler in either of the following ways:

For example, 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:

C:Program FilesNetscapeNavigatorProgramjavaclasses
See the Sun JDK documentation for more information about CLASSPATH.


JavaScript to Java communication

LiveConnect provides three ways for JavaScript to communicate with Java:

Accessing Java directly

When LiveConnect is enabled, JavaScript can make direct calls to Java methods. For example, you can call System.out.println to display a message on the Java Console.

In JavaScript, Java packages and classes are properties of the Packages object. Use Java syntax to reference Java objects in JavaScript, with the name of the Packages object optionally prepended:

[Packages.]packageName.className.methodName
The name Packages is optional for java, sun, and netscape packages; in code, java, sun, and netscape are aliases for Packages.java, Packages.sun, and Packages.netscape. For example, you can refer to the Java class java.lang.System as either Packages.java.lang.System or as java.lang.System in your code. The name Packages is required for other packages.

Access fields and methods in a class with the same syntax that you use in Java. For example, the following JavaScript code prints a message to the Java Console:

var System = java.lang.System
System.err.println("Greetings from JavaScript")
The first line in this example makes the JavaScript variable System refer to the class java.lang.System. The second line invokes the println method of the static variable err in the Java System class. Because println expects a java.lang.String argument, the JavaScript string is converted to a java.lang.String automatically.

You can even use Java class constructors in JavaScript. For example, the following code creates a Java Date object.

var mydate = new java.util.Date()

Controlling applets

You can use JavaScript to control the behavior of a Java applet without knowing much about the internal construction of the applet. All public variables, methods, and properties of an applet are available for JavaScript access. For example, you can use buttons on an HTML form to start and stop a Java applet that appears elsewhere in the document.

Referencing applets

Each applet in a document is reflected in JavaScript by document.appletName, where appletName is the value of the NAME attribute of the APPLET tag. There is also an applets array that contains all the applets in a page; you can reference elements of the array through the applet name (as in an associative array) or by the ordinal number of the applet on the page (starting from zero).

For example, consider the basic "Hello World" applet in Java:

import java.applet.Applet;
import java.awt.Graphics;

public class HelloWorld extends Applet {
   public void paint(Graphics g) {
      g.drawString("Hello world!", 50, 25);
      }
   }
The following HTML runs and displays the applet, and names it "HelloWorld" (with the NAME attribute):

<APPLET CODE="HelloWorld.class" NAME="HelloWorld" WIDTH=150 HEIGHT=25>
</APPLET>
You can reference this applet in JavaScript in either of the following ways:

document.HelloWorld
document.applets["HelloWorld"]
If this is the first applet in the document (topmost on the page), you could also reference it as:

document.applets[0]
The applets array has a length property, document.applets.length, that indicates the number of applets in the document.

All public variables declared in an applet, and its ancestor classes and packages are available in JavaScript. Static methods and properties declared in an applet are available to JavaScript as methods and properties of the Applet object. You can get and set property values, and you can call methods that return string, numeric, and boolean values.

Example: Hello World

So for example, modify the HelloWorld applet shown above, and make the following changes:

The source code then looks like this:

import java.applet.Applet;
import java.awt.Graphics;

public class HelloWorld extends Applet {
   String myString;

   public void init() {
      myString = new String("Hello, world!");
   }
   public void paint(Graphics g) {
      g.drawString(myString, 25, 20);
   }
   public void setString(String aString) {
      myString = aString;
      repaint();
   }
}
Making the message string a variable allows you to modify it from JavaScript. Now modify the HTML file as follows:

The HTML file now looks like this:

<APPLET CODE="HelloWorld1.class" NAME="Hello" WIDTH=150 HEIGHT=25>
</APPLET>

<FORM NAME="form1">
<INPUT TYPE="button" VALUE="Set String"
   onClick="document.HelloWorld.setString(document.form1.str.value)">
<BR>
<INPUT TYPE="text" SIZE="20" NAME="str">
</FORM>
When you compile the HelloWorld applet, and load the HTML page into Navigator, you initially see "Hello, World!" displayed in the gray applet panel. However, you can now change it by entering text in the text field and clicking on the button. This demonstrates controlling an applet from JavaScript.

Controlling plug-ins

Each plug-in in a document is reflected in JavaScript as an element in the embeds array. For example, the following HTML includes an AVI plug-in in a document:

<EMBED SRC=myavi.avi WIDTH=320 HEIGHT=200>
If this HTML defines the first plug-in in a document, you can use the following code to access it:

document.embeds[0]
If the plug-in is associated with the Java class netscape.plugin.Plugin, you can access its static variables and methods the way you access an applet's variables and methods.

The embeds array has a length property, document.embeds.length, that indicates the number of plug-ins embedded in the document. See "Determining installed plug-ins" for more information about plug-ins.

The Plug-in Developer's Guide (http://home.netscape.com/eng/mozilla/3.0/handbook/plugins/index.html) contains information on:


Java to JavaScript communication

To access JavaScript methods, properties, and data structures from your Java applet, import the Netscape javascript package:

import netscape.javascript.*
The package netscape.javascript defines the JSObject class and the JSException exception object.

The author of an HTML page must permit an applet to access JavaScript by specifying the MAYSCRIPT attribute of the APPLET tag. This prevents an applet from accessing JavaScript on a page without the knowledge of the page author. Attempting to access JavaScript from an applet that does not have the MAYSCRIPT attribute generates an exception.

Getting a handle for the JavaScript window

Before you can access JavaScript, you must get a handle for the Navigator window. Use the getWindow method in the class netscape.javascript.JSObject to get a window handle.

For example, if win is a previously-declared variable of type JSObject, the following code assigns a window handle to win:

public void init() {
   JSObject win = JSObject.getWindow(this);
}

Accessing JavaScript objects and properties

The getMember method in the class netscape.javascript.JSObject enables you to access JavaScript objects and properties. Call getWindow to get a handle for the JavaScript window, then call getMember to access each JavaScript object in a containership path in turn.

For example, the following Java code allows you to access the JavaScript object document.testForm through the variable myForm:

public void init() {
   win = JSObject.getWindow(this);
   JSObject doc = (JSObject) win.getMember("document");
   JSObject myForm = (JSObject) doc.getMember("testForm");
}
Notice that JavaScript objects appear as instances of the class netscape.javascript.JSObject in Java. Values passed between Java to JavaScript are converted as described in "netscape.javascript.JSObject".

If the JavaScript object document.testForm.jazz is a checkbox, the following code allows you to access its checked property:

public void init() {
   win = JSObject.getWindow(this);
   JSObject doc = (JSObject) win.getMember("document");
   JSObject myForm = (JSObject) doc.getMember("testForm");
   JSObject check = (JSObject) myForm.getMember("jazz");
   Boolean isChecked = (Boolean) check.getMember("checked");
}

Calling JavaScript methods

The call and eval methods of the class netscape.javascript.JSObject enable you to call JavaScript methods. Use getWindow to get a handle for the JavaScript window, then use call or eval to access a JavaScript method.

Use either of the following syntaxes to call JavaScript methods:

1. JSObject.getWindow().call("methodName", arguments)
2. JSObject.getWindow().eval("expression")
In the first form of this syntax, methodName is the name of the JavaScript method you want to call, and arguments is an array of arguments to pass to the JavaScript method. In the second form of the syntax, expression is a JavaScript expression that evaluates to a JavaScript method.

Example: Hello World

Returning to the HelloWorld example, modify the paint method so that it calls the JavaScript alert method (with the message "Painting!") as follows:

public void paint(Graphics g) {
   g.drawString(myString, 25, 20);
   JSObject win = JSObject.getWindow(this);
   String args[] = {"Painting!"};
   win.call("alert", args);
}
Then add the MAYSCRIPT attribute to the APPLET tag in the HTML page, recompile the applet, and try it. Each time the applet is painted (when it is initalized, when you enter a new text value, and when the page is reloaded) a JavaScript alert box pops up. This is a simple illustration of calling JavaScript from Java.

Note
You may have to reload the HTML page by choosing File | Open File... instead of clicking on the reload button, to ensure that the applet is re-initialized.
You can also call user-defined functions from a Java applet. For example, add the following function to the HEAD of the HTML page with the HelloWorld applet:

<SCRIPT>
function test() {
   alert("You are using " + navigator.appName + " " + navigator.appVersion)
}
</SCRIPT>
This simple function pops up an alert dialog box displaying the name and version of the client software being used. Then modify the init method similarly to the way you modified paint:

public void init() {
   myString = new String("Hello, world!")
   JSObject win = JSObject.getWindow(this)
   String args2[] = {""}
   win.call("test", args2)
}
Notice that args2 is declared as an array with no elements, even though the method does not take any arguments. When you recompile the applet and reload the HTML page (and re-initialize the applet), a JavaScript alert dialog box will pop up displaying the version of Navigator you are running. This is a simple illustration of calling a user-defined function from Java.