JavaScript コード用の ExternalType

EGL を使用すると、Rich UI アプリケーションは非生成 JavaScript にアクセスできます。 汎用ロジックを使用可能にしたり (例えば、乱数生成プログラムを提供するために)、非 EGL ウィジェットを参照したり (例えば、コード内で Dojo ウィジェットを使用可能にするために) することがあります。 いずれの場合も、作業は 2 とおりあります。
  1. JavaScript ロジックを Rich UI アプリケーションに使用可能にする EGL 外部型を開発する。JavaScript は、外部型の実装 と呼ばれています。
  2. 非生成 JavaScript クラスを作成する。ただしこれは、外部型が組み込み JavaScript クラス (Math または Number など) を参照しない場合に限ります。
外部型が JavaScript ソース・ファイルによって実装される場合、次の説明が当てはまります。

使用している外部型が組み込み JavaScript クラスによって実装されている場合は、外部型の relativePath プロパティーは設定しないでください。

外部型の実装方法に関係なく、JavaScript クラスの名前が外部型の名前とは異なっている場合は、そのクラスの名前に javaScriptName プロパティーを設定する必要があります。

実行時のエラーを回避するには、特定の 1 つの Rich UI アプリケーション内で、同じランタイム・ライブラリーの複数のバージョンを使用することを避けます。

このトピックでは、egl.defineClass の使用について説明します。 新規ウィジェットの定義について詳しくは、『Rich UI ウィジェット・セットの拡張』を参照してください。

汎用 JavaScript コードの構造

汎用ロジックを使用可能にする場合は (例えば乱数ジェネレーターなど)、JavaScript ファイルを WebContent フォルダーのサブディレクトリーに配置します。 このファイルは、egl.defineClass JavaScript 関数を呼び出します。
egl.defineClass(
   'packageName', 'className',
   'superclassPackageName', superclassName,
    {
      "constructor": function() 
      { },

      "otherFunction": function(parameterList)
      { }
    }
);
パラメーターは以下のとおりです。
packageName
カスタム JavaScript が常駐するパッケージの名前。パッケージ名は必須で、大/小文字の区別があり、WebContent サブフォルダーを識別します。最初のサブフォルダーの下のすべてのサブフォルダーについて、スラッシュの代わりにドットを使用します。例えば、JavaScript が WebContent/myPkg/test フォルダーにある場合、packageName 値は myPkg.test です。
className
JavaScript クラス名として割り当てる ID。このクラスは、事前定義された関数の集合です。 この名前は、EGL 外部型の JavaScriptName プロパティーの名前でなければなりません。これはデフォルトでは外部型の名前になります。 このクラス名は大/小文字が区別され、必須です。
superclassPackageName
オプション。スーパー・クラスの EGL 外部型が常駐するパッケージの名前。パッケージ名は大/小文字を区別します。 この値を指定する場合、superclassName 値も指定する必要があります。
superclassName
オプション。スーパー・クラスの名前で、スーパークラスを EGL ソース・コードに使用可能にする EGL 外部型の名前でもあります。スーパークラス名は大/小文字を区別します。 この値を指定する場合、superclassPackageName 値も指定する必要があります。
otherFunction
1 つの指定された「コンストラクター」に追加される関数。これについては後述します。 追加の関数は任意の数だけ指定できます。
parameterList
関数パラメーターのリスト。

「constructor」という名前の関数はオプションであり、存在する場合は、外部型の EGL 変数を宣言すると即時に実行されます。 この関数は、パラメーターを持つことができず、関数のリスト内のどの位置にも配置できます。

1 つの JavaScript ファイルに複数のクラスを定義できますが、規則では組み込むことができるのは、ファイルと同じ名前の 1 つのクラスのみです。例えば、以下は、RandomNumberGenerator.js ファイル内のコードで、乱数生成プログラムを使用可能にします。
egl.defineClass(
   'randomNumber', 'RandomNumberGenerator',	

   {	
	     "constructor" : function()
      {
         this.upperLimit = 100;
      },

      "setUpperLimit" : function(limit)
      {
         this.upperLimit = limit;
      },

      "getUpperLimit" : function()
      {
         return this.upperLimit;
      },

      "generateRandomNumber" : function()
      {
         return Math.floor(Math.random()*this.upperLimit);
      }
   }
);

外部型のステレオタイプ

JavaScript に関しては、EGL 外部型のステレオタイプは JavaScriptObject です。以下にその例を示します。
package randomNumber;

import com.ibm.egl.rui.JavaScriptObject;
import com.ibm.egl.rui.JavaScriptProperty;

ExternalType RandomNumberGenerator type JavaScriptObject
   {
      relativePath = "randomnumber",
      javaScriptName = "RandomNumberGenerator"
   }

   upperLimit int {@JavaScriptProperty{getMethod = "getUpperLimit", 
                                       setMethod = "setUpperLimit"}};
  
   function generateRandomNumber() returns(int);
end
外部型には、extends 文節を組み込んで、スーパー・クラスを表す外部型を参照することができます。次に、概略の例を示します。
ExternalType MyType extends OtherType type JavaScriptObject

end
外部型にも、以下のパーツ・レベルのプロパティーを組み込むことができます。それぞれは以下のストリングを取ります。
relativePath
WebContent フォルダーに関連する JavaScript ファイルのロケーション。プロパティー設定はオプションです。JavaScript ファイルが、サブフォルダーではなく WebContent フォルダーに直接保管される場合は、relativePath プロパティーを空のストリングに設定します。 いずれの場合にも、プロパティー値にはファイル名を組み込まないでください。

外部型が JavaScript ファイルによって実装される場合は、relativePath プロパティーを設定する必要があります。 外部型が組み込みクラスによって実装される場合は、プロパティーを設定しないでください。

javaScriptName
JavaScript クラスの名前を指定します。 ファイル拡張子 .js を指定しないでください。これは想定済みです。

プロパティー設定はオプションです。値を指定しない場合は、JavaScript クラスの名前が外部型の名前と想定されます。

名前が EGL 予約語である JavaScript クラスにアクセスするには、javaScriptName プロパティーを使用できます。 例えば、以下の外部型により、add という JavaScript クラスにアクセスすることが可能になります。これは WebContent/part1/part2/add.js ファイル内にあります。
ExternalType SumType type JavaScriptObject 
                          {relativePath = "part1/part2", javaScriptName = "add" }
    ;
end
includeFile
実行時に使用可能にされる HTML ファイルや、他の CSS あるいは JavaScript ファイルを示します。 includeFile に指定されるパスは、WebContent ディレクトリーに対して相対的です。 「JS/myFile.js」などがその例です。
次のファイルは、DoJo ウィジェットの参照に外部型を使用する場合に使用される場合があります。:
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js">
</script>

<style type="text/css">
   @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/dijit.css";
   @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";
   @import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"
</style>
        
<script>
   dojo.require("dijit.form.Button");
   dojo.require("dijit.form.Slider");
</script>

このファイルにより、Dojo ウィジェット・ライブラリーと Dojo CSS ファイルがロードされ、Dojo ランタイムが開始されます。

外部型の例で示したように、そのタイプのフィールドには、次のフィールド・レベル・プロパティーを含めることができます。
@JavaScriptProperty
この複合プロパティーは、EGL コードから JavaScript グローバル・フィールド (this.myField 書式のフィールド) にアクセスする場合には必須です。 EGL コードから値を割り当てる場合、JavaScript で、「constructor」という名前の関数にフィールドを定義する必要があります。しかし、JavaScript 内に定義されているフィールドの場所に関係なく、JavaScript フィールドから値を取得できます。
一般的に、@JavaScriptProperty で、 JavaScript フィールド値を取得および設定する JavaScript 関数を識別します。関数の名前が、直後に変数名が続く単語 get または set で作成されている場合は、関数名を指定せずにこのプロパティーを使用できます。 例えば、変数が UpperLimit で、JavaScriptクラスに getUpperLimit()setUpperLimit() という名前の関数が含まれている場合、必要なのは、複合プロパティーを追加することのみです。次にその例を示します。
UpperLimit INT { @JavaProperty{} };
@JavaScriptProperty のプロパティー・フィールドは、以下のとおりです。
getMethod
指定された変数の get メソッドの名前を含む (引用符で囲んだ) ストリング (小括弧は含まれません)。 メソッドはパラメーターを持たず、その戻り値はフィールドと同じ型になります。
setMethod
指定された変数の set メソッドの名前を含む (引用符で囲んだ) ストリング (小括弧は含まれません)。 メソッドは型がフィールドと同じパラメーターを 1 つ持ちます。 規則により、setMethod には戻り値はありませんが、メソッドが値を戻してもエラー状態にはなりません。

次の 2 つのプロパティー・フィールドのうちの 1 つのみを指定した場合、EGL では未指定の関数は使用不可と想定されます。欠落していると想定される関数の呼び出しを引き起こす式がない場合、エラーは発生しません。

JavaScript フィールド名は、外部型のフィールド名と同様、大/小文字が区別されます。

EGL と JavaScript データ型の関係

表 1. EGL と JavaScript データ型
EGL 型 JavaScript タイプ (大/小文字を区別)
STRING ストリング
BOOLEAN Boolean
SMALLINT、INT、FLOAT、SMALLFLOAT 数値
BIGINT、DECIMAL、MONEY、NUM egl.javascript.BigDecimal (後のセクションで説明)
DATE、TIME、TIMESTAMP Date

EGL 配列は、JavaScript に JavaScript 配列として渡されます。EGL タイプ (配列など) が NULL に設定されている場合、JavaScript コードは JavaScript NULL を受け取ります。

egl.javascript.BigDecimal

提供された JavaScript クラス egl.javascript.BigDecimal では、非常に大きい桁数を持つ数値を正確に表現できます。このクラスには、BigDecimals で数学演算を実行するメソッドもあります。

JavaScript のネイティブ数値タイプは Number クラスです。これは、数値を浮動小数点表記します。このクラスは不正確で、多くの値を表現できません。Number クラスの値を使用して数学計算すると、丸め誤差が発生することがあります。

BigDecimal オブジェクトは、作成されたら変更できません。例えば、2 つの BigDecimal 値を追加するには、次のようにコーディングします。
   var result = bigDecimal1.add( bigDecimal2 ); 
次のようにコーディングすると、結果は失われます。
   bigDecimal1.add( bigDecimal2 ); 
egl.javascript.BigDecimal コンストラクターは 1 つの引数を使用します。これは、BigDecimal に望ましい値を含む文字列です。文字列形式の数値には、少なくとも 1 桁の数値が必要で、ブランクを含めることはできません。 これは先行の符号と小数点を持つことができ、指数表記にすることもできます。 以下に、有効な引数をいくつか示します。
  • "0"
  • "12"
  • "-76"
  • "12.70"
  • "+0.003"
  • "17."
  • ".5"
  • "4E+9"
  • "0.73e-7"
以下に、egl.javascript.BigDecimal のオブジェクト (このようなオブジェクトは bd として識別され、数値オブジェクトは n として識別される) を使用する JavaScript メソッドを示します。
  • abs()。BigDecimal の絶対値を戻します。
  • add( bd )。現行オブジェクトと引数の合計を戻します。
  • compareTo( bd )。現行オブジェクトが、引数より小さい場合は -1、引数より大きい場合は 1、等しい場合は 0 を戻します。
  • divide( bd )。現行オブジェクトを引数で除算した結果を戻します。
  • divideInteger bd )。現行オブジェクトを引数で除算した結果の整数部分を戻します。
  • equals(obj) は、引数 (任意のオブジェクトが可能) が、現行オブジェクトと同じ値と位取り (10 進数の桁数) を持つ BigDecimal である場合には、true を返します。 このメソッドは、引数が BigDecimal でないか、または異なる値あるいは位取りを持つ BigDecimal の場合には false を返します。 obj パラメーターは任意のオブジェクトになります。
  • max( bd )。現行オブジェクトまたは引数の、いずれか大きい方を戻します。
  • min( bd )。現行オブジェクトまたはパラメーターの、いずれか小さい方を戻します。
  • movePointLeft( n )。現行オブジェクト (Number) と等価の BigDecimal を戻します。ただし、小数点は指定された位置数だけ左に桁移動されます。
  • movePointRight( n )。現行オブジェクト (Number) と等価の BigDecimal を戻します。ただし、小数点は指定された位置数だけ右に桁移動されます。
  • multiply(bd )。現行オブジェクトを引数で乗算した結果を戻します。
  • negate()。現行オブジェクトの否定を戻します。
  • pow( bd )。現行オブジェクトを指定された数だけ累乗した結果を戻します。累乗は -999999999 から 999999999 までの範囲内で、ゼロの 10 進数部がある必要があります。
  • remainder( bd )。現行オブジェクトを引数で除算して、余りを戻します。
  • setScale( n, mode )。指定されたスケール (10 進桁数) の BigDecimal を戻します。引数 n は数値で、オプションの引数モード は定数です (後述します)。
    n が現行スケールより大きい場合、メソッドによって、数値の小数部に後続ゼロが追加されます。n が現行スケールより小さい場合は、メソッドによって数値の小数部から後続桁が除去されます。モード で、残りの桁の丸め方が示されます。以下に、モード の可能な値を示します。
    • デフォルト (egl.javascript.BigDecimal.prototype.ROUND_UNNECESSARY) は、丸める必要がないことを示します。
    • egl.javascript.BigDecimal.prototype.ROUND_CEILING では、より大きい正数に丸められます。
    • egl.javascript.BigDecimal.prototype.ROUND_DOWN では、ゼロに向かって丸められます。
    • egl.javascript.BigDecimal.prototype.ROUND_FLOOR では、より大きい負の数値に丸められます。
    • egl.javascript.BigDecimal.prototype.ROUND_HALF_DOWN では、隣接値に丸められます。この場合、等距離値は切り捨てられます。
    • egl.javascript.BigDecimal.prototype.ROUND_HALF_EVEN では、隣接値に丸められます。この場合、等距離値は偶数の隣接値に丸められます。
    • egl.javascript.BigDecimal.prototype.ROUND_HALF_UP では、隣接値に丸められます。この場合、等距離値は切り上げられます。
    • egl.javascript.BigDecimal.prototype.ROUND_UP では、ゼロから離れる方向に丸められます。

  • scale()。小数点の後の桁数を、数値として戻します。
  • signum()。数値が負の場合は -1、ゼロの場合は 0、正の場合は 1 を戻します。
  • subtract( bd )。現行オブジェクトからパラメーターを減算した結果を戻します。
  • toString()。BigDecimal オブジェクトの文字列表現を戻します。
以下の定数も、BigDecimal によって定義されます。
  • egl.javascript.BigDecimal.prototype.ZERO は、値ゼロの BigDecimal です。
  • egl.javascript.BigDecimal.prototype.ONE は、値 1 の BigDecimal です。
  • egl.javascript.BigDecimal.prototype.TEN は、値 10 の BigDecimal です。

JavaScriptObjectException

非生成 JavaScript 関数が、外部型を使用して起動され、関数からエラーがスローされた場合、起動で EGL JavaScriptObjectException が発生します。すべての EGL 例外と同様に、JavaScriptObjectException には メッセージメッセージ ID フィールドがあります。

JavaScript エラー・オブジェクトがキャッチされると、エラー・オブジェクトの同等のフィールドからメッセージ ・フィールドが設定されます。それ以外の場合は、メッセージ・フィールドは、JavaScript 関数によってスローされた値と同等の文字列を受け取ります。

次に、JavaScriptObjectException の追加フィールドを示します。
name
JavaScript エラー・オブジェクトがキャッチされると、エラー・オブジェクトの同等のフィールドから名前フィールドが設定されます。それ以外の場合、名前フィールドは空ストリングを受け取ります。

フィードバック