クライアント アプリケーション開発者ガイド

Java クライアントからのデータ サービスの呼び出し

この章では、Java アプリケーションからデータ サービス処理を呼び出す Java API の Data Services Mediator API について説明します。この章では、Mediator API の使用方法を説明します。また、処理を始めるために役に立つ作業サンプル アプリケーションを含みます。

Mediator API の使用は、クライアント アプリケーションからデータ サービスを呼び出すための複数の手法の 1 つです。これらの手法の概要については、「クライアント アプリケーション向けのデータ サービスについて」を参照してください。

この章の内容は以下のとおりです。

Mediator API について

Mediator API は、データ サービスから Service Data Object (SDO) のアーティファクトを取得し、そのソースに返す Java API です。Java クライアントでは、Mediator API のメソッドを呼び出してデータ サービスに接続し、データ サービス メソッドを呼び出して、更新されたデータ オブジェクトをサーバに送り返します。SDO API のメソッドを使用して Java クライアント内のデータ オブジェクトを処理できます。

たとえば、Mediator API のメソッド getAllCustomers() を呼び出して、データ サービスから顧客のデータ オブジェクトの集合を取得します。さらに、setCustomerName() など SDO メソッドを呼び出すことで顧客オブジェクトを変更することができます。最後に、updateCustomers() など Mediator API の別のメソッドを呼び出して、変更されたオブジェクトをサーバ上のデータ ソースに返すことができます。

この節の内容は以下のとおりです。

SDO とは

データ サービス処理を呼び出すために ALDSP によって提供された Java プログラミング モデルは、Service Data Objects (SDO) に基づいています。SDO とは BEA と IBM、Oracle、SAP、および他社が共同提案した仕様で、データ プログラミング用の Java ベースのアーキテクチャおよび API です。ALDSP では、プログラマがリレーショナル データベース、XML データ ソースおよびエンタープライズ情報システムなど異種のデータ ソースからデータ オブジェクトに一様にアクセスできます。

Mediator API とは

SDO 仕様では、データ オブジェクトの更新メカニズムについては指定されていなく、mediator サービス という更新サービスのニーズについて説明します。Mediator API は、ALDSP によって実装されたメディエータ サービスです。Mediator API を使用すると、DataObjects という SDO 準拠オブジェクトにアクセスし、そのソース データ ストアに返すことができます。

重要な点は、Mediator API では、データ サービスに接続し、データ サービス処理を呼び出すことができるということです。結果が、SDO 準拠データ オブジェクトとして返されます。SDO API のメソッドを使用して、データ オブジェクトを変更し、処理できます。最後に、Mediator API を使用して更新を実行します。

SDO データ オブジェクトおよびその他のアーティファクトの一般的な概要については、「ALDSP および SDO」を参照してください。

動的および静的 Mediator API

ALDSP Mediator API は、動的および静的の 2 つの主なインタフェースから構成されています。アプリケーション開発者として、いずれかの手法を選択する必要があります。

API の概要

動的 Mediator API は、表 3-1 に示されているクラスおよびインタフェースで構成されています。これらのクラスおよびインタフェースの詳細の情報については、e-docs の Javadoc を参照してください。

静的 Mediator および動的 Mediator クライアント アプリケーションのサンプルについては、以下を参照してください。「静的 Mediator アプリケーションのサンプル」および「動的 Mediator アプリケーションのサンプル」を参照してください。

概要

SDO と mediator API を一緒に説明すると混乱を招く可能性があります。SDO とは、クライアント アプリケーションが ALDSP データ サービスを通じてデータにアクセスし、更新することができる標準で、利用可能な技術です。SDO は、Java API を使用して DataObjects および DataObject の集合を処理します。SDO の DataObjects は、動的オブジェクトか静的オブジェクトです。

SDO のAPI は、標準な実装です。次のリンクをクリックすると、完全な SDO 仕様「SDO for Java Specification V2.1」を読むことができます。

http://www.osoa.org/display/Main/Service+Data+Objects+Specifications

一方、mediator API は、ALDSP 固有の実装です。mediator API は、SDO DataObjects にアクセスし、それをサーバに返すことができるように設計されています。ALDSP の SDO の使用方法については、「データ プログラミング モデルと更新フレームワーク」を参照してください。

はじめに

この節では、データ サービスと対話する Java アプリケーションを書くための基本手順を示します。

この節の内容は以下のとおりです。

基本手順

Mediator API を使用する Java クライアントを開発する時の基本手順は以下のとおりです。

CLASSPATH の設定

CLASSPATH の設定は、静的 Mediator API の使用または動的 Mediator API の使用によって異なります。

静的 Java Mediator API クライアント CLASSPATH

静的 Mediator API を使用している場合、次の JAR が Java アプリケーションの CLASSPATH に含まれている必要があります。

動的 Java Mediator API クライアント CLASSPATH

動的 Mediator API を使用している場合、次の JAR を Java アプリケーションの CLASSPATH に存在する必要があります。

サンプル アプリケーションの実行

最初に、この章で取り上げたサンプル アプリケーション コードを実行するのが良いでしょう。静的 Mediator API と動的 Mediator API の両方を使用したサンプルです。サンプルは簡単に説明してありますが、データの取得、変更と更新のための共通のケースとして使用されます。「静的 Mediator アプリケーションのサンプル」および「動的 Mediator アプリケーションのサンプル」を参照してください。

静的 Mediator アプリケーションのサンプル

この節では、簡単な Java プログラムが含まれています。このプログラムをコピーし、コンパイルして実行することができます。プログラムは、サーバでクライアントの認証、データの取得、データの変更およびデータの更新など基本タスクを実行するために静的 Mediator API を使用します。静的 Mediator API の基本的な概要については、「動的および静的 Mediator API」を参照してください。また、「Mediator API の基礎」および「高度なトピック」を参照してください。

内容は以下のとおりです。

サンプル データ サービスの設定

サンプル Java アプリケーションを構築してテストする前に、ALDSP データ サービスを設定する必要があります。手順では、AquaLogic Data Services Studio の使用を理解していることを前提としています。

図 3-2 に、サンプル Dataspace コンフィグレーションを示します。

xquery version "1.0" encoding "UTF-8";

(::pragma  xds <x:xds targetType="t:CUSTOMER" xmlns:x="urn:annotations.ld.bea.com" xmlns:t="ld:Retail/CUSTOMER">
    <creationDate>2007-11-08T17:13:51</creationDate>
    <relationalDB name="dspSamplesDataSource" providerId="Pointbase"/>
    <field xpath="CUSTOMER_ID" type="xs:short">
        <extension nativeXpath="CUSTOMER_ID" nativeTypeCode="5"
        nativeType="SMALLINT" nativeSize="5" nativeFractionalDigits="0" 
        nativeKey="true">
            <autoNumber type="identity"/>
        </extension>
        <properties nullable="false"/>
    </field>
    <field xpath="FIRST_NAME" type="xs:string">
        <extension nativeXpath="FIRST_NAME" nativeTypeCode="12"
        nativeType="VARCHAR" nativeSize="64" nativeFractionalDigits="0"/>
        <properties nullable="false"/>
    </field>
    <field xpath="LAST_NAME" type="xs:string">
        <extension nativeXpath="LAST_NAME" nativeTypeCode="12"
        nativeType="VARCHAR" nativeSize="64" nativeFractionalDigits="0"/>
        <properties nullable="false"/>
    </field>
    <field xpath="CUSTOMER_SINCE" type="xs:date">
        <extension nativeXpath="CUSTOMER_SINCE" nativeTypeCode="91"
        nativeType="DATE" nativeSize="10" nativeFractionalDigits="0"/>
        <properties nullable="false"/>
    </field>
    <field xpath="EMAIL_ADDRESS" type="xs:string">
        <extension nativeXpath="EMAIL_ADDRESS" nativeTypeCode="12"
        nativeType="VARCHAR" nativeSize="32" nativeFractionalDigits="0"/>
        <properties nullable="false"/>
    </field>
    <field xpath="TELEPHONE_NUMBER" type="xs:string">
        <extension nativeXpath="TELEPHONE_NUMBER" nativeTypeCode="12"
        nativeType="VARCHAR" nativeSize="32" nativeFractionalDigits="0"/>
        <properties nullable="false"/>
    </field>
    <field xpath="SSN" type="xs:string">
        <extension nativeXpath="SSN" nativeTypeCode="12" nativeType="VARCHAR"
        nativeSize="16" nativeFractionalDigits="0"/>
        <properties nullable="true"/>
    </field>
    <field xpath="BIRTH_DAY" type="xs:date">
        <extension nativeXpath="BIRTH_DAY" nativeTypeCode="91" nativeType="DATE"
        nativeSize="10" nativeFractionalDigits="0"/>
        <properties nullable="true"/>
    </field>
    <field xpath="DEFAULT_SHIP_METHOD" type="xs:string">
        <extension nativeXpath="DEFAULT_SHIP_METHOD" nativeTypeCode="12"
        nativeType="VARCHAR" nativeSize="16" nativeFractionalDigits="0"/>
        <properties nullable="true"/>
    </field>

    <field xpath="EMAIL_NOTIFICATION" type="xs:short">
        <extension nativeXpath="EMAIL_NOTIFICATION" nativeTypeCode="5"
        nativeType="SMALLINT" nativeSize="5" nativeFractionalDigits="0"/>
        <properties nullable="true"/>
    </field>
    <field xpath="NEWS_LETTTER" type="xs:short">
        <extension nativeXpath="NEWS_LETTTER" nativeTypeCode="5"
        nativeType="SMALLINT" nativeSize="5" nativeFractionalDigits="0"/>
        <properties nullable="true"/>
    </field>
    <field xpath="ONLINE_STATEMENT" type="xs:short">
        <extension nativeXpath="ONLINE_STATEMENT" nativeTypeCode="5"
        nativeType="SMALLINT" nativeSize="5" nativeFractionalDigits="0"/>
        <properties nullable="true"/>
    </field>
    <field xpath="LOGIN_ID" type="xs:string">
        <extension nativeXpath="LOGIN_ID" nativeTypeCode="12" nativeType="VARCHAR"
        nativeSize="50" nativeFractionalDigits="0"/>
        <properties nullable="true"/>
    </field>
    <key name="CUSTOMER_0_SYSTEMNAMEDCONSTRAINT__PRIMARYKEY"
    type="cus:CUSTOMER_KEY" inferredSchema="true"
    xmlns:cus="ld:Retail/CUSTOMER"/>
</x:xds>::)

declare namespace f1 = "ld:Retail/CUSTOMER";

import schema namespace t1 = "ld:Retail/CUSTOMER" at "ld:Retail/schemas/CUSTOMER.xsd";

import schema "ld:Retail/CUSTOMER" at "ld:Retail/schemas/CUSTOMER_KEY.xsd";

   (::pragma function <f:function xmlns:f="urn:annotations.ld.bea.com"
   visibility="public" kind="read" isPrimary="false" nativeName="CUSTOMER"
   nativeLevel2Container="SAMPLECUSTOMER" style="table">
   <nonCacheable/>   </f:function>::)

   declare function f1:CUSTOMER() as schema-element(t1:CUSTOMER)* external;



   (::pragma function <f:function xmlns:f="urn:annotations.ld.bea.com"
   visibility="public" kind="create" isPrimary="true" nativeName="CUSTOMER"
   nativeLevel2Container="SAMPLECUSTOMER" style="table">
   <nonCacheable/>   </f:function>::)

   declare procedure f1:createCUSTOMER($p as element(t1:CUSTOMER)*)as
   schema-element(t1:CUSTOMER_KEY)* external;

   (::pragma function <f:function xmlns:f="urn:annotations.ld.bea.com"
   visibility="public" kind="update" isPrimary="true" nativeName="CUSTOMER"
   nativeLevel2Container="SAMPLECUSTOMER" style="table">
   <nonCacheable/>   </f:function>::)

   declare procedure f1:updateCUSTOMER($p as changed-element(t1:CUSTOMER)*) as
   empty()  external;

   (::pragma function <f:function xmlns:f="urn:annotations.ld.bea.com"
   visibility="public" kind="delete" isPrimary="true" nativeName="CUSTOMER"
   nativeLevel2Container="SAMPLECUSTOMER" style="table">
   <nonCacheable/>   </f:function>::)

   declare procedure f1:deleteCUSTOMER($p as element(t1:CUSTOMER)*) as empty() 
   external;

<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema targetNamespace="ld:Retail/CUSTOMER" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="CUSTOMER_KEY">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="CUSTOMER_ID" type="xs:short"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

<xs:schema targetNamespace="ld:Retail/CUSTOMER" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="CUSTOMER">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="CUSTOMER_ID" type="xs:short" minOccurs="0"/>
            <xs:element name="FIRST_NAME" type="xs:string"/>
            <xs:element name="LAST_NAME" type="xs:string"/>
            <xs:element name="CUSTOMER_SINCE" type="xs:date"/>
            <xs:element name="EMAIL_ADDRESS" type="xs:string"/>
            <xs:element name="TELEPHONE_NUMBER" type="xs:string"/>
            <xs:element name="SSN" type="xs:string" minOccurs="0"/>
            <xs:element name="BIRTH_DAY" type="xs:date" minOccurs="0"/>
             <xs:element name="DEFAULT_SHIP_METHOD" 
                type="xs:string" minOccurs="0"/>
            <xs:element name="EMAIL_NOTIFICATION" type="xs:short" minOccurs="0"/>
            <xs:element name="NEWS_LETTTER" type="xs:short" minOccurs="0"/>
            <xs:element name="ONLINE_STATEMENT" type="xs:short" minOccurs="0"/>
            <xs:element name="LOGIN_ID" type="xs:string" minOccurs="0"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Mediator クライアント JAR ファイルの生成

この節で後述したサンプル Java アプリケーションでは、データ サービスから Mediator クライアント JAR ファイルを最初に作成する必要があります。JAR のクラスには、type-safe メソッドがあります。このメソッドは、データ サービス関数とプロシージャを呼び出します。生成した Java メソッドの名前とその対応するデータ サービス関数のプロシージャの名前と同じです。

Data Services Studio を使用して Mediator クライアント JAR ファイルを生成するには、以下の手順に従います。

Java プロジェクトの設定

コード リスト 3-5 には、静的 Mediator API を使用するサンプル Java プログラムを示します。アプリケーションでは、データ ストーアから DataObject を取得し、オブジェクトを変更して、データ ストーアに返します。この例では、Data Services Studio を使用することを前提としていますが、IDE か必要な環境を構築できます。この例では、「MediatorClient」という Java プロジェクトを設定します。

プロジェクトを設定するには、以下の手順に従います。

package com.bea.dsp.sample;

import das.ejb.retail.CUSTOMERDAS;
import retail.customer.CUSTOMER;

import com.bea.dsp.das.DASResult;
import com.bea.dsp.sdo.SDOUtil;

import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.InitialContext;

public class StaticSampleApp {
    public static void main(String[] args) throws Exception {
        // メディエータの InitialContext を作成します。
        Hashtable<String, String> hash = new Hashtable<String, String>();
        hash.put(Context.INITIAL_CONTEXT_FACTORY,
                 "weblogic.jndi.WLInitialContextFactory");
        hash.put(Context.PROVIDER_URL,"t3://localhost:7001");
        hash.put(Context.SECURITY_PRINCIPAL,"weblogic");
        hash.put(Context.SECURITY_CREDENTIALS,"weblogic");
        Context ctx = new InitialContext(hash);

        // コンテキストと データスペース名で DataAccessService ハンドルを作成します。
        CUSTOMERDAS das = CUSTOMERDAS.getInstance(ctx, "MediatorSamples");

        // Invoke the basic 'get all customers' function
        DASResult<CUSTOMER> result = das.CUSTOMER();

        // 最初の CUSTOMER DataObject を取得します。また、
        // 任意の DASResults を dispose() メソッドで削除します。
        try {
            CUSTOMER customer = result.next();

            // CUSTOMER の変更追跡を有効にします。
            SDOUtil.enableChanges(customer);



            // 顧客を変更します。
            customer.setFIRST_NAME("New First Name");
            customer.setEMAIL_ADDRESS("first_name@example.com");

            // 変更を DSP へ送り戻します。更新関数は、
            // CUSTOMERs の配列を取ります。
            das.updateCUSTOMER(new CUSTOMER[] { customer });
        }
        finally {
            result.dispose();
        }
    }
}

コードの実行およびテスト

アプリケーションをテストするには、次の手順に従います。

Java クライアントが正常に動作していることを確認するには、データ サービスに対して以下のテストをするだけです。

サンプル コードの検査

この節では、コード リスト 3-4 に示す Java サンプルの部分を検証します。この節では以下について説明します。

パッケージのインポート

最初の 2 つのクラスは、生成された Mediator クライアント JAR ファイルに削除され、ビルド パスに置かれている必要があります。CUSTOMERDAS クラスは、データ サービスのために生成された DataAccessService クラスです。このクラスには、type-safe メソッドがあり、実際のデータ サービス処理にマップします。CUSTOMER クラスには、データ サービスから返された DataObjects を処理する SDO インタフェースがあります。

import das.ejb.retail.CUSTOMERDAS;
import retail.customer.CUSTOMER;

import com.bea.dsp.das.DASResult;
import com.bea.dsp.sdo.SDOUtil;

import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.InitialContext;

データ アクセス サービス ハンドルの取得

DataAccessService では、データ サービスのメソッドを呼び出すことができます。このクラスの詳細情報については、「Javadoc」を参照してください。静的 Mediator API については、DataAccessService (DAS) クラスには、ハンドルを返すために getInstance() というファクトリ メソッドがあります。

getInstance() メソッドには、ハンドルを返すために 2 つのパラメータが必要です。

    Hashtable<String, String> hash = new Hashtable<String, String>();
    hash.put(Context.INITIAL_CONTEXT_FACTORY,
        "weblogic.jndi.WLInitialContextFactory");
    hash.put(Context.PROVIDER_URL,"t3://localhost:7001");
    hash.put(Context.SECURITY_PRINCIPAL,"weblogic");
    hash.put(Context.SECURITY_CREDENTIALS,"weblogic");
    Context ctx = new InitialContext(hash);

    CUSTOMERDAS das = CUSTOMERDAS.getInstance(ctx, "MediatorSamples");

サービスからのデータの取得

生成された DataAccessService メソッドの CUSTOMER() は、データ サービスから結果セットを取得します。このメソッドは、データ サービスからのすべての顧客オブジェクトを返します。戻り値の型は DASResult オブジェクトで、反復子と同じように機能します。この戻り値の型の詳細情報については、「DASResult について」を参照してください。

DASResult<CUSTOMER> result = das.CUSTOMER();

結果からの DataObject の取得

DASResult.next() メソッドは、Java method Iterator.next() メソッドと同じように機能します。このメソッドは、SDO DataObject である、次の CUSTOMER を返します。SDO は、データへのアクセスやデータの更新に使用する、Java ベースのデータ プログラミング モデル (API) およびアーキテクチャです。SDO の詳細については、『ALDSP コンセプト ガイド』の「サービス データ オブジェクト (SDO) の使用」を参照してください。

CUSTOMER customer = result.next();

結果のオブジェクトの削除

結果オブジェクトを通じて反復するたびに、DASResult.dispose() を呼び出す必要があります。dispose() の詳細については、「DASResult オブジェクトの削除」を参照してください。

result.dispose();

DataObject の変更

DataObject を取得した後、それを変更できるが、これらの変更を ALDSP サーバに送信する場合、変更を行う前に、DataObject の変更追跡を有効にする必要があります。SDOUtil.enableChanges() メソッドでは、1 つの DataObject または DataObjects の配列の変更追跡を有効にすることができます。このメソッドの詳細については、「データ オブジェクトの取り扱い」を参照してください。顧客のオブジェクトの変更追跡を有効にすると、顧客オブジェクトの一部の値を変更するために、生成されたセッターが呼び出されます。

SDOUtil.enableChanges(customer);

// 顧客を変更します。
customer.setFIRST_NAME("New First Name");
customer.setEMAIL_ADDRESS("first_name@example.com");

変更のサーバへの返し

最後に、生成された DataAccessService.updateCUSTOMER() メソッドは、CUSTOMER オブジェクトの配列という 1 つのパラメータで呼び出されます。このメソッドは、その等価データ サービス処理を呼び出して、新たに変更したデータ行をデータベースに更新します。

das.updateCUSTOMER(new CUSTOMER[] { customer });

動的 Mediator アプリケーションのサンプル

この節では、簡単なサンプルが含まれています。このサンプルをコピーし、コンパイルして実行することができます。サンプルは、サーバでクライアントの認証、データの取得、データの変更およびデータの更新など基本タスクを実行するために動的 Mediator API を使用します。

この節の内容は以下のとおりです。

サンプル コードの設定および実行

サンプル コードを設定し、実行するには、「静的 Mediator アプリケーションのサンプル」に示す基本指示に従います。サンプル データ サービスの作成、Java オブジェクトの設定、およびプログラムの実行に関するプロシージャは、静的 Mediator のサンプルと同じですが、動的 Mediator API を使用する場合、静的 Mediator クライアント JAR ファイルを作成または参照する必要はありません。プロジェクトのコード リスト 3-5 のように、サンプル Java コードを使用します。

Java クライアント コードのサンプル (動的 Mediator API)

package com.bea.dsp.sample;

import com.bea.dsp.das.DataAccessServiceFactory;
import com.bea.dsp.das.DataAccessService;
import com.bea.dsp.das.DASResult;
import com.bea.dsp.sdo.SDOUtil;

import commonj.sdo.DataObject;

import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.InitialContext;

public class DynamicSampleApp {
    public static void main(String[] args) throws Exception {
        // メディエータの InitialContext を作成します。
        Hashtable<String, String> hash = new Hashtable<String, String>();
        hash.put(Context.INITIAL_CONTEXT_FACTORY,
                 "weblogic.jndi.WLInitialContextFactory");
        hash.put(Context.PROVIDER_URL,"t3://localhost:7001");
        hash.put(Context.SECURITY_PRINCIPAL,"weblogic");
        hash.put(Context.SECURITY_CREDENTIALS,"weblogic");
        Context ctx = new InitialContext(hash);

        // コンテキストと データスペース名およびデータ サービスの URI で 
        // DataAccessService のハンドルを作成します。
        DataAccessService das = DataAccessServiceFactory.newDataAccessService
            (ctx, "MediatorSamples", "ld:Retail/CUSTOMER");

        // 引数を取らない基本的な「get all customers」
        // 関数を呼び出します。
        DASResult<Object> result = das.invoke("CUSTOMER", new Object[0]);

        // 最初の CUSTOMER DataObject を取得します。また、
        // 任意の DASResults を dispose() メソッドで削除します。
        try {
            DataObject customer = (DataObject) result.next();

            // CUSTOMER の変更追跡を有効にします。
            SDOUtil.enableChanges(customer);

            // 顧客を変更します。
            customer.set("FIRST_NAME", "DynamicClient");
            customer.set("EMAIL_ADDRESS", "dynamic@example.com");

            // 変更を DSP へ送り戻します。更新関数は、
            // CUSTOMERs の配列を取ります。
            das.invoke("updateCUSTOMER", new Object[] { customer });
        }
        finally { result.dispose(); }
    }
}

サンプル コードの検査

この節では、コード リスト 3-5 に示す Java サンプルの部分を検証します。この節では以下について説明します。

クラスのインポート

このクラスは、サンプルに対して必要です。クラスの詳細については、e-docs の Javadoc を参照してください。

import com.bea.dsp.das.DataAccessServiceFactory;
import com.bea.dsp.das.DataAccessService;
import com.bea.dsp.das.DASResult;
import com.bea.dsp.sdo.SDOUtil;
import commonj.sdo.DataObject;
import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.InitialContext;

DataAccessService ハンドルの取得

DataAccessService では、データ サービスのメソッドを呼び出すことができます。このクラスの詳細情報については、Javadoc を参照してください。DataAccessServiceFactory では、ハンドルを返すために 3 つのパラメータが必要です。

コードは以下のとおりです。

    Hashtable<String, String> hash = new Hashtable<String, String>();
    hash.put(Context.INITIAL_CONTEXT_FACTORY,
        "weblogic.jndi.WLInitialContextFactory");
    hash.put(Context.PROVIDER_URL,"t3://localhost:7001");
    hash.put(Context.SECURITY_PRINCIPAL,"weblogic");
    hash.put(Context.SECURITY_CREDENTIALS,"weblogic");
    Context ctx = new InitialContext(hash);

    DataAccessService das = DataAccessServiceFactory.newDataAccessService
    (ctx, "MediatorSamples", "ld:Retail/CUSTOMER");

サービスからのデータの取得

この例では、invoke() メソッドは、データ サービス CUSTOMER オペレーションを呼び出します。このオペレーションは、データ サービスからのすべての顧客オブジェクトを返します。invoke() メソッドは DASResult オブジェクトを返します。このオブジェクトは、反復子と同じように機能します。この戻り値の型の詳細情報については、「DASResult について」を参照してください。CUSTOMER オペレーションには引数はありません。

DASResult<Object> result = das.invoke("CUSTOMER", new Object[0])

結果からの DataObject の取得

DASResult.next() メソッドは、Java method Iterator.next() メソッドと同じように機能します。このメソッドは、結果セットの次のオブジェクトを返します。CUSTOMER データ サービス メソッドは、SDO 準拠 DataObject を返すので、戻り値を DataObject にキャストできます。SDO は、データへのアクセスやデータの更新に使用する、Java ベースのデータ プログラミング モデル (API) およびアーキテクチャです。SDO の詳細については、『ALDSP コンセプト ガイド』の「サービス データ オブジェクト (SDO) の使用」を参照してください。「SDO とは」も参照してください。

DataObject customer = (DataObject) result.next();

結果のオブジェクトの削除

結果オブジェクトを通じて反復するたびに、DASResult.dispose() を呼び出す必要があります。dispose() の詳細については、「結果のオブジェクトの削除」を参照してください。

    result.dispose();

DataObject の変更

DataObject を取得した後それを変更できますが、これらの変更を ALDSP サーバに送信する場合には、変更を行う前に DataObject の変更追跡を有効にする必要があります。SDOUtil.enableChanges() メソッドでは、1 つの DataObject または DataObjects の配列の変更追跡を有効にすることができます。このメソッドの詳細については、「データ オブジェクトの取り扱い」を参照してください。顧客のオブジェクトの変更追跡を有効にすると、顧客オブジェクトの一部の値を変更するために、動的 SDO set() が呼び出されます。SDO メソッドの詳細については、「データ プログラミング モデルと更新フレームワーク」を参照してください。

    SDOUtil.enableChanges(customer);

    customer.set("FIRST_NAME", "DynamicClient");
    customer.set("EMAIL_ADDRESS", "dynamic@example.com");

変更のサーバへの返し

最後に、DataAccessService メソッド invoke() は、CUSTOMER オブジェクトの配列という 1 つのパラメータでデータ サービスの更新メソッドを呼び出します。データ サービス処理は、新たに変更したデータ行をデータベースに更新します。

das.invoke("updateCUSTOMER", new Object[] { customer });

新規 DataObject の作成

この節では、データ サービス Mediator および SDO API を使用して、新しいデータ　オブジェクトを作成し、ALDSP サーバに送信する方法を説明します。前の例と同じように、静的 API と動的 API の両方を説明します。

静的 API を使用して新規 DataObject の作成

コード リスト 3-6 の Java プログラムは、新しい DataObject を作成し、変更して、ALDSP サーバでそれを更新します。

サンプルの設定および実行

コード リスト 3-6 のサンプル コードは、「静的 Mediator アプリケーションのサンプル」に説明したと同じ Java プロジェクトとデータ サービス プロジェクトで動作するように設計されています。ここに表示されたサンプル コードを実行するには、このセクションの設定手順に従います。データ サービスをテストすると、テーブルに新しい行が追加されます。

package com.bea.dsp.sample;

import das.ejb.retail.CUSTOMERDAS;
import retail.customer.CUSTOMER;
import retail.customer.CUSTOMER_KEY;

import com.bea.dsp.das.DASResult;
import com.bea.dsp.sdo.SDOUtil;

import commonj.sdo.helper.HelperContext;
import commonj.sdo.helper.DataFactory;

import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.InitialContext;

public class StaticCreateSample {
    public static void main(String[] args) throws Exception {
        // メディエータの InitialContext を作成します。
        Hashtable<String, String> hash = new Hashtable<String, String>();
        hash.put(Context.INITIAL_CONTEXT_FACTORY,
                 "weblogic.jndi.WLInitialContextFactory");
        hash.put(Context.PROVIDER_URL,"t3://localhost:7001");
        hash.put(Context.SECURITY_PRINCIPAL,"weblogic");
        hash.put(Context.SECURITY_CREDENTIALS,"weblogic");
        Context ctx = new InitialContext(hash);

        // コンテキストと データスペース名で DataAccessService のハンドルを作成します。
        CUSTOMERDAS das = CUSTOMERDAS.getInstance(ctx, "MediatorSamples");

        // このデータスペースに対して SDO HelperContext を取得します。
        HelperContext hctx = das.getHelperContext();
        // 次も使用できます。
        // HelperContext hctx = HelperContextCache.get("MediatorSamples");

        // HelperContext から DataFactory を取得します。
        DataFactory factory = hctx.getDataFactory();

        // スキーマ *type* に名前をつけて
        // 「空」の CUSTOMER DataObject を作成します。スキーマ グロバール要素については、
        // タイプを明示的に指定しない場合、そのタイプ名は、
        // 要素名と同じになります。
CUSTOMER customer = (CUSTOMER) factory.create
            ("ld:Retail/CUSTOMER", "CUSTOMER");

        // この DataObject をその名前と共に提供する必要があります。注意：
        // これは、*type* ではなく、XML スキーマ *name* です。
        // スキーマ グロバール要素については、
        // タイプが明示的に指定しない場合、そのタイプ名は、
        // 要素名と同じになります。
SDOUtil.setElementName(customer, "ld:Retail/CUSTOMER", "CUSTOMER");

        // enableChanges() を使用するこの DataObject の場合、
        //  変更追跡を有効にしないでください。DSP サーバから
        // 元に取得したデータの変更を追跡する場合のみ、
        // 変更追跡を有効にします。

// DataObject のフィールドを設定します。自動生成されたフィールド、たとえば、
        // CUSTOMER_ID を設定されない。省略可能なフィールドまたは
        // デフォルト値で設定されたフィールドを省略します。
        customer.setFIRST_NAME("New First Name");
        customer.setLAST_NAME("New Last Name");
        customer.setCUSTOMER_SINCE("2007-10-18");
        customer.setEMAIL_ADDRESS("first_name@example.com");
        customer.setTELEPHONE_NUMBER("867-5309");

        // DSP に新しい DataObject を設定します。作成機能は、
        // CUSTOMERs の配列を取って、CUSTOMER_KEYs を返します。
        DASResult<CUSTOMER_KEY> result =
            das.createCUSTOMER(new CUSTOMER[] { customer });

        // 返されたキーから新しい顧客 ID を取得できます。また、
        // 任意の DASResults を dispose() メソッドで削除します。
        try {
            CUSTOMER_KEY key = result.next();
            System.out.println("New customer key: " + key.getCUSTOMER_ID());
        }
        finally {
            result.dispose();
        }

        // 作成した DataObject は、
        // 生成されたキー値に基づいて自動的に更新されません。新しい
        //CUSTOMER_ID と一緒に DataObject を表示する場合、
        //再度読み込む必要があります。これは、
        // データ サービス設計者がデータ サービスの getByID() 関数を使用すると、
        // 簡単にできます。
    }
}

パッケージのインポート

このプログラムでは、2 つのクラスが必要です。HelperContext は、SDO ヘルパーの一致するセットのインスタンスにアクセスを提供します。これは、ヘルパー実行コンテキストを表します。このインタフェースのメソッドによって返されたヘルパーのセットは、同じ SDO メータデータを表示できます。つまり、それらが、同じ「スコープ」に実行されます。DataFactory は、DataObjects を作成するためのヘルパーです。作成された DataObjects は、他の DataObjects と接続されません。DataType false および abstract false の型のみ作成できます。

データ アクセス サービス ハンドルの取得

DataAccessService では、データ サービスのメソッドを呼び出すことができます。このクラスの詳細情報については、Javadoc を参照してください。静的 静的 Mediator API については、 DataAccessService (DAS) クラスには、ハンドルを返すために getInstance() というファクトリ メソッドがあります。

getInstance() メソッドには、ハンドルを返すために 2 つのパラメータがある必要があります。

    Hashtable<String, String> hash = new Hashtable<String, String>();
    hash.put(Context.INITIAL_CONTEXT_FACTORY,
        "weblogic.jndi.WLInitialContextFactory");
    hash.put(Context.PROVIDER_URL,"t3://localhost:7001");
    hash.put(Context.SECURITY_PRINCIPAL,"weblogic");
    hash.put(Context.SECURITY_CREDENTIALS,"weblogic");
    Context ctx = new InitialContext(hash);

    CUSTOMERDAS das = CUSTOMERDAS.getInstance(ctx, "MediatorSamples");

DataFactory の作成

DataFactory を作成するには、まず、データスペースの HelperContext オブジェクトを取得する必要があります。

    HelperContext hctx = das.getHelperContext();

    DataFactory factory = hctx.getDataFactory();

HelperContext を返すには、次の呼び出しも使用できます。

    HelperContext hctx = HelperContextCache.get("MediatorSamples");

DataObject の作成および名前の割り当て

DataObject を作成した後、明示的に名前をつける必要があります。factory.create() メソッドには、2 つのパラメータがあります。1 つ目のパラメータは、URI で、データ サービスのデータスペース プロジェクトの場所を示します。2 つ目のパラメータは、作成する DataObject の XML スキーマ型です。スキーマ グローバル要素については、型を明示的に指定しない場合、その型名は、要素名と同じになります。

CUSTOMER customer = (CUSTOMER) factory.create("ld:Retail/CUSTOMER", "CUSTOMER");

次に、新しい DataObject に名前をつけて提供する必要があります。SDOUtil.setElementName() メソッドは、DataObject、要素 QName のネームスペース URI、および要素 QName のローカルの部分というパラメータを取ります。

これは、型ではなく、XML スキーマ名です。ただし、前に記載したとおり、型を指定しないグローバル要素は、提供した型の名前は要素の名前と同じです。

SDOUtil.setElementName(customer, "ld:Retail/CUSTOMER", "CUSTOMER");

DataObject の変更

新しい DataObject を作成した後、サーバに送信する前に変更できます。

customer.setFIRST_NAME("New First Name");
customer.setLAST_NAME("New Last Name");
customer.setCUSTOMER_SINCE("2007-10-18T12:27:41Z");
customer.setEMAIL_ADDRESS("first_name@example.com");
customer.setTELEPHONE_NUMBER("867-5309");

新規 DataObject のサーバへの返し

新しいオブジェクトを作成した後、静的 Mediator API から createCUSTOMER というデータ サービス処理を呼び出します。データ サービスの作成処理は、入力としてオブジェクトの配列を取ります。Mediator API メソッドは、DASResult に CUSTOMER_KEY オブジェクトを返します。

DASResult<CUSTOMER_KEY> result = das.createCUSTOMER(new CUSTOMER[] { customer });

新規 DataObject キーの返し

新しい CUSTOMER オブジェクトの CUSTOMER_KEY を返すには、DASResult オブジェクトの next() メソッドを呼び出します。DASResult オブジェクト (結果) が返された後、それを削除する必要があります。dispose() の呼び出しを try/finally ブロックに削除する、という方法をお勧めします。

try {
    CUSTOMER_KEY key = result.next();
    System.out.println("New customer key: " + key.getCUSTOMER_ID());
    }
finally {
    result.dispose();
}

動的 API を使用して新規 DataObject の作成

コード リスト 3-6 の Java プログラムは、新しい DataObject を作成し、更新して、ALDSP サーバに更新します。

サンプルの実行

コード リスト 3-7 のサンプル コードは、「動的 Mediator アプリケーションのサンプル」に説明したと同じ Java プロジェクトとデータ サービス プロジェクトに動作するように設計されています。ここに表示されたサンプル コードを実行するには、このセクションの設定手順に従います。

package com.bea.dsp.sample;

import com.bea.dsp.das.DataAccessService;
import com.bea.dsp.das.DataAccessServiceFactory;
import com.bea.dsp.das.DASResult;
import com.bea.dsp.das.HelperContextCache;
import com.bea.dsp.sdo.SDOUtil;

import commonj.sdo.helper.HelperContext;
import commonj.sdo.helper.DataFactory;
import commonj.sdo.DataObject;

import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.InitialContext;

public class DynamicCreateSample {
    public static void main(String[] args) throws Exception {
        // メディエータの InitialContext を作成します。
        Hashtable<String, String> hash = new Hashtable<String, String>();
        hash.put(Context.INITIAL_CONTEXT_FACTORY,
                 "weblogic.jndi.WLInitialContextFactory");
        hash.put(Context.PROVIDER_URL,"t3://localhost:7001");
        hash.put(Context.SECURITY_PRINCIPAL,"weblogic");
        hash.put(Context.SECURITY_CREDENTIALS,"weblogic");
        Context ctx = new InitialContext(hash);

        // このデータスペースの場合、SDO HelperContext を取得します。StaticCreateSample
        // と同じように、これを DataAccessService から
        // 取得できました。ただし、
        // DataAccessService インスタンスを作成する前に、all-new DataObject の
        // 作成方法は次に示します。この場合は、
        // 動的メディエータを使用しているので、
        //使用しているデータ サービスのスキーマでグローバル HelperContext キャッシュを表示するかどうかを
        // 確認する必要があります。
HelperContextCache.loadSchemasForDataspace
            (ctx, "MediatorSamples", "ld:Retail/CUSTOMER");

        // スキーマがロードされたので、
        // データスペースの HelperContext を取得できます。
        HelperContext hctx = HelperContextCache.get("MediatorSamples");

        //HelperContext から DataFactory を取得します。
        DataFactory factory = hctx.getDataFactory();

        // スキーマ *type* に
        // 名前をつけて「空」の CUSTOMER DataObject を作成します。スキーマ グロバール要素については、
        // タイプが明示的に指定しない場合、そのタイプ名は、
        // 要素名と同じになります。
DataObject customer = factory.create("ld:Retail/CUSTOMER", "CUSTOMER");

        // この DataObject をその独自の名前で提供する必要があります。注意：
        // これは、*type* ではなく、XML スキーマ *name* です。
        // スキーマ グロバール要素については、
        // タイプを明示的に指定しない場合、そのタイプ名は、
        // 要素名と同じになります。
SDOUtil.setElementName(customer, "ld:Retail/CUSTOMER", "CUSTOMER");

        // enableChanges() を使用するこの DataObject の場合、
        //  変更追跡を有効にしてはいけません。DSP サーバから
        // 元に取得したデータの変更を追跡する場合のみ、
        // 変更追跡を有効にします。

// DataObject のフィールドを設定します。自動生成されたフィールド、たとえば、
        // CUSTOMER_ID を設定されない。省略可能なフィールドまたは
        // デフォルト値で設定されたフィールドを省略します。
        customer.set("FIRST_NAME", "Dynammic");
        customer.set("LAST_NAME", "Mediator");
        customer.set("CUSTOMER_SINCE", "2007-10-18");
        customer.set("EMAIL_ADDRESS", "dynamic@example.com");
        customer.set("TELEPHONE_NUMBER", "867-5309");

        // コンテキストと データスペース名で DataAccessService のハンドルを作成します。
        DataAccessService das = DataAccessServiceFactory.newDataAccessService
            (ctx, "MediatorSamples", "ld:Retail/CUSTOMER");

        // DSP に新しい DataObject を送信します。作成機能は、
        // CUSTOMERs の配列を取って、CUSTOMER_KEYs を返します。
        DASResult<Object> result =
            das.invoke("createCUSTOMER", new Object[] { customer });

        // 返されたキーから新しい顧客 ID を取得できます。取得する
        // 任意の DASResults を dispose() メソッドで削除します。
        try {
            DataObject key = (DataObject) result.next();
            System.out.println("New customer key: " + key.get("CUSTOMER_ID"));
        }
        finally {
            result.dispose();
        }

        // 作成した DataObject は、
        // 生成されたキー値に基づいて自動的に更新されません。新しい
        //CUSTOMER_ID と一緒に DataObject を表示する場合、
        //再度読み込む必要があります。これは、
        // データ サービス設計者がデータ サービスの getByID() 関数を使用すると、
        // 簡単にできます。
    }
}

パッケージのインポート

このプログラムでは、3 つのクラスが必要です。DataObject は、いくつかの構造化されたデータの表現です。これは、SDO (サービス データ オブジェクト) パッケージ内の基本的なコンポーネントです。HelperContext は、SDO ヘルパーの一致するセットのインスタンスにアクセスを提供します。これは、ヘルパー実行コンテキストを表します。このインタフェースのメソッドによって返されたヘルパーのセットは、同じ SDO メータデータを表示できます。つまり、それらが、同じ「スコープ」に実行されます。DataFactory は、DataObjects を作成するためのヘルパーです。作成された DataObjects は、他の DataObjects と接続されません。DataType false および abstract false の型のみ作成できます。

また、この例では、com.bea.dsp.das.HelperContextCache クラスが使用され、ALDSP によって管理された SDO HelperContext オブジェクトのグローバル キャッシュにアクセスを提供します。HelperContextCache の使用については、次の節「DataFactory の作成」に説明します。

DataFactory の作成

前に説明した静的メディエータの例と同じように、このデータスペースの SDO HelperContext を取得する必要があります。この静的例では、DataAccessService から HelperContext が作成されます。ただし、DataAccessService のインスタンスを作成する前に、新しいDataObject を作成します。そのためには、グローバル HelperContext キャッシュがデータ サービス スキーマで表示する必要があります。

HelperContextCache.loadSchemasForDataspace
    (ctx, "MediatorSamples", "ld:Retail/CUSTOMER");
    // スキーマがロードされたので、データスペースの HelperContext を取得できます。
    HelperContext hctx = HelperContextCache.get("MediatorSamples");

    DataFactory factory = hctx.getDataFactory();

DataObject の作成および名前の割り当て

DataObject を作成した後、明示的に名前をつける必要があります。factory.create() メソッドには、2 つのパラメータがあります。1 つ目のパラメータは、URI で、データ サービスのデータスペース プロジェクトの場所を示します。2 つ目のパラメータは、作成する DataObject の XML スキーマ型です。スキーマ グロバール要素については、型を明示的に指定しない場合、その型名は、要素名と同じになります。

DataObject customer = factory.create("ld:Retail/CUSTOMER", "CUSTOMER");

次は、新しい DataObject を名前をつけて提供する必要があります。SDOUtil.setElementName() メソッドは、DataObject、要素 QName のネームスペース URI、および要素 QName のローカルの部分というパラメータを取ります。

これは、型ではなく、XML スキーマ名です。ただし、前に記載したとおり、型を指定しないグローバル要素は、提供した型の名前は要素の名前と同じです。

SDOUtil.setElementName(customer, "ld:Retail/CUSTOMER", "CUSTOMER");

DataObject の変更

新しい DataObject を作成した後、サーバに送信する前に変更できます。

    customer.set("FIRST_NAME", "New First Name");
    customer.set("LAST_NAME", "New Last Name");
    customer.set("CUSTOMER_SINCE", "2007-10-18T12:27:41Z");
    customer.set("EMAIL_ADDRESS", "first_name@example.com");
    customer.set("TELEPHONE_NUMBER", "867-5309");

新規 DataObject のサーバへの返し

データ サービスのメソッドを呼び出すには、DataAccessService ハンドルが必要です。DataAccessService では、データ サービスのメソッドを呼び出すことができます。このクラスの詳細情報については、Javadoc を参照してください。DataAccessServiceFactoryには、ハンドルを返すために 3 つのパラメータがある必要があります。

DataAccessServiceFactory はハンドルを返します。

    // コンテキストとデータスペース名で DataAccessService ハンドルを作成します。
    DataAccessService das = DataAccessServiceFactory.newDataAccessService
    (ctx, "MediatorSamples", "ld:Retail/CUSTOMER");

DataAccessService.invoke() メソッドを使用して、サーバの createCUSTOMER データ サービス処理が呼び出されます。createCUSTOMER データ サービス処理は、入力としてオブジェクトの配列を取るように設計されています。関数は、DASResult に CUTOMER_KEYS オブジェクトを返します。

    DASResult<Object> result =
        das.invoke("createCUSTOMER", new Object[] { customer });

新規 DataObject キーの返し

新しい CUSTOMER オブジェクトのキーを返すには、DASResult オブジェクトの next() メソッドを呼び出します。DASResult オブジェクト (結果) が返された後、それを削除する必要があります。dispose() の呼び出しを try/finally ブロックに削除する、という方法をお勧めします。

try {
    DataObject key = (DataObject) result.next();
        System.out.println("New customer key: " + key.get("CUSTOMER_ID"));
    }
finally {
    result.dispose();
}

Mediator API の基礎

この節では、さまざまな Mediator API トピックについて説明します。

サンプル アプリケーション

この章で取り上げたサンプル アプリケーションを確認して実行することをお勧めします。

サンプル コードは基本的なものですが、データの取得、変更、更新のために共通で使用されるケースを示しています。サンプル コードでは、コードを理解するためにその詳細についても説明しています。

この章の残りの部分は、API の詳細機能に加え、高度なトピックおよび重要な参照資料についても説明します。

静的 Mediator API の詳細情報

静的 Mediator API を使用して呼び出すと、empty() または単一の項目を返すデータ サービス処理は、DASResult を返しません。代わりに、void または単一の項目を返します。「DASResult について」を参照してください。

動的 Mediator API の詳細情報

この節では、動的 Mediator APIの詳細について説明します。

データ サービス操作の呼び出し

invoke(String メソッド、Object[] args) メソッドは、データ サービス処理を動的に呼び出します。処理を呼び出すと (たとえば、getCustomerByCustID())、DASResult オブジェクトが返されます。すべてのデータ サービスの関数を動的 Mediator API を使用して呼び出すと、DASResult を返します。「DASResult について」を参照してください。

コード リスト 3-5、DynamicSampleApp.java の動的 Mediator API のサンプルに invoke() メソッドが使用されています。

  DASResult<Object> result = das.invoke("updateCustomer", new Object[0]);

invoke() メソッドの詳細については、e-docs の Javadoc を参照してください。

ゲッターおよびセッター

SDO では、データ オブジェクトで利用するための一般的なゲッターとセッターがあります。SDO API は、開発時にデプロイされていなかったデータ型と共に使用することができます。XPath 式が引数として汎用メソッドに渡されます。次に例を示します。

customer.set("EMAIL_ADDRESS", "first_name@example.com");

または

String name = customer.get("EMAIL_ADDRESS");

「引数として XPath 式の指定」および「データ プログラミング モデルと更新フレームワーク」も参照してください。

生成されたクラスの命名規約

Mediator クライアント JAR ファイルまたは Web サービス Mediator クライアント JAR ファイルを生成すると、次の命名規約に従って、生成された DataAccessService サブクラスおよびパッケージに名前をつけます。

Mediator クライアント JAR の命名規約

生成された DataAccessService サブクラス名は、<Data_Service_Name>DAS.class になります。たとえば、Customer.ds というデータ サービスから Mediator クライアント JAR ファイルを作成すると、JAR ファイルに CustomerDAS.class というクラスが生成されます。パッケージ名には、das.ejb が含まれています。

Web サービス Mediator クライアント JAR の命名規約

生成された DataAccessService サブクラス名は、<Data_Service_Name>DAS.class になります。たとえば、Customer.ws という Web サービス マップ ファイルから Web サービス Mediator クライアント JAR ファイルを作成すると、JAR ファイルに CustomerDAS.class というクラスが生成されます。パッケージ名には、das.ws が含まれています。

DASResult について

データ セットを返す Mediator API は、DASResult (Data Access Service Result) というオブジェクトを返します。DASResult は Java Iterator と同じです。

この節の内容は以下のとおりです。

DASResult の概要

デフォルトで、データは、小さいブロックでメディエータから ALDSP サーバに返されます。この「ストリーミング」動作は、すべての大きな結果セットが、ALDSP サーバまたはクライアント アプリケーションのメモリに存在していないことを示します。これにより、メモリの使用が最適化されます。ただし、この場合は、すべての結果がクライアントに返されるまで、サーバのリソースをオープンしておく必要があります。「ステートレス操作のサポート」を参照してください。

invoke() メソッド用のシグネチャの例を以下に示します。

DASResult<Object> invoke(String operation, Object[] args) throws DASException;

反復子オブジェクトと同じように、DASResult は転送専用です。前の項目を返す方法または反復を再起動する方法はありません。

DASResult には、次の標準 Java 反復子メソッドがあります。

DASResult オブジェクトのすべての複雑な XML 項目が DataObjects として表現されます。結果のすべての簡単な項目 (ライブラリ データ サービス処理から返されることができる項目) が、Integer、Long など対応する Java オブジェクトによって表現されます。型のスキーマ型へのマッピング方法については、「データ サービス型の Java 型へのマッピング」を参照してください。「アド ホック クエリの作成」も参照してください。

DASResult オブジェクトの削除

コードによってすべての結果を反復処理するまで、サーバーのデータベース ハンドルなどリーソースをオープンしておく必要があります。したがって、サーバにリソースをリリースするように通知するために返された DASResult オブジェクトを削除する必要があります。

DASResult には、以下のメソッドがあります。

void dispose() - ALDSP サーバの DASResult によって必要なリソースを削除します。

boolean isDisposed() - ALDSP サーバへの接続が切れたかどうかを返します。

dispose() メソッドは、以下の 2 つの場合に自動的に呼び出されます。

動的 Mediator API および DASResult

XQuery 結果を返すすべての動的 Mediator API メソッドは、DASResult オブジェクトを返します。このメソッドには以下があります。

静的 Mediator API および DASResult

動的 Mediator API では、複数の結果を持つデータ サービス処理に対して生成されたすべてのメソッドを宣言して、DASResult<T> を返します。複数の結果は、XQuery 戻り値の型が type* (型のセロまたは複数のインスタンス) または type+ (型の 1 つまたは複数インスタンス) であるデータ サービス処理の結果です。T は、DataObjects のクラスで、DASResult.next() によって返されます。

最大 1 つの戻り値の型を持つデータ サービス処理に対して生成されたメソッド (たとえば、 XQuery 戻り値の型が type または type? であるデータ サービス処理) を宣言して、DASResult オブジェクトではなく、対応する Java 型が直接返されます。さらに、戻り値の型が empty() であるデータ サービス処理は、void 型の戻り値で静的メディエータメソッドを生成します。詳細については、「データ サービス型の Java 型へのマッピング」を参照してください。

オブジェクトの配列の取得

DASResult には、T[] getItems() というメソッドがあります。このメソッドは、配列として結果を返します。このメソッドは、すぐに DASResult を廃棄します。「DASResult オブジェクトの削除」を参照してください。

ALDSP 用の WebLogic JNDI コンテキストの取得

Java クライアント アプリケーションは、WebLogic Server 上では、JNDI を使用してデータ サービスなどの名前付きのオブジェクトにアクセスします。任意の Mediator API を使用するには、ALDSP 用の WebLogic JNDI コンテキストを取得する必要があります。このコンテキストを取得すると、mediator API が、データ サービス処理を呼び出し、データ サービスから情報を取得できます。WebLogic JNDI コンテキスト オブジェクトの詳細については、e-docs の「WebLogic JNDI プログラマーズ ガイド」を参照してください。

JNDI コンテキストを取得するには、次の呼び出しを使用します。次に、hashtable パラメータについて説明します。

InitialContext jndiCtxt = new InitialContext(hashtable);

表 3-5 には、hashtable パラメータに挿入できるキーおよび値を示します。

コード リスト 3-8 には、JNDI コンテキストを取得コードの例を示します。

Hashtable h = new Hashtable();
   h.put(Context.INITIAL_CONTEXT_FACTORY,
   "weblogic.jndi.WLInitialContextFactory");
   h.put(Context.PROVIDER_URL,"t3://machinename:7001");
   h.put(Context.SECURITY_PRINCIPAL,<username>);
   h.put(Context.SECURITY_CREDENTIALS,<password>);
  InitialContext jndiCtxt = new InitialContext(h);

データ オブジェクトの取り扱い

Mediator API を使用してデータ サービス処理を呼び出すと、SDO 準拠 データ オブジェクトが DASResult オブジェクトの返されます。(「DASResult について」を参照してください。)

この節では、Java クライアントのコンテキスト内でデータ オブジェクトの取り扱いについて説明します。SDO データ オブジェクトおよび SDO API の詳細については、「データ プログラミング モデルと更新フレームワーク」を参照してください。

変更追跡のためにデータ オブジェクトの有効化

DataObject を変更する前に、それを変更追跡のために有効化する必要があります。そのためには、DataObject を com.bea.dsp.sdo.SDOUtil.enableChanges() メソッドに渡します。次に例を示します。

SDOUtil.enableChanges(customer); 

enableChanges() には、2 つの形式があります。1 つ目は、DataObject を取り、2 つ目は、DataObjects の配列を取ります。

com.bea.dsp.sdo.SDOUtil.enableChanges(DataObject);

com.bea.dsp.sdo.SDOUtil.enableChanges(DataObject[]);

データ オブジェクト プロパティの変更

DataObject を enableChanges() に渡した後、標準 SDO API を使用して、DataObject に許可される変更を行うことができます。SDO API インタフェースの詳細については、「データ プログラミング モデルと更新フレームワーク」を参照してください。

SDO は、静的 (型付き) および動的 (型なし) インタフェースを提供します。詳細については、「静的 データ オブジェクト API」および「動的 データ オブジェクト API」を参照してください。

静的 (型付き) メソッド呼び出しの例は以下に示します。

    customer.setFIRST_NAME("New First Name");

動的 (型なし) メソッド呼び出しの例は以下に示します。

    customer.set("FIRST_NAME", "New First Name");

SDO オブジェクトを変更、修正に対して有効化した後、更新メソッドに引数として渡すことができます。その後、ALDSP は更新の詳細を取り扱うことができるようになります。たとえば、「コード リスト 3-4、StaticSampleApp.java」を参照。

das.updateCUSTOMER(new CUSTOMER[] { customer });

新規データ オブジェクトの作成

API を使用して、新規データ オブジェクトを作成できます。RDBMS では、これを新規レコードの作成と見なしています。Data object の作成は、高度なトピックです。詳細については、「新規 DataObject の作成」を参照してください。

データ サービス型の Java 型へのマッピング

この節では、Mediator API によって、データ サービス型の Java 型へのマッピングの方法について説明します。たとえば、静的 Mediator API 作成者は、Mediator クライアント JAR ファイルを作成するときにこれらの変換を行います。この節では、Mediator API メソッドに渡された引数型の対応する XQuery 型へのマッピングについても説明します。

この節の内容は以下のとおりです。

単純型の変換

表 3-6 には、Mediator APIを使用して単純 XQuery 型の Java 型への変換方法を示します。たとえば、xs:int を返すデータ サービス処理は、Java メソッドを生成します。このメソッドが Java の Integer オブジェクトを返します。xs:int* (ゼロまたは複数 int) を返す処理は、DASResult<Integer> オブジェクトを返します。(「静的 Mediator API および DASResult」も参照してください。)

日付/時間型の変換

mediator API では、日付/時間型の変換方法は、SDO 仕様と一致します。SDO for Java Specification V2.1 では、すべての日付/時間の値が、Java 文字列にマッピングされます。オンライン仕様は次のサイトで見ることができます。www.osoa.org/display/Main/Service+Data+Objects+Specifications。

空シーケンス引数の渡し

データ サービス処理は省略可能な引数 (たとえば、CUSTOMER?) を取ると、静的または動的 Mediator メソッドに NULL パラメータを渡すことができます。次の場合には、NULL パラメータを渡すことができます。

数値化した戻り値の型

静的 Mediator API では、データ サービスからの数値化した戻り値の型は、以下のルールに基づいて生成されます。

* または + (たとえば、xx:int*) で数値化した任意のデータ サービス パラメータの場合、静的 mediator メソッドがあります。それらのメソッドが、DASResult<type> を返すために宣言されます。

たとえば、次のシグネチャのデータ サービス処理

    declare function t1:someFunc($a as xs:int*, $b as xs:double+) as xs:int*
    external;

は、以下のようなメソッドに変換されます。

    DataObject<java.lang.Integer> someFunc(Integer[] a, Double[] b); 

Data service operations that return 数値化されないまたは ?-数値化された型を返すデータ サービス処理の場合、静的 mediator メソッドがあります。それらのメソッドが、型を直接返すために宣言されます。? の場合、処理の結果は型の 0 インスタンスであり、静的 mediator メソッドは NULL を返すことを示します。

Autoboxing とは

Autoboxing は、Java 1.5 言語の機能であり、Java プリミティブ型lおよびそのオブジェクト ラッパの場合、コードを単純化することができます。Autoboxing は、Integer およびそのプリミティブ countertypes などオブジェクト ラッパの間に自動的にキャストを行います。たとえば、autoboxing では、 Mediator API メソッドから返された Integer オブジェクトを数式に使用して、Integer オブジェクトを取る Mediator API メソッドに int を渡すことができます。autoboxing の詳細については、『Sun Java マニュアル』を参照してください。

コード リスト 3-9 では、DASResult から取得されたInteger オブジェクトは、int に自動キャストされます。

CustomerDAS custdas = CustomerDAS.getInstance(..);
// xs:int* を返す 0 引数プロシージャの呼び出す。
DASResult<Integer> result = custdas.getIDs();
while (result.hasNext()) {
    int cust = result.next(); // autoboxing を使用しない
}
result.dispose();

Web サービスのサポート

ALDSP のネイティブ web サービス機能を使用すると、データ サービスを web サービスに直接マップすることができます。クライアント側のアプリケーションでは、Mediator APIを使用して、web サービスを通じてデータにアクセスできます。動的 Mediator API と静的 Mediator API の両方が、ネイティブ web サービスをサポートします。ネイティブ web サービス機能の詳細については、「Web サービスを通じてデータ サービスの呼び出し」を参照してください。

高度なトピック

この節の内容は以下のとおりです。

スキーマの管理

SDO は、スキーマの管理に役に立つ一連の API を提供します。これらの API には、以下のものが含まれます。

スキーマのスコープ

HelperContext オブジェクトは、スコープの SDO コンセプトを表します。特定の XSDHelper にロードされたすべてのスキーマを利用可能であり、同じ HelperContext の XMLHelper または DataFactory から DataObjects を作成するときに使用されます。

データスペースは、スキーマのスコープの基本単位を表します。データスペースには、型の衝突があるスキーマが含まれません。

web サービス ベースのメディエータの場合、WSDL によってスコープが定義されます。All schemas necessary for all operations in a WSDL のすべての処理のために必要なスキーマは、WSDL に含まれているので、WSDL 自体は、スキーマの適度なスコープになります。詳細については、「Web サービスを通じてデータ サービスの呼び出し」を参照してください。

Mediator は、HelperContexts のグローバル キャッシュを保持します。そのキャッシュのキーは、データスペース名であるか、または、web サービスの場合、WSDL の URL です。処理の戻り値に対して新しい DataObjects を作成するとき、Mediator は、Dataspace/WSDL に適した HelperContext を自動的に使用します。指定した Dataspace/WSDL の HelperContext を取得し、独自の DataObjects の作成、型システムのクエリなどに使用します。HelperContext API の詳細については、「スキーマ キャッシュ管理」を参照してください。

スキーマのダウンロード

この節では、データ サービスおよび WSDL (web サービス) からインスタンス化された DataAccessService オブジェクトのスキーマのダウンロード処理について説明します。

スキーマがすでにロードされていない場合のみ、ロードされます。メディエータにスキーマをダウンロードしないように要求する newDataAccessService() メソッドに対して省略可能なブール フラグを設定できます。次の節に説明したメソッドまたは SDO XSDHelper メソッドを使用して手動でスキーマをダウンロードしようとした場合、このフラグを使用します。

スキーマ キャッシュ管理

次のメソッドを使用して、HelperContexts のメディエータ キャッシュをクエリと処理します。これらは、com.bea.dsp.das.HelperContextCache クラスの静的メソッドです。

ステートレス操作のサポート

デフォルトで、Mediator API は、データが返されるまで、ALDSP サーバのリソースを開いて置きます。「DASResult について」に説明したとおり、データ オブジェクトが、DASResult を通じて 一つずつ返されます。ALDSP では、この方式は、「ステートフル」と呼ばれます。

一般に、ステートフル処理が望ましいです。ステートフル行動では、クライアント側とサーバ側のメモリの利用を最小限にすることができます。どうしても必要な場合のみ、ALDSP サーバのリソースをオープンしておきます。クライアントは、サーバにデータを転送する必要がある場合のみ以外はネットワーク ラウンドトリップを使用しません。

ただし、場合によっては、クライアントがただ一回のネットワーク ラウンドトリップを使用することを保障する場合もあります。たとえば、ALDSP へのネットワーク接続の遅延が大きく信頼性が低い場合、一回のネットワーク ラウンドトリップによって応答時間が短縮され、サーバ上のリソースが必要以上にオープンされたままになる可能性がなくなります。

デフォルト ステートフル動作をオーバーライドして、すぐに結果を返すには、RequestConfig flag FETCH_ALL_IMMEDIATELY を使用します。このフラグを指定した場合、Mediator は、ただ一回のネットワーク ラウンドトリップを使用してすべての結果を取得します。さらに、サーバのリソースを直ちにクローズします。

このフラグを有効にした場合、DASResult を返すすべてのメソッドは、「結果オブジェクトの削除」で説明したとおり、すでに廃棄されたものを返します。

FETCH_ALL_IMMEDIATELY を使用した場合、DASResult の通常の反復子メソッドを使用するか、一度にすべての結果を読み込むために getItems() を使用することができます。

キャッシュの管理

この節では、Mediator API を通じてデータのキャッシュを管理できる API 機能について説明します。

データ キャッシュの制御的なリードスルーおよび更新

データ サービス処理により取得されたデータは、迅速にアクセスできるようにキャッシュに格納されます。これは、データ キャッシングとして知られます。(詳細については、ADSP 『管理者ガイド』の「クエリ結果キャッシュのコンフィグレーション」を参照してください。)データ変更があまり頻繁になされないと思われる場合は、キャッシュ機能が役立ちます。

RequestConfig.GET_CURRENT_DATA 属性が True に設定されている場合は、以下のようになります。

REFRESH_CACHE_EARLY 属性の設定

RequestConfig.REFRESH_CACHE_EARLY 属性を使用して、データ キャッシュを制御することができます。

RequestConfig.GET_CURRENT_DATA プロパティが有効に設定されていない場合は、RequestConfig.REFRESH_CACHE_EARLY を使用して、関数のデータ キャッシュで使用できる残りの TTL (time-to-live : 生存時間) に基づきキャッシュ データを使用するかどうかをコントロールできます。

REFRESH_CACHE_EARLY 属性は整数型です。これは、RequestConfig.setIntegerAttribute() メソッドを呼び出して設定します。REFRESH_CACHE_EARLY を特定の値に設定するには、使用する前に、キャッシュ レコードに少なくとも n 秒以上の使用可能な TTL が残されている必要があります。レコードの期限が n 秒以内に切れる場合は取得されません。代わりに、この値が基礎となるデータに基づいて再計算され、その関数に関連するデータ キャッシュが更新されます。クエリ評価中は、同一の REFRESH_CACHE_EARLY 値がすべてのキャッシュ オペレーションに適用されます。

引数として XPath 式の指定

ALDSP は、SDO パス式という XPath 式の限定されたサブセットをサポートします。SDO パス式は、動的 データ API アクセサ内のデータ オブジェクトおよび属性を検索する方法に柔軟性がもたらされます。

SDO パスは、セレクタで SDO プロパティ名 (スキーマ/xml の要素/属性名と異なる可能性がある) のみ使用します。割り当てられたエリアス名があれば、それも一致するために使用されます。パスの最後のステップの前の各ステップは、1 つの DataObject を返す必要があります。

次に例を示します。

customer.get("CUSTOMER_PROFILE[1]/ADDRESS[AddressID=\"ADDR_10_1\"]")

例では、指定 addressID を使用して指定したパスで ADDRESS を取得します。要素識別子が複数値の場合は、すべての要素が戻されます。

get() メソッドは、1 つのオブジェクトを返します。式の結果には、isMany というプロパティが設定されている場合、メソッドは、DataObjects のリストを返します。

XPath 表記を伴う get() メソッドを使用すると、親データ オブジェクトを含むデータ オブジェクトを取得できます。

   myCustomer.get("..")

XPath 表記を伴う get() メソッドを使用すると、データ オブジェクトを含むルートを取得できます。

	myCustomer.get("/")

これは、myCustomer.getRootObject() の実行と同様です。

ADSP は、従来のインデックス表記と拡張表記の両方を完全にサポートしています。詳細については、「動的データ オブジェクト API における XPath の式」を参照してください。

アド ホック クエリの作成

DataAccessServiceFactory.prepareExpression() メソッドで、データ サービスに対しアド ホック クエリを作成できます。コード リスト 3-10 には、preparedExpression() メソッドの例を示します。アド ホック クエリの詳細については、「アド ホック クエリを使用したクライアントからの結果の微調整」を参照してください。

PreparedExpression pe = DataAccessServiceFactory.prepareExpression
   (ctx, appname, "18 + 25");
DASResult<Object> result = pe.executeQuery();
int answer = (int) result.next();
result.dispose();

トランザクション動作について

この節では、読み書きおよび読み取り専用の処理およびクエリのトランザクション動作について説明します。

読み取り/書き込み操作のトランザクション動作

ALDSP サーバは、作成、更新または削除など読み書き処理を実行するとき、必要に応じて、新しいトランザクションを作成します。

読み取り専用処理のトランザクション動作

デフォルトで、読み込み処理は、クライアント側で現在にアクティブになっているトランザクションがある場合、そのトランザクションを使用します。ただし、クライアント側でオープンされているトランザクションがない場合、それは作成されません。このデフォルトを変更するには、RequestConfig and passing RequestConfig 上の属性を invoke() へのパラメータとして設定します。(invoke() の詳細については、Javadoc を参照してください。)RequestConfig.ReadTransactionMode の属性で、次のいずれかの値を設定して、読み取り専用の処理のトランザクション動作をコンフィグレーションすることができます。

RequestConfig.setEnumAttribute() メソッドを使用して、ReadTransactionMode 属性を設定します。たとえば、次のコードは、ReadTransactionMode モードを「SUPPORTS」に設定します。

RequestConfig config = new RequestConfig();
config.setEnumAttribute(RequestConfig.ReadTransactionMode.SUPPORTS);