LiveConnect の概要

この章では、Java のコードと JavaScript のコードが相互通信を可能にする技術である LiveConnect の使用方法を解説します。この章の読者は、Java プログラミングの経験があるものとします。

ラッパの使用

JavaScript において、ラッパとは元の言語のオブジェクトをくるんだ、ターゲットとする言語のデータ型のオブジェクトです。JavaScript でプログラミングをするときは、ラッパオブジェクトを用いることで Java のメソッドやフィールドにアクセスすることができます。つまり、ラッパのメソッドを呼び出したりプロパティにアクセスすることで、Java のオブジェクトにおいて呼び出すことになります。Java 側では JavaScript のオブジェクトがクラス netscape.javascript.JSObject のインスタンスでラップされ、Java に渡されます。

JavaScript のオブジェクトが Java に送られる際、ランタイムエンジンは JSObject 型の Java ラッパを生成します。一方 JSObject が Java から JavaScript に送られるときは、ランタイムエンジンはそのラップを解き、元の JavaScript オブジェクトの種類に戻します。JSObject クラスには、JavaScript のメソッドを呼び出したり JavaScript のプロパティを調べるためのインタフェースが備わっています。

JavaScript から Java への通信

Java のパッケージやクラスを参照したり、Java のオブジェクトや配列を扱ったりするときは、特別な LiveConnect オブジェクトを使用します。JavaScript から Java へのアクセスはすべて、これらのオブジェクトを用いて行います。それらのオブジェクトについて、以下の表で簡単にまとめます。

注意: Java は強く型付けされた言語であり、JavaScript は弱く型付けされた言語であるため、LiveConnect を使用する際はもう一方の言語のために JavaScript ランタイムエンジンが引数の値を適当なデータ型に変換します。詳細はデータ型の変換をご覧ください。

かなり直感的に Java とやりとりできることから、ある意味で LiveConnect オブジェクトの存在は透過的です。例えば、次のように Java の String オブジェクトを作成し、new 演算子を Java のコンストラクタとともに用いて、そのオブジェクトを JavaScript の変数 myString に代入することができます:

var myString = new java.lang.String("Hello world");

この例では、変数 myString は JavaObject になります。これは、Java の String オブジェクトのインスタンスを保持しているためです。JavaObject であるので、myString は java.lang.String およびそのスーパークラスである java.lang.Object のパブリックなインスタンスメソッドにアクセスできます。これらの Java のメソッドは JavaScript から、JavaObject のメソッドとして使用できます:

myString.length(); // 11 を返す

JavaClass オブジェクトの静的メンバは直接呼び出すことができます。

alert(java.lang.Integer.MAX_VALUE); // 2147483647 というアラート

Packages オブジェクト

Java のクラスが java、sun あるいは netscape パッケージのいずれの一部でもない場合は、Packages オブジェクトを用いてそれにアクセスします。例えば Redwood 社が、実装したさまざまな Java のクラスを格納するための、redwood という名前の Java パッケージを使用することを想定します。redwood の HelloWorld クラスのインスタンスを作成するには、次のようにそのクラスのコンストラクタにアクセスします:

var red = new Packages.redwood.HelloWorld();

デフォルトパッケージのクラス (すなわち、明示的にはパッケージに名前をつけていないクラス) にアクセスすることもできます。例えば、HelloWorld クラスが直接 CLASSPATH に入っており、またパッケージには入っていない場合は、次のようにしてそれにアクセスできます:

var red = new Packages.HelloWorld();

LiveConnect の java、sun および netscape オブジェクトはよく使用される Java のパッケージであるために、短縮記法が備わっています。例えば、次のように使用できます:

var myString = new java.lang.String("Hello world");

これは次のものを省略したものです:

var myString = new Packages.java.lang.String("Hello world");

Java の配列の使用

Java のメソッドが配列を作成し、JavaScript からその配列を参照するときは、JavaArray を使用します。例えば、次のコードは int 型の要素を 10 個持つ JavaArray x を作成します:

var x = java.lang.reflect.Array.newInstance(java.lang.Integer, 10);

JavaScript の Array オブジェクトのように、JavaArray にはその配列の要素数を返す length プロパティがあります。Array.length とは異なり、JavaArray.length は読み取り専用のプロパティです。これは、Java の配列は作成時に要素総数が固定されるためです。

パッケージおよびクラスの参照

JavaScript から Java のパッケージやクラスへの簡単な参照では、JavaPackage や JavaClass オブジェクトが作成されます。先の Redwood 社についての例では、例えば Packages.redwood という参照が JavaPackage オブジェクトです。同様に、java.lang.String のような参照は JavaClass オブジェクトです。

ほとんどの場合は JavaPackage や JavaClass オブジェクトについて気にする必要はありません。ただ Java のパッケージを使うだけのことであり、LiveConnect がこれらのオブジェクトを透過的に生成するからです。LiveConnect がクラスの読み込みに失敗する場合があり、そのときは以下のようにして手動で読み込みを行う必要があります:

var Widgetry = java.lang.Thread.currentThread().getContextClassLoader().loadClass("org.mywidgets.Widgetry");

JavaScript 1.3 以前では JavaClass オブジェクトをパラメータとして Java のメソッドとして渡す際に、自動的には java.lang.Class のインスタンスに変換されません。そのため、java.lang.Class のインスタンスのラッパを作成しなければなりません。次の例では、forName メソッドがラッパオブジェクトである theClass を生成します。そしてそれを newInstance メソッドに渡し、配列を生成します。

// JavaScript 1.3
var theClass = java.lang.Class.forName("java.lang.String");
var theArray = java.lang.reflect.Array.newInstance(theClass, 5);

JavaScript 1.4 以降では次の例のように、JavaClass オブジェクトをメソッドに直接渡すことができます:

// JavaScript 1.4
var theArray = java.lang.reflect.Array.newInstance(java.lang.String, 5);

char 型の引数

JavaScript 1.4 以降では char 型の引数を必要とする Java のメソッドに、1 文字の文字列を渡すことができます。例えば、次のようにして文字列 "H" を Character コンストラクタに渡すことができます:

var c = new java.lang.Character("H");

JavaScript 1.3 以前では、このようなメソッドにはその文字の Unicode 値に対応する整数値を渡さなければなりません。例えば、次のコードも "H" という文字列を変数 c に代入するものです:

var c = new java.lang.Character(72);

JavaScript での Java 例外の処理

Java のコードは実行時に失敗すると、例外を投げます。JavaScript のコードが Java のデータメンバまたはメソッドにアクセスし、失敗すると、Java の例外が JavaScript に渡されます。これは、例外を処理できるようにするためです。JavaScript 1.4 からは try...catch 文でこの例外を受け取ることができます。(Mozilla 固有の LiveConnect コードが Mozilla 内でメンテナンスされていなかったため、この機能は (他の一部機能もあわせて) Gecko 1.9 で壊れています (バグ 391642 をご覧ください)。しかし Java 6 アップデート 11 および 12 での、Mozilla の汎用 (かつクロスブラウザの) NPAPI プラグインコードに依存する構築のサポートにより修復されました。)

例えば、Java の forName メソッドを使用して Java のクラス名を theClass という変数に代入するとします。forName メソッドに渡す値が Java のクラス名に評価できなければ、そのメソッドは例外を投げます。次のようにして、例外を処理できるように forName 代入文を try ブロック内に置きます:

function getClass(javaClassName) {
   try {
      var theClass = java.lang.Class.forName(javaClassName);
   } catch (e) {
      return ("The Java exception is " + e);
   }
   return theClass;
}

この例では、javaClassName が "java.lang.String" のような正当なクラス名に評価されると代入が成功します。javaClassName が "String" のような不正なクラス名に評価されると、getClass 関数が例外を受け取り、次のようなものを返します:

The Java exception is java.lang.ClassNotFoundException: String

例外の型に基づいて特別な処理をするには instanceof 演算子を使用します:

try {
  // ...
} catch (e) {
  if (e instanceof java.io.FileNotFound) {
     // FileNotFound についての処理
  } else {
    throw e;
  }
}

JavaScript の例外についての詳細情報は例外処理文を参照してください。

Java から JavaScript への通信

Java で JavaScript のオブジェクトを使用したい場合は、その Java ファイルに netscape.javascript パッケージをインポートしなければなりません。このパッケージは次のクラスを定義しています:

• netscape.javascript.JSObject : Java のコードから JavaScript のメソッドやプロパティにアクセスできるようにします。
• netscape.javascript.JSException : Java のコードで JavaScript のエラーを処理できるようにします。

これらのクラスの詳細は JavaScript リファレンスをご覧ください。

LiveConnect クラスの場所の特定

古いバージョンの Netscape ブラウザでは、これらのクラスがブラウザに同梱されていました。JavaScript 1.2 からは、これらのクラスは .jar ファイルに格納されています。それより古いバージョンの JavaScript では、これらのクラスは .zip ファイルに格納されています。例えば Windows NT 向けの Netscape Navigator 4 では、クラスは Navigator のディレクトリ直下の Program\Java\Classes ディレクトリ内の java40.jar ファイルに格納されています。

より最近では、クラスは Sun の Java ランタイムに同梱されています。はじめはランタイムディストリビューションの "jre/lib" ディレクトリ内の "jaws.jar" ファイルに入っていましたが (JRE 1.3)、その後同じ場所の "plugin.jar" に移っています (JRE 1.4 以降)。

JDK での LiveConnect クラスの使用

LiveConnect クラスにアクセスするには、次のどちらかの方法で JDK コンパイラの CLASSPATH に .jar または .zip ファイルを配置します:

• CLASSPATH 環境変数を作成し、.jar または .zip ファイルのパスと名前を指定します。
• コンパイル時に -classpath コマンドラインパラメータを用いて .jar または .zip ファイルの場所を指定する。

Windows NT では、コントロールパネルのシステムアイコンをダブルクリックし、CLASSPATH という名前のユーザ環境変数を作成し、それに次のような値を設定することで環境変数を作成できます:

C:\Program Files\Java\jre1.4.1\lib\plugin.jar

CLASSPATH についての詳細は Sun の JDK に関する資料をご覧ください。

注意: Java は強く型付けされた言語であり、JavaScript は弱く型付けされた言語であるため、LiveConnect を使用する際はもう一方の言語のために JavaScript ランタイムエンジンが引数の値を適当なデータ型に変換します。詳細は データ型の変換 をご覧ください。

LiveConnect クラスの使用

すべての JavaScript オブジェクトは、Java コード内では netscape.javascript.JSObject のインスタンスとして現れます。Java コード内でメソッドを呼び出すときに、その引数として JavaScriptのオブジェクトを渡すことができます。そうするためには、そのメソッドの対応する仮パラメータを JSObject 型で定義しなければなりません。

さらに、Java コード内で JavaScript のオブジェクトを使用するたびに、netscape.javascript.JSException 型の例外を処理する try...catch 文の内側で、その JavaScript オブジェクトを呼び出すようにしてください。こうすることで JSException 型の例外として Java で現れる、JavaScript コードの実行におけるエラーを Java コードで処理できるようになります。

JSObject を用いた JavaScript へのアクセス

例えば、JavaDog という Java のクラスを使用するとします。次のコードで示すように、JavaDog コンストラクタは JavaScript のオブジェクトである jsDog を引数としてとります。このオブジェクトは JSObject 型として定義されています:

import netscape.javascript.*;

public class JavaDog{
    public String dogBreed;
    public String dogColor;
    public String dogSex;

    // クラスコンストラクタの定義
    public JavaDog(JSObject jsDog){
        // ここで try...catch を使用して JSExceptions を処理できるようにする
        this.dogBreed = (String)jsDog.getMember("breed");
        this.dogColor = (String)jsDog.getMember("color");
        this.dogSex = (String)jsDog.getMember("sex");
    }
}

JSObject の getMember メソッドは、JavaScript のオブジェクトのプロパティにアクセスするために使用するものです。この例では JavaScript のプロパティである jsDog.breed の値を Java のデータメンバである JavaDog.dogBreed に代入するために、getMember を使用しています。

注意: より現実的な例では try...catch 文の内側で getMember を呼び出し、JSException 型のエラーを処理できるようにします。詳細は、Java での JavaScript の例外処理を参照してください。

getMember の動作をさらに知るために、JavaScript の Dog オブジェクトを作成し、その定義を見てみます:

function Dog(breed,color,sex){
   this.breed = breed;
   this.color = color;
   this.sex = sex;
}

Dog の JavaScript のインスタンスである gabby は、次のようにして作ることができます:

var gabby = new Dog("lab", "chocolate", "female");

gabby.color を評価すると、それが "chocolate" という値を持っていることがわかります。ここで次のように gabby オブジェクトをコンストラクタに渡し、JavaScript コードで JavaDog のインスタンスを作成することにします:

var javaDog = new Packages.JavaDog(gabby);

javaDog.dogColor を評価すると、それも "chocolate" という値を持っていることがわかります。これは Java のコンストラクタ内の getMember メソッドが、gabby.color の値を dogColor に代入するからです。

Java での JavaScript の例外処理

実行時に Java からの JavaScript コードの呼び出しに失敗すると、例外が投げられます。Java から JavaScript コードを呼び出すときに、try...catch 文でこの例外を受け取ることができます。JavaScript の例外は、netscape.javascript.JSException のインスタンスとして Java コードから扱えます。

JSException は JavaScript が投げるあらゆる種類の例外に対応する、Java のラッパです。JSObject のインスタンスが JavaScript のオブジェクトのラッパであるのと同じようなものです。Java で JavaScript コードを評価するときは JSException を使用してください。

Java で JavaScript コードを評価する際、次の状況でランタイムエラーが発生します:

• JavaScript コンパイルエラーまたは 実行時に生じた 他のエラーにより、JavaScript コードが評価されません。JavaScript インタプリタは、JSException のインスタンスに変換されるエラーメッセージを生成します。
• Java は正常に JavaScript のコードを評価しましたが、処理方法が定かでない throw 文をJavaScript コードが実行します。JavaScript は、JSException のインスタンスとしてラップされる例外を投げます。Java でこの例外のラップを解くには、JSException の getWrappedException メソッドを使用します。

例えば、Java のオブジェクトである jsCode が自身に渡される文字列 eTest を評価するとします。次のようなエラー処理を実行することで、評価が原因で発生するどちらの種類のランタイムエラーにも対応できます:

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

この例では、渡された文字列 jsCode を try ブロック内のコードが評価しようとします。文字列 "myFunction()" を jsCode の値として渡すとします。myFunction が JavaScript の関数として定義されていない場合、JavaScript インタプリタは jsCode を評価できません。インタプリタはエラーメッセージを生成し、Java のハンドラがそのメッセージを受け取り、doit メソッドは netscape.javascript.JSException のインスタンスを返します。

しかし、次のように myFunction が JavaScript で定義されているとします:

function myFunction() {
   try {
      if (theCondition == true) {
         return "Everything's ok";
      } else {
         throw "JavaScript error occurred";
      }
   } catch (e) {
      if (canHandle == true) {
         handleIt();
      } else {
         throw e;
      }
   }
}

theCondition が false であれば、関数は例外を投げます。その例外は JavaScript コードで受け取られ、さらに canHandle が true の場合に JavaScript はそれを処理します。canHandle false がならばその例外が再び投げられ、Java のハンドラがそれを受け取り、 doit メソッドが次の Java の文字列を返します:

JavaScript error occurred

JavaScript の例外についての詳細情報は例外処理文を参照してください。

後方互換性

JavaScript 1.3 以前のバージョンでは、JSException クラスには省略可能な文字列引数をとる 3 つの public タイプのコンストラクタがありました。この文字列引数は、詳細なメッセージやその例外に対する他の情報を指定するものです。getWrappedException メソッドは使用できませんでした。

次のような try...catch 文を使用することで、JavaScript 1.3 以前のバージョンで LiveConnect の例外を処理できます:

try {
   global.eval("foo.bar = 999;");
} catch (Exception e) {
   if (e instanceof JSException) {
      jsCodeFailed();
   } else {
      otherCodeFailed();
   }
}

この例では foo が定義されていないと eval 文が失敗します。try ブロックの eval 文が JSException を投げると、catch ブロックが jsCodeFailed メソッドを実行します。try ブロックがそれ以外のエラーを投げると、otherCodeFailed メソッドが実行されます。

データ型変換

Java は強く型付けされた言語であり、JavaScript は弱く型付けされた言語であるため、LiveConnect を使用する際はもう一方の言語のために、JavaScript ランタイムエンジンが引数の値を適切なデータ型に変換します。この変換について以下のセクションで説明します:

• JavaScript から Java への変換
• Java からJavaScript への変換

JavaScript から Java への変換

JavaScript から Java のメソッドを呼び出してパラメータを渡す際、渡すパラメータのデータ型は以下のセクションで説明するルールによって変換されます:

• 数値
• 真偽値
• 文字列値
• undefined 値
• null 値
• JavaArray および JavaObject オブジェクト
• JavaClass オブジェクト
• その他の JavaScript オブジェクト

netscape.javascript.JSObject メソッドの戻り値は常に java.lang.Object のインスタンスに変換されます。このような戻り値の変換ルールもここで説明します。

例えば JSObject.eval が JavaScript の数値を返すのであれば、この数値を java.lang.Object のインスタンスに変換するルールは数値に記載されています。

数値

Java のメソッドに JavaScript の数値型をパラメータとして渡すと、Java は次の表で示すルールに従ってその値を変換します:

java.lang.String のインスタンスをパラメータに想定した Java のメソッドに JavaScript の数値をパラメータとして渡すと、その数値は文字列に変換されます。equals() メソッドを使用すると、この変換結果と他の文字列を比較できます。

真偽値

Java のメソッドに JavaScript の真偽値型をパラメータとして渡すと、Java は次の表で示すルールに従ってその値を変換します:

java.lang.String のインスタンスをパラメータに想定した Java のメソッドに JavaScript の真偽値をパラメータとして渡すと、その真偽値は文字列に変換されます。== 演算子を使用すると、この変換結果と他の文字列を比較できます。

文字列値

Java のメソッドに JavaScript の文字列型をパラメータとして渡すと、Java は次の表で示すルールに従ってその値を変換します:

undefined 値

Java のメソッドに JavaScript の undefined 値をパラメータとして渡すと、Java は次の表で示すルールに従ってその値を変換します:

undefined 値の変換は JavaScript 1.3 以降でのみ可能です。それより古いバージョンでは、undefined 値がサポートされていません。

java.lang.String のインスタンスをパラメータに想定した Java のメソッドに JavaScript の undefined 値をパラメータとして渡すと、その undefined 値は文字列に変換されます。== 演算子を使用すると、この変換結果と他の文字列を比較できます。

null 値

Java のメソッドに JavaScript の null 値をパラメータとして渡すと、Java は次の表で示すルールに従ってその値を変換します:

JavaArray および JavaObject オブジェクト

ほとんどの場合、Java のメソッドに JavaScript の JavaArray または JavaObject オブジェクトをパラメータとして渡すと、Java は単にそのオブジェクトのラップを解きます。そうでない場合は、Java は次の表で示すルールに従ってそのオブジェクトを別のデータ型に変換します:

ラップが解かれたオブジェクトが Java のパラメータ型のインスタンスであれば、インタフェースまたはクラスが、ラップが解かれたオブジェクトと代入互換性があるということです。つまり、次の文は必ず true を返します:

unwrappedObject instanceof parameterType;

JavaClass オブジェクト

Java のメソッドに JavaScript の JavaClass オブジェクトをパラメータとして渡すと、Java は次の表で示すルールに従ってその値を変換します:

その他の JavaScript のオブジェクト

Java のメソッドに JavaScript のその他のオブジェクトをパラメータとして渡すと、Java は次の表で示すルールに従ってその値を変換します:

Java から JavaScript への変換

Java から JavaScript に渡された値は、次のように変換されます:

• Java の byte、char、short、int、long、float および double は、JavaScript の数値に変換されます。
• Java の boolean は、JavaScript の真偽値に変換されます。
• クラス netscape.javascript.JSObject のオブジェクトは、元の JavaScript のオブジェクトに変換されます。
• Java の配列は JavaScript の擬似的な Array オブジェクトに変換されます。このオブジェクトは JavaScript の Array オブジェクトと全く同じような挙動をとります。つまり、arrayName[index] (index は整数) という構文でそれにアクセスでき、その長さを arrayName.length で判断できます。
• Java のそれ以外オブジェクトは、JavaScript のラッパに変換されます。このラッパを通じて Java のオブジェクトのメソッドやフィールドにアクセスできます:
  • このラッパから文字列への変換では、元のオブジェクトで toString メソッドが呼び出されます。
  • 数値への変換では、可能であれば doubleValue メソッドが呼び出され、そうでなければ失敗します。
  • JavaScript 1.3 以降の真偽値への変換では、そのオブジェクトが null であれば false が、そうでなければ true を返します。
  • JavaScript 1.2 以前の真偽値への変換では、可能であれば booleanValue メソッドが呼び出され、そうでなければ失敗します。

java.lang.Double および java.lang.Integer のインスタンスは、JavaScript の数値ではなく JavaScript のオブジェクトに変換されることに注意してください。同様に java.lang.String のインスタンスも、JavaScript の文字列ではなく JavaScript のオブジェクトに変換されます。

Java の String オブジェクトも、JavaScript のラッパに相当します。JavaScript の文字列を必要とする JavaScript のメソッドを、このラッパを渡して呼び出すとエラーになります。そうではなく、次のようにラッパに空文字列を付加することで、ラッパを JavaScript の文字列に変換してください:

var JavaString = JavaObj.methodThatReturnsAString();
var JavaScriptString = JavaString + "";