Oracle Service Busでは、カスタムXPath関数を作成するための充実したフレームワークが提供されます。カスタムXPath関数は、プロキシ・サービス・メッセージ・フロー、分割-結合およびXQuery Mapper変換など、開発時や実行時のツールにおいてXQuery式エディタで使用できます。
ここでは、XQuery式のカスタムXPath関数を作成、登録および使用する方法について説明します。次のプロセスが含まれます。
注意: Oracle Service Busでは、データベース表の更新やグローバル・トランザクションへの参加といった二次的な動作を含むカスタム関数はサポートされません。XQuery結果のみに影響するカスタム関数を作成し、二次的な動作はJavaコールアウトなど他の機能を使用して実行してください。 |
カスタム関数は、インストール内のOracle Service Busのすべてのプロジェクトとサービスで使用できます。特定のドメインに限られません。
カスタム関数の登録には、XMLファイル(およびローカライズ用のオプション・プロパティ・ファイル)の作成が必要です。Oracle Service Bus提供の組込み関数はこの関数フレームワークが使用されるため、このような既存の登録リソースをガイダンスとして使用できます。これらのファイルは次の場所にあります。
OSB_ORACLE_HOME/config/xpath-functions/
Oracle Service Busの関数ファイルはosb-built-in.xmlです。このファイルでは、%記号で囲まれたキー(%OSB_FUNCTIONS%など)は対応する.propertiesファイルから値を取得します。
カスタム関数登録ファイルの基本構造は次のとおりです。その後で要素について説明します。
category id group id function name comment namespaceURI className method isDeterministic
要素にはxpf:接頭辞が付きます。
カスタム関数の要素の説明
category id
– 式エディタで、一連の関数を物理的に分類するグループの名前です。たとえば、「Service Bus Functions」とします。id
属性を使用して名前を指定します。ローカライズのために対応する.propertiesファイルを使用する場合は、テキスト値を含むキーを.propertiesファイルに入力します。たとえば、%MY_FUNCTIONS%です。category id(プロパティ・ファイルのキー名と実際のnameの値を含む)は一意であることが必要です。
group id
– 省略可能。ユーザー・インタフェースで関数をグループ分けするためのサブカテゴリの名前です。たとえば、「General」または「Accessors」とします。category idのネーミング・ルールはgroup idにも適用されます。
name
– XQuery式に表示される関数の名前。関数名(namespaceURIと接頭辞で構成される)は一意であることが必要です。Oracle Service Busでは異なるメソッド引数でオーバーロードする関数はサポートされません。関数名が同一でもネームスペースが異なっていれば(つまり接頭辞が異なっていれば)使用できます。
comment
- 関数の説明。説明はOracle Service Busユーザー・インタフェースには表示されませんが、関数の呼出し方法やわかりやすい引数の名前を示すように指示を指定できます。
namespaceURI
– 関数のネームスペース。たとえば、Oracle Service Busの関数ネームスペースはhttp://www.bea.com/xquery/xquery-functions
です。ネームスペースとネームスペース接頭辞は一意であることが必要です。指定するカスタム・ネームスペースは、XQueryエディタのOracle Service Busデフォルト・ネームスペース・リストに表示されます。
className
– 関数を実装する、完全修飾されたカスタムJavaクラスです。
method
– 関数を実装するカスタムJavaメソッドです。前に戻り型を指定します。例:boolean isUserInGroup(java.lang.String, java.lang.String)
となります。
メソッドが一次元配列を使用する場合は、XMLファイルにエントリを作成する方法について23.2.1.1項「一次元配列の使用」を参照してください。
isDeterministic
– 関数が決定的かどうかを宣言するtrue
またはfalse
の値です。決定的関数は常に同じ結果を返します(たとえば、文字列を連結する関数)。非決定的関数は一意の結果を返します(たとえば、時刻を返す関数)。非決定的関数を使用できますが、XQuery標準では、XQueryエンジンの最適化を保証するために決定的関数の作成が推奨されています。
カスタム関数がXQuery式エディタに表示されるのは、Oracle Service Busがカスタム・クラスを検出できるようになってからです。次の項では、カスタム・クラスとパッケージを作成して、Oracle Service Busで検出できるようにする方法を説明します。
次のガイドラインに従って、カスタムXPath関数のクラスを作成してパッケージ化します。
次のガイドラインに従って、カスタム関数のJavaクラスとメソッドを作成します。
クラス – クラスはパブリックであることが必要です。
メソッド – メソッドはパブリックかつ静的であることが必要です。
引数および戻り値 – 表23-1に、メソッドの引数と戻り値でサポートされる型を示します。この表に含まれない型はサポートされません。内部クラスおよび多次元配列はサポートされません。
表23-1 カスタム関数でサポートされるJavaメソッドの型
Javaの型 | XQueryの型 | XSLTの型 |
---|---|---|
java.lang.String |
xs:string |
string |
int、java.lang.Integer |
xs:int |
number |
boolean、java.lang.Boolean |
xs:boolean |
boolean |
long、java.lang.Long |
xs:long |
number |
short、java.lang.Short |
xs:short |
number |
byte、java.lang.Byte |
xs:byte |
number |
double、java.lang.Double |
xs:double |
number |
float、java.lang.Float |
xs:float |
number |
char、java.lang.Char |
xs:string |
object |
java.math.BigInteger |
xs:integer |
number |
java.math.BigDecimal |
xs:decimal |
number |
java.util.Date |
xs:datetime |
脚注脚注1を参照してください。 |
java.sql.Date |
xs:date |
脚注を参照してください。 |
java.sql.Time |
xs:time |
脚注を参照してください。 |
javax.xml.namespace.QName |
xs:Qname |
脚注を参照してください。 |
org.apache.xmlbeans.XmlObject |
element() |
脚注を参照してください。 |
org.w3c.dom.Element |
element() |
XSLTのnode-set型はカスタムXPath関数ではサポートされません。 |
脚注1 文字列に変換されてから元の型として渡されます。
1次元配列(サポート対象のJavaの型を使用)が、アスタリスク(*)を使用して、対応するXQueryの型にマップされます(アスタリスクは、配列の複数のカーディナリティを暗黙に指定するワイルドカードです)。例:
public static XmlObject[] getArrayOfXmlObjects(XmlObject[] a)
これが次の型にマップされます。
namespace:getArrayOfXmlObjects($arg1 as element()*) as element()*
1次元配列の入力引数または戻り値を含む関数のシグネチャでは、http://java.sun.com/javase/6/docs/api/java/lang/Class.html#getName()
で説明されている型のエンコーディングを使用する必要があります。次の例は、カスタム関数XMLファイルで、必要な配列エンコーディングを使用して1次元配列のメソッドを指定する方法を示します。
Javaメソッド | カスタム関数XMLファイルでの入力 |
---|---|
public static String[] myUppercaseStringArray(String[] arg) |
Ljava.lang.String; myUppercaseStringArray([Ljava.lang.String;) |
public static int[] myAddInts(int[] arg) |
[I myAddInts([I) |
カスタム関数をXQueryエディタに組み込んで使用するためには、Oracle Service Busがそれらのカスタム関数を認識する必要があります。
カスタム関数クラスをJARファイルにパッケージ化し、そのJARをOSB_ORACLE_HOME/config/xpath-functions/ディレクトリに置きます。IDEおよびサーバーの起動時にOracle Service Busはこのディレクトリのカスタム関数クラスを認識します。23.1項「Oracle Service Busでのカスタム関数の登録」に従って、カスタム関数のXMLファイルでカスタム・クラスおよびメソッドを正しく参照してください。
注意: カスタム関数クラスに実行時のみアクセスすることもできます。これには、カスタムJARをOracle Fusion Middlewareホームの任意の場所に置いて、JARをサーバーのクラスパスに追加してください。 |
新しいカスタム関数を追加したら、IDEと新しい関数を使用するすべてのサーバーを再起動する必要があります。
ここでは、Oracle Service Busでカスタム関数を使用する方法について説明します。
Oracle Service Bus提供の関数と同様に、インラインXQuery式とXQueryリソースの両方にカスタム関数を含めることができます。
XSLTリソース内からカスタム関数を呼び出すための構文は、Oracle Service Busで使用するXSLTエンジンによって異なります。次のカスタム関数コードに対して、Xalan XSLTエンジン(Sun JDK対応のMicrosoft Windowsでのデフォルト)を使用してカスタム関数を呼び出す構文を例23-1に示します。
package tests.pipeline; public class CustomXQFunctions { public static String myUppercaseString(String arg) { return arg.toUpperCase(); } }
例23-1 Xalanエンジンを使用してカスタム関数を呼び出すための構文
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:param name="arg-string"/> <xsl:template name="myUppercaseString" xmlns:ns0="xalan://tests.pipeline.CustomXQFunctions"> <xsl:variable name="upcase" select="ns0:myUppercaseString($arg-string)" /> <originalInput> <xsl:value-of select="$arg-string" /> </originalInput> <result> <xsl:value-of select="$upcase" /> </result> </xsl:template> <xsl:template match="*"> <xsl:copy> <xsl:call-template name="myUppercaseString"/> </xsl:copy> </xsl:template> </xsl:stylesheet>
入力ドキュメントが<example />
、入力arg-string
の値がhello
の場合、変換は次のように行われます。
<example> <originalInput>hello</originalInput> <result>HELLO</result> </example>
EclipseでカスタムXPath関数を含むXQueryリソースのテストは、接続しているサーバーのみでサポートされています。「Run」→「Run As」→「Run on Server」コマンドを使用すると、テスト・コンソールでリソースが実行されます。
複数のOracle Fusion Middleware製品のホームがある複数サーバー環境では、カスタム関数が使用される環境ごとにすべてのカスタム関数リソースを手動で追加する必要があります。クラスタリングによって、すべての管理対象サーバーにカスタム関数リソースが自動的に配布されるわけではありません。