SOAPClientオブジェクト
コンポーネント情報 | |
---|---|
version | 8.0.9 |
since | 7.0 |
SOAPClient オブジェクト。
このオブジェクトを利用することにより、XMLやJavaを意識することなく、Webサービスを呼び出すことが可能です。
SOAPClientオブジェクトを利用したWebサービスの呼び出しは、以下の3ステップで実現できます。
●ステップ1 : WSDLを指定して SOAPClientオブジェクトのインスタンスを生成 ・・・ 「コンストラクタ」参照
●ステップ2 : Webサービスを呼び出すソースコードのサンプルを表示 ・・・ 「getSampleCode() 関数」参照
●ステップ3 : Webサービスの呼び出し (ステップ2で出力されたコードをカスタマイズ)
具体的なWebサービス実行方法は、サンプルコード 参照してください。
なお、Webサービスの結果がSOAPフォルトとして返却された場合、SOAPFault オブジェクトが例外としてスローされます。
SOAPFault オブジェクトを捕捉する(=Webサービス・オペレーションの実行ロジック部分をtry/catchで囲む)ことで、 SOAPFault オブジェクトを利用したエラー処理を行う事が可能です。
概要
このオブジェクトは、SOAP/WSDLベースのWebサービスを呼び出すためのオブジェクトです。このオブジェクトを利用することにより、XMLやJavaを意識することなく、Webサービスを呼び出すことが可能です。
SOAPClientオブジェクトを利用したWebサービスの呼び出しは、以下の3ステップで実現できます。
●ステップ1 : WSDLを指定して SOAPClientオブジェクトのインスタンスを生成 ・・・ 「コンストラクタ」参照
●ステップ2 : Webサービスを呼び出すソースコードのサンプルを表示 ・・・ 「getSampleCode() 関数」参照
●ステップ3 : Webサービスの呼び出し (ステップ2で出力されたコードをカスタマイズ)
具体的なWebサービス実行方法は、サンプルコード 参照してください。
なお、Webサービスの結果がSOAPフォルトとして返却された場合、SOAPFault オブジェクトが例外としてスローされます。
SOAPFault オブジェクトを捕捉する(=Webサービス・オペレーションの実行ロジック部分をtry/catchで囲む)ことで、 SOAPFault オブジェクトを利用したエラー処理を行う事が可能です。
注意事項
- SOAPClientオブジェクトは、データバインディング方式に「ADB」を利用したAxis2のスタブを利用しています。 そのため、Axis2が対応していないWebサービスを呼び出すことはできません。
- SOAPClientオブジェクトは、document-literal スタイルの Web サービスに対応しています。
- SOAPClientは、非同期型コールバック形式のWebサービスを実行することはできません。
設定
Application Runtime上の conf/soap-client-config.xml にて、SOAPClientオブジェクトの各種設定が可能です。設定項目 | 概要 | 初期値 |
---|---|---|
mode | SOAPClientのインスタンス生成時に行われるWebサービスのスタブ生成 (=WSDLの解析、Javaスタブ・ソースの生成&コンパイル、および、JavaScriptソースの生成)に関する設定です。 以下の3つの設定が可能です。
|
Once |
work-dir | Webサービスのスタブ、および、WSDLファイルを展開するディレクトリです。 Application Runtimeが展開してできたWEB-INFディレクトリからの相対パスで指定します。 | ファンクションコンテナの自動コンパイル時のクラスファイル出力先ディレクトリ |
javac-encoding | Webサービスのスタブをコンパイルする際のJavaソースの文字コード | UTF-8 |
javac-verbose | Webサービスのスタブをコンパイルする際の詳細情報出力可否設定です。 trueの場合、詳細情報が出力され、falseの場合詳細情報は出力されません。 |
false |
javac-xmx | Webサービスのスタブをコンパイルする際の最大ヒープサイズを設定します。 例えば、 |
false |
wsdl/storage/import-location/suffixes/suffix | スタブ生成に必要なファイルの拡張子を設定します。 パブリックストレージ上に保存されているWSDLファイルを利用する際に必要な設定です。 例えば、あるWSDLファイルで参照している要素が、別のファイルで定義されている場合、その定義ファイルの拡張子をここに設定します。 | 「.xsd」と「.wsdl」 |
wsdl/storage/import-location/sub-dirs/sub-dir | スタブ生成に必要なファイルが格納されているディレクトリ名の設定です。 パブリックストレージ上に保存されているWSDLファイルを利用する際に必要な設定です。 例えば、あるWSDLファイルで参照している要素が、別のファイルで定義されている場合、 そのファイルが保存されているディレクトリ名をここに設定します。 WSDLファイルが保存されているディレクトリのサブディレクトリ名として利用されます。 | 「xsd」 |
サンプルコード
サンプル |
---|
1: var wsdlFileURL = "http://localhost:8080/imart/services/SampleMemberInfoOperatorService?wsdl"; 2: 3: var wsUserID = "ueda"; 4: var wsPassword = "ueda"; 5: var wsLoginGroupID = "default"; 6: 7: /** 8: * SOAPClientオブジェクトを利用してWebサービスを呼び出すサンプルです。 9: */ 10: function init(args){ 11: add(); 12: findAll(); 13: } 14: 15: /** 16: * メンバー情報を追加します。 17: */ 18: function add(){ 19: 20: //************************************************************** 21: // ステップ1:WSDLを指定して SOAPClientオブジェクト のインスタンスを生成 22: //************************************************************** 23: try { 24: var soapClient = new SOAPClient(wsdlFileURL); 25: Debug.print("ステップ1 完了"); 26: } 27: catch(ex) { 28: Debug.browse("エラーが発生しました。", ex); 29: } 30: 31: 32: //************************************************************** 33: // ステップ2:Webサービスを呼び出すソースコードのサンプルを表示 34: //************************************************************** 35: var sampleCode = soapClient.getSampleCode("add"); 36: var msg = "ステップ2 完了。" + "\n"; 37: msg += "Webサービスを呼び出すソースコードのサンプルが表示されました。" + "\n"; 38: msg += "pages/src/sample/web_service/client/member_info_operator_client.jsの35, 40行目を" + "\n"; 39: msg += "コメントアウトしてステップ3を実行してください"; 40: Debug.browse(msg, sampleCode); 41: 42: 43: //************************************************************** 44: // ステップ3: Webサービスの呼び出し (ステップ2で出力された内容をカスタマイズ) 45: //************************************************************** 46: // ↓↓↓↓ コピー&ペースト (ここから) ↓↓↓↓ 47: //------------------------------- 48: // Sample Data : 'wsUserInfo' 49: //------------------------------- 50: var wsUserInfo = 51: /* Object <WSUserInfo> */ 52: { 53: /* String */ 54: "password" : WSAuthDigestGenerator4WSSE.getDigest(wsUserID, wsPassword) , 55: 56: /* String */ 57: "authType" : WSAuthDigestGenerator4WSSE.getAuthType(), 58: 59: /* String */ 60: "userID" : wsUserID, 61: 62: /* String */ 63: "loginGroupID" : wsLoginGroupID 64: }; 65: 66: //------------------------------- 67: // Sample Data : 'member' 68: //------------------------------- 69: var member = 70: /* Object <Member> */ 71: { 72: /* Boolean */ 73: "married" : true, 74: 75: /* Number */ 76: "age" : 123, 77: 78: /* String */ 79: "name" : "prop_name", 80: 81: /* String */ 82: "id" : "prop_id", 83: 84: /* Array <Member[]> */ 85: "children" : [ 86: 87: ], 88: 89: /* Date (Thu Jun 19 2008 12:34:56 GMT+0900 (JST)) */ 90: "birthDate" : new Date(1213846496000) 91: }; 92: // ↑↑↑↑ コピー&ペースト (ここまで) ↑↑↑↑ 93: 94: 95: //------------------------------- 96: // Webサービスの呼び出し 97: //------------------------------- 98: try{ 99: var result = soapClient.add(wsUserInfo, member); 100: } 101: catch(soapFault){ 102: Debug.browse("エラーが発生しました。", soapFault); 103: } 104: 105: Debug.browse("ステップ3 完了", 106: "追加しました。", 107: "結果:" + result); 108: } |
コンストラクタの概要
SOAPClient (String wsdlUrl , String [serviceName] , String [portName] , String [endpoint] ) WSDLを URL文字列 で指定するコンストラクタ。 |
SOAPClient (File wsdlOnAppRuntime , String [serviceName] , String [portName] , String [endpoint] ) WSDLを File# オブジェクトで指定するコンストラクタ。 |
SOAPClient (PublicStorage wsdlOnStorage , String [serviceName] , String [portName] , String [endpoint] ) WSDLを PublicStorage# オブジェクトで指定するコンストラクタ。 |
メソッドの概要
返却値の型 | メソッド名 |
---|---|
void | cleanup () SOAPClientの関連リソースをクリーンアップします。 |
Array | getOperationNames () このWebサービスで利用可能なオペレーション名を返却します。 |
String | getSampleCode (String [operationName] ) Webサービスを呼び出すソースコードのサンプルを返却します。 |
void | setCharacterSetEncoding (String charset ) 送信するSOAPメッセージの文字セットを設定します。 |
void | setEnableMTOM (Boolean bool ) MTOM (Message Transmission Optimization Mechanism)の有効・無効を設定します。 |
void | setTimeOutInMilliSeconds (Number timeOutInMilliSeconds ) タイムアウト値を設定します。 |
コンストラクタの詳細
SOAPClient (String wsdlUrl , String [serviceName] , String [portName] , String [endpoint] )
WSDLを URL文字列 で指定するコンストラクタ。
SOAPClientは、インスタンス生成時に以下の処理を行います。
2回目以降のインスタンス生成では上記処理が省略され、1回目に作成されたスタブが利用されます。 なお、この動作は、初期設定時の動作です。設定を変更する方法は こちら を参照してください。 WSDL内に複数のWebサービスが定義されている場合は、第2引数「serviceName」に実行したいWebサービス名を指定します。 WSDLのポート要素を指定したい場合は、第3引数「portName」に利用したいポート名を指定します。 WSDL内に定義されているエンドポイントとは異なるエンドポイントを利用する場合は、第4引数「endpoint」に指定してください。 serviceNameやportNameを指定しない場合は、以下のようにエンドポイントを設定してください。
なお、WSDLファイルは、パブリックストレージ上に存在するWSDLファイルを利用することも可能です。 詳しくは、WSDLを PublicStorage オブジェクトで指定するコンストラクタ を参照してください。
パラメータ
|
|
SOAPClient (File wsdlOnAppRuntime , String [serviceName] , String [portName] , String [endpoint] )
WSDLを File# オブジェクトで指定するコンストラクタ。
このコンストラクタを利用すると、Application Runtime上に保存されているWSDLファイルを利用することが可能です。 第1引数に、WSDLファイルを指し示している File オブジェクトを指定してください。 そのほかの動作は、「WSDLをURLで指定するコンストラクタ」と同等です。
パラメータ
|
|
SOAPClient (PublicStorage wsdlOnStorage , String [serviceName] , String [portName] , String [endpoint] )
WSDLを PublicStorage# オブジェクトで指定するコンストラクタ。
このコンストラクタを利用すると、パブリックストレージ上に保存されているWSDLファイルを利用することが可能です。 第1引数に、WSDLファイルを指し示している PublicStorage オブジェクトを指定してください。 なお、WSDLファイルの解析時に、別のWSDLファイル や 別のXMLスキーマファイル (以降、「XSDファイル」と呼ぶ)が必要な場合は、 コンストラクタに指定したWSDLファイルと同じディレクトリ(または、設定可能なサブディレクトリ)にそれらのファイルを保存してください。 上記は、SOAPメッセージの送受信時に使われる要素が、指定したWSDLファイル内ではなく、 別のXSDファイルで定義されている場合が当てはまります。 WSDLファイルの解析時に必要なファイルの拡張子や、必要なファイルが格納されているディレクトリ名の設定方法は、 こちら を参照してください。 そのほかの動作は、「WSDLをURLで指定するコンストラクタ」と同等です。
パラメータ
|
メソッドの詳細
void cleanup ()
SOAPClientの関連リソースをクリーンアップします。
このメソッドを呼び出すことは、Axis2のorg.apache.axis2.client.Stub#cleanup()メソッドを呼び出すことに相当します。
返却値
|
||
Array getOperationNames ()
このWebサービスで利用可能なオペレーション名を返却します。
返却値
|
||
String getSampleCode (String [operationName] )
Webサービスを呼び出すソースコードのサンプルを返却します。
getSampleCode()の引数にはWebサービス・オペレーション名を指定します。 オペレーション名は getOperationNames() でも取得可能です。 引数を指定せずに getSampleCode() を実行すると、Webサービス内で利用可能なすべてのオペレーションに関するソースコードが返却されます。 getSampleCode()関数の目的はサンプルコードの表示です。 したがって、getSampleCode()関数の実行ロジックは、Webサービスを呼び出すコードの作成完了後に削除してください。 以下に、getSampleCode()関数で生成される、Webサービスを呼び出すソースコードのサンプルを示します。
サンプルコードはJSON形式で出力されます。そのため、コピー&ペーストで利用することが可能です。 また、コメントとしてJavaScriptの型情報が付与されています。 9行目の「<WSUserInfo>」 や 28行目の「<Member>」など、 JavaScriptの型情報の右側に表示されている「<>」内の文字列は、そのオブジェクト構成を表す名称です。 例えば、42行目の「<Member[]>」は、 「childrenプロパティには、28行目で示されている<Member>形式のオブジェクトが配列で格納される」 ことを意味しています。 なお、XMLスキーマの restriction で定義されている型などは、サンプルデータが生成されません。 サンプルデータが生成されていない型については、WSDL、および、実行するWebサービスの仕様を確認してください。
パラメータ
返却値
|
||
void setCharacterSetEncoding (String charset )
送信するSOAPメッセージの文字セットを設定します。
設定しない場合の初期値は「UTF-8」です。
パラメータ
返却値
|
||
void setEnableMTOM (Boolean bool )
MTOM (Message Transmission Optimization Mechanism)の有効・無効を設定します。
パラメータ
返却値
|
||
void setTimeOutInMilliSeconds (Number timeOutInMilliSeconds )
タイムアウト値を設定します。
パラメータ
返却値
|