サービスコンポーネントの構造

サービスコンポーネントは、クラスとして実装します。 サービスコンポーネントであることを示すために、@service アノテーションを使用します。SCA ランタイムは、 スクリプトのファイル名にもとづく規約でコンポーネント名を決定します。 したがって、クラス名とスクリプトのファイル名は同じにしておく必要があります。

PHP SCA コンポーネントは常にサービスを公開しています。 コンポーネントは、ウェブサービスへのリクエストの結果としてコールされるか スクリプト内の別のコンポーネントから直接コールされるかのいずれかの方法でしか起動しません。 このため、有効な PHP SCA コンポーネントは常に @service アノテーションを含んでおり、少なくともひとつの public メソッドを持っています。

各 SCA コンポーネントは、SCA.php をインクルードする必要があります。 ここには SCA クラスの定義が含まれているだけでなく、 スクリプトがコールされた際に実行される、 コンポーネントとして振舞うための PHP コードも含まれています。

以下の例で、これらすべての構造について説明します。

別のサービスコンポーネントへのプロキシの取得

ある SCA コンポーネントが、別の SCA コンポーネントのサービスをコールすることができます。 コンポーネントが提供するサービスは、すべて public メソッドでできています。 SCA for PHP では現在、あるコンポーネントから他のコンポーネントをコールする方法を 二通り提供しています。ローカルに (同一の PHP ランタイム、 同一のコールスタック上で) コールする方法と、リモートにコールする方法です。 リモートにコールする場合は、コールされるコンポーネントが ウェブサービスを公開していなければなりません。

あるコンポーネントが別のコンポーネントをコールするには、 呼び出し元のコンポーネント側に呼び出し先コンポーネントへのプロキシが必要です。 このプロキシは、通常は呼び出し元コンポーネントのインスタンス変数として用意します。 しかし、後でご覧いただくように SCA::getService() でプロキシを取得することも可能です。 コンポーネントを作成する際にプロキシを作成し、 別のコンポーネントを参照するインスタンス変数にそのプロキシを "注入 (inject)" します。プロキシは、そのコンポーネントがローカルにあるかリモートにあるかにかかわらず 常に用いられます。これにより、リモートだろうがローカルだろうが同じ方法でコールできるようになります (たとえば、ローカルへのコールの際もデータは常に値渡しとなります)。 プロキシは、そのコンポーネントがある場所と、 それをコールする方法を知っています。

サービスのプロキシを保持することを意図したインスタンス変数は、 PHPDocumentor 形式のふたつのアノテーション @reference および @binding で表します。それぞれのアノテーションは、 クラスのインスタンス変数のコメント部で指定します。以下のコードを参照ください。

インスタンス変数の前にある @reference アノテーションは、 そのインスタンス変数がコンポーネントへのプロキシとして初期化されることを示します。

@binding アノテーションには二通りの形式 @binding.php および @@binding.ws があり、それぞれそのプロキシが ローカルコンポーネント用なのかウェブサービス用なのかを表します。 @binding.php および @binding.ws のいずれの場合も、 対象の URI をアノテーションで指定します。

現時点では依存性の指定をアノテーションで行っているので、 参照先を変更する唯一の方法はコンポーネント内のアノテーションを書き換えることになります。

今回の例の ConvertedStockQuote では、インスタンス変数 $exchange_rate をローカルのコンポーネント ExchangeRate へのプロキシとして初期化しています。これは、 ConvertedStockQuote のインスタンスが作成されるたびに作成されます。

@binding.php の場合の URI は、 そのコンポーネントの実装を含むスクリプトの場所を表します。 コンポーネントはローカルにコールされます。 提供されるサービスは、コンポーネントの public メソッド群となります。 URI は、絶対パスあるいは相対パスで表す単純なパス名でなければなりません。 コンポーネントの読み込みには、PHP の include ディレクティブを使用します。 その際に、既に読み込まれていないかどうかを class_exists() で調べます。URI が相対パスの場合は、 そのアノテーションを含むコンポーネントの場所を基準としてパスを解決します。 これは、通常の PHP の振る舞いとは異なることに注意しましょう。 通常は、PHP は include_path を基準として解決します。 このようにしない理由は、複数コンポーネント間の参照関係を、 できるだけ場所の影響を受けないようにするためです。

この ExchangeRate サービスがリモートにあり、ウェブサービスとしてコールされるものだとすると、 変更するところは @binding の行だけです。PHP クラスの場所を指定するかわりに、 ウェブサービスについて記述した WSDL ファイルの場所を指定します。 今回のサンプルでは、二番目の参照でこの方式を説明しています。

StockQuote コンポーネントはウェブサービスへのリクエストとしてコールされます。 今回の場合は WSDL の URI が単純なパス名となっていますが、 PHP のラッパーを使用して、たとえば file:// や http:// で始めることもできます。 単純にパス指定する場合は絶対パスでも相対パスでもかまいません。 相対パスの場合は、そのアノテーションを含むコンポーネントの位置からの相対パスと解釈されます。 これは @binding.php の振る舞いと同様で、通常の PHP の挙動とは異なることに注意しましょう。 通常は、PHP は現在の作業ディレクトリからの相対パスとして探します。 作業ディレクトリは、通常はそのスクリプトがコールされた場所となります。 このようにしない理由は、複数コンポーネント間の参照関係を、 まずバインド形式の違いに影響を受けないようにすること、 そして場所の影響を受けないようにするためです。

別のサービスコンポーネントのコール

ConvertedStockQuote の例では、これらのプロキシをコールすることで それぞれが参照するコンポーネントを使用しています。

StockQuote サービスのコールはローカルサービスへのコール、 一方 ExchangeRate サービスのコールはリモートサービスへのコールとなります。 それがローカルサービスであるかリモートサービスであるかにかかわらず、 コール方法は同じようになることに注意しましょう。

プロキシを使用することにより、コンポーネントのコール方法や振る舞いが ローカルであろうがリモートであろうが同じものになることが保証されます。 つまり、コンポーネントをコールする際に それがローカルにあるのかリモートにあるのかを気にしなくてもよいということです。 たとえば、ローカルサービスへのプロキシは、 引数をコピーしてそのコピーのみをサービスに渡します。 これにより、リモートコールの場合と同様に引数が値渡しとなることが保証されるわけです。 またリモートサービスへのプロキシは、受け取ったパラメータを SOAP リクエストのプロパティに変換し、戻ってきた内容を通常のパラメータリストに変換します。

上の例では、$ticker および $currency は明らかに PHP のスカラー型です。 コンポーネントには PHP のスカラー型である string、integer、float および boolean を渡すことができます。しかし、構造化されたデータは常に Service Data Objects (SDO) として渡します。 これ以降では、コンポーネントがどのようにして SDO を作成して ローカルコールやウェブサービスコールに渡すのか、 あるいはどのようにしてコンポーネントが返す SDO を作成するのかについて説明します。 PHP SDO プロジェクトのドキュメントに、SDO API の動作原理についての説明があります (SDO のページ を参照ください)。

SCA コンポーネントではないスクリプトからのサービスの指定およびコール

SCA コンポーネントは、インスタンス変数に @reference アノテーションを指定することで他のコンポーネントやサービスのプロキシを取得することができます。 しかし、コンポーネントではないスクリプトの場合はこれは不可能です。 クライアントスクリプトがコンポーネントではない場合は、静的メソッド SCA::getService() を使用して ローカルあるいはリモートサービスのプロキシを取得する必要があります。 getService() メソッドの引数には URI を指定します。 通常は、これはコンポーネントを含むローカル PHP スクリプトの場所か、 あるいは wsdl ファイルの場所となります。また、先ほどの節で説明した @binding アノテーションで指定するものと同じようになります。 つまり、相対 URI はクライアントスクリプトの場所を基準として解決し、 PHP の include_path や現在の作業ディレクトリは使用しません。

たとえば、あるスクリプトで ExchangeRate および StockQuote サービスのプロキシを取得する必要があるが、そのスクリプトがコンポーネントではない場合、 getService() メソッドを次のように使用します。

サービスのメソッドをコールするには、返されたプロキシを使用します。 これはコンポーネント内からコールする場合と同じです。

サービスコンポーネントの、ウェブサービスとしての公開

SCA for PHP は、サービスコンポーネント内のアノテーションから WSDL を作成することができます。これにより、 ウェブサービスとして公開することが簡単にできるようになります。 WSDL の作成に必要な情報を SCA に与えるには、@binding.ws アノテーションを @service アノテーションの下に追加しなければなりません。 そこに、メソッドのパラメータおよび返り値をそれぞれ @param アノテーションおよび @return アノテーションで指定します。 これらのアノテーションを読み込むことで WSDL が作成され、 パラメータの順序や型が WSDL の <schema> セクションの内容を決定します。

SCA for PHP は、常に document/literal でラップされたコンポーネントの WSDL を作成します。これにより、ウェブサービスを公開します。注意してほしいのは、 これは、SCA コンポーネント以外のウェブサービスや 別の形式の WSDL で表されるウェブサービスの使用を妨げるものではないということです。

@param アノテーションで使用できるスカラー型は、 一般的な PHP のスカラー型である boolean、integer、float そして string です。これらは、WSDL において それぞれ同名の XML スキーマ型に変換されます。 以下の例は、ConvertedStockQuote コンポーネントが呼び出す StockQuote サービスをごく平凡に実装したもので、 string および float 型の使用法をご確認いただけます。

このサービスの WSDL は、次のようになります (おそらく、サービスの場所は 'localhost' ではなく別のものになるでしょう)。

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xsi:type="tDefinitions"
    xmlns:tns2="http://StockQuote" xmlns:tns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns3="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" targetNamespace="http://StockQuote">
  <types>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://StockQuote">
      <xs:element name="getQuote">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ticker" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="getQuoteResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="getQuoteReturn" type="xs:float"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </types>

  <message name="getQuoteRequest">
    <part name="getQuoteRequest" element="tns2:getQuote"/>
  </message>
  <message name="getQuoteResponse">
    <part name="return" element="tns2:getQuoteResponse"/>
  </message>
  <portType name="StockQuotePortType">
    <operation name="getQuote">
      <input message="tns2:getQuoteRequest"/>
      <output message="tns2:getQuoteResponse"/>
    </operation>
  </portType>
  <binding name="StockQuoteBinding" type="tns2:StockQuotePortType">
    <operation name="getQuote">
      <input>
        <tns3:body xsi:type="tBody" use="literal"/>
      </input>
      <output>
        <tns3:body xsi:type="tBody" use="literal"/>
      </output>
      <tns3:operation xsi:type="tOperation" soapAction=""/>
    </operation>
    <tns3:binding xsi:type="tBinding" transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
  </binding>
  <service name="StockQuoteService">
    <port name="StockQuotePort" binding="tns2:StockQuoteBinding">
      <tns3:address xsi:type="tAddress" location="http://localhost/StockQuote/StockQuote.php"/>
    </port>
  </service>
</definitions>

<!-- this line identifies this file as WSDL generated by SCA for PHP. Do not remove -->

SCA コンポーネントの配置

PHP SCA コンポーネントを配置するには、特別な方法は必要ありません。 コンポーネントの PHP スクリプトを、 ウェブサーバのドキュメントルート以下の適切なディレクトリに配置するだけです。 これはごく普通の PHP スクリプトと同様です。 スクリプトがコールされると、各コンポーネント内の SCA::initComponent() の行が実行されます。 またウェブサービスのコール、ローカルのコール、 あるいは WSDL へのリクエストに対してコンポーネントが適切に応答するようにします。

ウェブサービスとしてのサービスを提供する SCA コンポーネントの WSDL の取得

ウェブサービスのインターフェイスを公開している (つまり、@binding.ws アノテーションを持っている) SCA コンポーネントは、HTTP リクエストのパラメータに "wsdl" を指定されるとその WSDL 定義を返します。 つまり、WSDL を取得する一般的な方法は、URL の最後に "?wsdl" をつけることです。以下の例では、 file_get_contents() を使用してサービスの WSDL を取得し、それをテンポラリファイルに書き出します。 それをもとにして、サービスへのプロキシを取得します。 もちろん、WSDL をブラウザやその他の方法で取得して、自分でそれを保存することも可能です。

<?php
$wsdl 	= file_get_contents('http://www.example.com/Services/Example.php?wsdl');
file_put_contents("service.wsdl",$wsdl); // wsdl をファイルに書き出します
$service = SCA::getService('service.wsdl'); 
?>

注意: wsdl が xsd をインポートしている場合は、 それを個別に取得する必要があります。

WSDL の作成方法について理解する

SCA for PHP は、@service アノテーションの後に @binding.ws アノテーションを含むコンポーネントについての WSDL を作成します。WSDL を作成するために、SCA はコンポーネントの情報を取得し、各 public メソッドの @param アノテーションおよび @return アノテーションの内容を調べます。 また、コンポーネント内の @types アノテーションの内容も調べます。 @param アノテーションおよび @return アノテーションからの情報を基にして、 WSDL の <types> セクションを構築します。また、@types アノテーションによる別のスキーマファイルの指定は、WSDL 内の <import> 要素に変換されます。

<service name="ConvertedStockQuote"
...
location="http://localhost/ConvertedStockQuote/ConvertedStockQuote.php"/>

<types>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://ConvertedStockQuote">
      <xs:element name="getQuote">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ticker" type="xs:string"/>
            <xs:element name="currency" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="getQuoteResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="getQuoteReturn" type="xs:float"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </types>

データ構造の扱い

SCA コンポーネントが受け渡しできる PHP のスカラー型は boolean、integer、real および string の四種類です。 それ以外のデータ構造を扱う際には、SCA コンポーネントは Service Data Objects (SDO) を使用します。SDO についての詳細は、このマニュアルの SDO のページ を参照ください。 SDO になじみのあるかたならご存知のとおり、 SDO は (XML のモデルのような) 構造化されたデータを扱うのに非常に適しています。 また、リモートコンポーネントやウェブサービスとのデータのやり取りの際に ごく自然にシリアライズすることができます。 データ構造の受け渡しを行う手段としては、現在 SDO のみをサポートしています。 その他の PHP オブジェクトや配列を受け渡しすることはできません。

SCA ランタイムは、データを常に値渡しします。これはローカルコールでも同じです。 そのため、SCA ランタイムは、パラメータリスト中の SDO のコピーを事前に作成します。これはスカラー型の場合と同じです。

<xs:import schemaLocation="PortfolioTypes.xsd"
                      namespace="http://www.example.org/Portfolio"/>

エラー処理

この節では、エラーの処理方法について説明します。 エラーには次の二種類があります。

• SCA の実行時例外。これは、 コンポーネントの実行やリモートサービスとのやりとりの際に問題が発生したことを表すものです。 ネットワークや設定の問題が原因で起こることがあります。

• ビジネスロジックの例外。これは、 プログラマが定義するものです。 PHP の Exception クラスを継承したクラスを作成し、 ビジネスロジックで問題が発生した場合に故意にスローします。

SCA

SCA クラスのほとんどの作業は、SCA コンポーネントにファイル SCA.php をインクルードしたときに行われます。しかし、PHP スクリプトは SCA.php をインクルードしてから SCA クラスの getService() メソッドをコールし、 サービスのプロキシを取得することもできます。 コンポーネントは、これを行う必要はありません。というのも、 インスタンス変数と @reference アノテーションを定義することでプロキシを取得できるからです。

SDO を作成して呼び出し元に返す必要があるコンポーネントは、 データファクトリが必要となります。この目的のために、SCA クラスは createDataObject() メソッドをサポートしています。 これは、コンポーネントの @types アノテーションで定義したモデルに基づいた SDO を作成します。 createDataObject() への引数は、 SDO の XML データアクセスサービスと同じです。

SCA_LocalProxy

getService() に 対象となるローカル PHP コンポーネントを指定してコールすると、 ローカルプロキシが返されます。 ローカルプロキシは、@reference および @binding.php アノテーションで定義されたコンポーネントのインスタンス変数に注入されます。 スクリプトあるいはコンポーネントがローカルプロキシをコールすると、 それが対象のコンポーネント自身に渡されます。

SDO を作成して呼び出し元に返す必要があるコンポーネントは、 データファクトリが必要となります。この目的のために、 SCA_LocalProxy クラスは createDataObject メソッドをサポートしています。 これは、コンポーネントの @types アノテーションで定義したモデルに基づいた SDO を作成します。 createDataObject への引数は、 SDO の XML データアクセスサービスと同じです。

SCA_SoapProxy

getService() に 対象となる WSDL ファイルを指定してコールすると、 SOAP プロキシが返されます。 SOAP プロキシは、@reference および @binding.ws アノテーションで定義されたコンポーネントのインスタンス変数に注入されます。 スクリプトあるいはコンポーネントが SOAP プロキシをコールすると、 それがウェブサービスへの SOAP リクエストに変換され、 PHP の Soap 拡張モジュールの助けを得て対象のコンポーネントに渡されます。

SDO を作成して呼び出し元に返す必要があるコンポーネントは、 データファクトリが必要となります。この目的のために、 SCA_SoapProxy クラスは createDataObject メソッドをサポートしています。 これは、対象の WSDL で定義したモデルに基づいた SDO を作成します。 createDataObject への引数は、 SDO の XML データアクセスサービスと同じです。