Java ベースの Web サービスクライアントの作成
プロジェクトディレクトリ (src_client) と Java ソースファイルの例 (src_client/org/myorg/MathClient.java) が、セクションInfo*Engine ベースの Web サービスの作成の手順「プロジェクトを作成」で作成されました。
MathClient.java ソースファイルは、展開済みの Web サービスから生成されるソースコンポーネントに依存しています。クライアントソースを作成する前に、これらのコンポーネントを生成し、コンパイルする必要があります。生成と同時に MathClient.java がコンパイルされますが、それを使用して Web サービスメソッドを呼び出すまで、何も行いません。
これらのコンポーネントを取得するには、以下のコマンドを使用して、空のクライアントをコンパイルする必要があります。
% cd <Windchill>/prog_examples/jws/MyProject/src_client
% ant
% ant
Apache Ant スクリプトによって、アプリケーションの JAR 実行ファイルも生成されます。
<Windchill>/prog_examples/jws/MyProject/dist_client/MathServiceClient.jar
ただし、メインクラスが何も行わないので、JAR を実行しても何も行われません。前の ant コマンドを実行すると、Web サービスの WSDL が処理され、Java ソースコンポーネントが以下のロケーションに生成されます。
<Windchill>/prog_examples/jws/MyProject/gensrc_client
これにより、Java ソースコードが com.ptc.jws.service.org.myorg.mathservice パッケージ内に作成されます。サービスネームスペースから派生した名前を持つパッケージに Java コードが生成されないようにするには、build.xml ファイル内の jaxws.package プロパティを使用して、ソースコードの生成先のパッケージを明示的に定義します。
クライアントソースコードを編集して、クライアントを完成させます。
1. テキストエディタで次のファイルを開きます。
<Windchill>/prog_examples/jws/MyProject/src_client/org/myorg/MathClient.java
ソースは以下のようになります。
package org.myorg;
// import the classes generated when compiling your client
//import com.ptc.jws.service.?.*;
import com.ptc.jws.client.handler.*;
public class MathClient
{
public static void main ( String [] args ) throws java.lang.Exception
{
// depending on your security requirements you may need to specify credentials up
// front, or on the command-line where most policies will prompt for them
//Credentials.setUsername ( "demo" );
//Credentials.setPassword ( "demo" );
// TODO implement your client /*
MathServiceImplService service = new MathServiceImplService();
MathServiceImpl port = service.getMathServiceImplPort ();
//invoke an action
//port.methodName ( <arguments> );
*/
}
}
// import the classes generated when compiling your client
//import com.ptc.jws.service.?.*;
import com.ptc.jws.client.handler.*;
public class MathClient
{
public static void main ( String [] args ) throws java.lang.Exception
{
// depending on your security requirements you may need to specify credentials up
// front, or on the command-line where most policies will prompt for them
//Credentials.setUsername ( "demo" );
//Credentials.setPassword ( "demo" );
// TODO implement your client /*
MathServiceImplService service = new MathServiceImplService();
MathServiceImpl port = service.getMathServiceImplPort ();
//invoke an action
//port.methodName ( <arguments> );
*/
}
}
2. 以下のように、サーバー側の Web サービスコンポーネントをインポートしてメソッドを呼び出すようにソースを更新します。
package org.myorg;
// import the classes generated when compiling your client
import com.ptc.jws.service.org.myorg.mathservice.*;
public class MathClient
{
public static void main ( String [] args ) throws java.lang.Exception
{
int a = args.length > 0 ? Integer.parseInt ( args[0] ) : 0;
int b = args.length > 1 ? Integer.parseInt ( args[1] ) : 0;
MathServiceImplService service = new MathServiceImplService();
MathServiceImpl port = service.getMathServiceImplPort ();
System.out.printf ( "a+b=%d\n", port.add ( a, b ) );
System.out.printf ( "a-b=%d\n", port.subtract ( a, b ) );
System.out.printf ( "a*b=%d\n", port.multiply ( a, b ) );
System.out.printf ( "a/b=%f\n", port.divide ( a, b ) );
}
}
// import the classes generated when compiling your client
import com.ptc.jws.service.org.myorg.mathservice.*;
public class MathClient
{
public static void main ( String [] args ) throws java.lang.Exception
{
int a = args.length > 0 ? Integer.parseInt ( args[0] ) : 0;
int b = args.length > 1 ? Integer.parseInt ( args[1] ) : 0;
MathServiceImplService service = new MathServiceImplService();
MathServiceImpl port = service.getMathServiceImplPort ();
System.out.printf ( "a+b=%d\n", port.add ( a, b ) );
System.out.printf ( "a-b=%d\n", port.subtract ( a, b ) );
System.out.printf ( "a*b=%d\n", port.multiply ( a, b ) );
System.out.printf ( "a/b=%f\n", port.divide ( a, b ) );
}
}
3. クライアントを再コンパイルし、更新されたクラスが含まれるように実行可能 JAR を更新します。
% ant compile
% ant dist
% ant dist
4. 新しい Web サービスクライアントをコマンドラインから実行します。
% java -jar ../dist_client/MathServiceClient.jar 10 20
Username:<パスワード>
Password:<ユーザー名>
a+b=30
a-b=-10
a*b=200
a/b=0.500000
Username:<パスワード>
Password:<ユーザー名>
a+b=30
a-b=-10
a*b=200
a/b=0.500000
ここで、<ユーザー名> はユーザー名、<パスワード> は先に指定したパスワードです。クライアントを実行すると、コマンドラインで資格証明が要求されます。
クライアントのコールバックハンドラ
Web サービスを作成したときに、-Dsecurity.policy=usernameAuthSymmetricKeys プロパティが指定されています。これにより、セキュリティポリシーによって明示的に Web サービスのセキュリティを確保するようにフレームワークに指示が出されています (対称キーを使用したユーザー名認証を参照)。このプロパティが明示的に指定されていなければ、セキュリティポリシーは <Windchill>/bin/adminTools/WebServices/security.properties で設定されているようにデフォルト値である security.policy プロパティの値になります。
プロジェクトのクライアント部分を生成するとき、このポリシーに基づいて、デフォルトのクライアント側コールバックハンドラのコンフィギュレーションが使用されます。これは、src_client/build.xml ビルドスクリプトの handler.config プロパティで指定されています。handler.config プロパティのフォーマットを表示するには、src_client ディレクトリ内から ant usage コマンドを実行します。
com.ptc.jws.client.handler パッケージには、サポートされているセキュリティポリシーを Web サービスクライアントが使用するための基本的なコールバックハンドラもいくつか含まれています (これらのハンドラのクラスは、クライアントを構築するときに自動的にパッケージ化されます)。これらのクラスを使用してセキュリティ情報を Web サービスクライアントに提供することも、javax.security.auth.callback.CallbackHandler を実装するクラスを指定し、そのクラスを handler.config プロパティの一部として指定することによって独自のクラスを作成することもできます。
usernameAuthSymmetricKeys 用のデフォルトのコールバックハンドラは、コマンドラインで資格証明を要求します。これは、Swing ダイアログを使用してユーザーに資格証明を要求する、またはシステムプロパティから資格証明を取得するように設定できます。これは、スレッドにつき一回のみ資格証明を要求し、ユーザーがプログラムによってクリアするまでその資格証明を再利用します。
プログラムによって資格証明を指定する場合は、setUsername および setPassword メソッドを使用する com.ptc.jws.client.handler.Credentials クラスを使用する必要があります。
Web サービスフレームワークでは、2 つのコールバックメカニズムが使用されています。
• WSIT (Web Services Interoperability Technologies) メカニズムでは、javax.security.auth.callback.CallbackHandler 実装が使用されます。
これらのハンドラは、webServerAuthenticated 以外のセキュリティポリシーに使用され、Web サービスに渡された資格証明またはセキュリティトークンを収集します。これらの実装がアプリケーションの要件に対応しない場合は、build.xml ファイル内の handler.config プロパティを使用して独自の実装を指定できます。
• JAX-WS ハンドラ チェーンは、実質的には、一般的に以下のものを実装する Java クラスのリストです。
javax.xml.ws.handler.soap.SOAPHandler<javax.xml.ws.handler.soap.SOAPMessageContext>
クライアントコードを実装する代わりに、これらのハンドラのクラスを使用して、SOAP 操作用の汎用機能と条件付けを提供できます。Web サービスフレームワークには、詳細を処理するための基本的なハンドラがいくつか用意されています。たとえば、これらを使用して、Web サービスの URL を指定したり、Web サーバー認証が使用されるときにリクエストに資格証明を追加したりします。
ヘッダーを SOAP リクエストに追加する、一般的な方法でエラーを処理するなどの追加の機能を実行するためのハンドラを作成することもできます。build.xml ファイル内の handler.chain プロパティの値を変更することで、クライアントのハンドラチェーンをカスタマイズできます。これらのプロパティの詳細については、build.xml ファイル内で説明されています。
ポータブル Web サービスクライアント
Web サービスクライアントをクライアントマシンで適切に実行できるようにしたり、Web サービスクライアントが複数の Windchill インスタンスで複数の同一サービスホストと対話できるようにしたりするには、いくつかの課題を解決する必要があります。セキュリティポリシーのコンフィギュレーションは基本的にはコンパイル時にハードコード化されるため、新しいクライアントはクライアントホストごとに再設定される必要があります。同様に、Web サービスのアドレスはコンパイル時に固定されるため、サービスインスタンスと対話するクライアントを個別に作成するには、サービスの終点がプログラムによって指定される必要があります。Web サービスクライアントの移植性を向上させるため、Web サービスフレームワークでは JAX-WS ハンドラチェーンが使用されており、これによってクライアント JAR ファイルが必要に応じて再設定されるようにできます。
セキュリティポリシーの使用
サポートされているセキュリティポリシー (Web サーバー認証以外) のいずれかで Web サービスのセキュリティを確保する場合、Java クライアントが独自のキーストアとトラストストアにアクセスできる必要があります。これらのファイル (キーストアとトラストストア) へのパスは、以下の場所にあるビルドフレームワークによって使用されるように設定されています。
<Windchill>/bin/adminTools/WebServices/client/security.properties
キーストアとトラストストアへのパスは絶対パスであり、META-INF ディレクトリ内でクライアント JAR ファイルとパッケージ化された展開記述子にコンパイルされる必要があります。
Windchill が標準のコンフィギュレーションで実行されているホストから Web サービスクライアントをコンパイルすると、これらのファイルはクライアントでは使用できますが、サーバーでは使用できません。Web サービスクライアントを別のホストに再配布する前に、次のいずれかの操作を実行する必要があります。
• これらのファイルが新規クライアントに配置される際の場所のパスを含むように、client/security.properties ファイルを更新 (または、このファイルのコピーを src_client ディレクトリに作成して更新) し、クライアントを再構築します。
• クライアントを実行する各ホストで、クライアントの JAR ファイルを再設定します。詳細については、後述のセクション「クライアント JAR ファイルの再設定」を参照してください。
• クライアントを実行する予定の各ホストで、ホストごとに適切なパスを指定したクライアントのコピーをコンパイルします。詳細については、後述のセクション「ホストごとにクライアントのコピーをコンパイルする」を参照してください。
クライアント JAR ファイルの再設定
クライアントをコンパイルし、パッケージ化したら、プロジェクトの dist_client ディレクトリに、コンパイルされたクライアントを含んでいる JAR ファイルと webservices-support.jar ファイルの 2 つの JAR ファイルが生成されます。この JAR ファイルは実行可能で、クライアントを再設定するために次のように使用することができます。
% java -jar webservices-support.jar
-clientJar <JAR ファイル> [-targetJar <JAR ファイル>] [-securityProperties
<プロパティファイル>] [-wsdl <サービス WSDL>]
-clientJar <JAR ファイル> [-targetJar <JAR ファイル>] [-securityProperties
<プロパティファイル>] [-wsdl <サービス WSDL>]
-targetJar が指定されていない場合は、-clientJar が上書きされます。-wsdl と -securityProperties の両方またはいずれかを指定する必要もあります。
トラストストアとキーストアのロケーションへのパスを再設定するには、security.properties ファイルをクライアントホストにコピーし、-securityProperties 引数を使用してユーティリティを実行します。これは、Web サービスのデフォルトの URL を再設定するためにも使用できます。別の方法として、システムプロパティを使用して Web サービスの URL を指定することも、独自の JAX-WS ハンドラを作成して URL を指定することもできます。
 |
プロパティファイル内のトラストストアおよびキーストアのロケーションへのファイルパスは絶対パスで指定する必要があり、ほかのプロパティの参照を含めることはできません。
|
この方法でクライアント JAR を再設定する場合は、クライアントが使用するコールバックハンドラに関する追加情報も指定する必要があります。この情報を指定しない場合、通常コールバックハンドラによって提供される情報がプログラムによって指定されるまで、再設定したクライアントは機能できません。特に、これにはユーザーの資格情報の収集や、JAX-WS ハンドラチェーンを通した一般的な処理の実行に必要なクラスが含まれます。
設定可能なその他のプロパティを次に示します。
handler.config
handler.chain.authentication
handler.chain.extras
handler.chain.url
handler.chain.authentication
|
|
これらのプロパティの説明については、ant usage コマンドを src_client プロジェクトディレクトリ内で実行してください。
|
既存のクライアント JAR の場合、コンフィギュレーションは security.properties ファイルで指定されます。構築時に、このコンフィギュレーションは通常 src_client/build.xml Ant スクリプト内で検索されます。
トラストストアとキーストアのパスだけを再設定している場合は、src_client/build.xml スクリプトで handler.config プロパティの値を確認する必要があります。クライアント JAR を再設定するときに、security.properties ファイルでこのプロパティを指定します。
Web サービスのセキュリティポリシーが変更されたためにクライアント JAR を再設定する場合は、クライアントのハンドラコンフィギュレーションの変更が必要となる場合があります。例:
#web service security.policy=userNameAuthSymmetricKeys
handler.config=usernameHandler:com.ptc.jws.client.handler.
UsernamePasswordCallbackHandler,passwordHandler:com.ptc.jws.client.handler.
UsernamePasswordCallbackHandler
#web service security.policy=samlsv
handler.config=samlHandler:com.ptc.jws.client.handler.SamlCallbackHandler
handler.config=usernameHandler:com.ptc.jws.client.handler.
UsernamePasswordCallbackHandler,passwordHandler:com.ptc.jws.client.handler.
UsernamePasswordCallbackHandler
#web service security.policy=samlsv
handler.config=samlHandler:com.ptc.jws.client.handler.SamlCallbackHandler
|
|
これらのプロパティは、com.ptc.jws.client.handler パッケージに加えて指定します。
|
Web サーバー認証 (security.policy=webServerAuthenticated) で保護された Web サービスに対してクライアントを再設定する場合は、コマンドを実行するときにシステムプロパティの requires.authentication=true を指定する必要があります。独自の JAX-WS ハンドラチェーンコンフィギュレーションを指定する場合は、security.properties ファイルのみ必要です。例:
% java -D requires.authentication=true -clientJar <client jar> -wsdl <service wsdl>
この場合は、handler.chain.authentication のデフォルト値が自動的に使用されます。
ホストごとにクライアントのコピーをコンパイルする
また、クライアントが実行される予定のすべてのホストにそれぞれ対応するように、特定のホストへの適切なパスが含まれているクライアントのコピーをコンパイルすることもできます。
例:
% cd <Windchill>/prog_examples/jws/MathService/src_client
% cp <Windchill>/bin/adminTools/WebServices/client/security.properties .
% cp <Windchill>/bin/adminTools/WebServices/client/security.properties .
必要に応じて、クライアントごとに security.properties のローカルコピーを更新します。これにより、これらのセキュリティプロパティが <Windchill>/bin/adminTools/WebServices/ client/security.properties 内にある共通のプロパティよりも優先されます。
Web サービス URL の動的な指定
Java ベースの Web サービスクライアントを作成しているとき、HTTP 接続情報は Windchill のコンフィギュレーションに基づいて決定されます。Web サービスクライアントの JAR を構築しているとき、フレームワークによって Web Service Definition Language (WSDL) のローカルコピーが Web サービスに保存され、カタログファイルからその WSDL が参照されます。これにより、クライアントが実行時にネットワーク経由で WSDL にアクセスする必要がなくなります。
デフォルトでは、Web サービスフレームワークは、Windchill のコンフィギュレーションに基づいてサーバーに URL を設定するクラスが含まれるように JAX-WS ハンドラチェーンを設定します。デフォルト実装は com.ptc.jws.client.handler.WebServiceURLHandler であり、これは build.xml で handler.chain.url プロパティを使用してオーバーライドできます。したがって、クライアントを実行するためにこの情報を指定する必要はありません。
クライアントが wt.webservice.url システムプロパティを使用して Web サーバー URL をオーバーライドすることも、ユーザーが com.ptc.jws.client.handler.WebServiceURLHandler クラスで setWebServiceURL(java.net.URL url) メソッドを使用してプログラムによって URL を指定することもできます。
別の方法として、独自の実装で handler.chain.url プロパティをオーバーライドしてこの URL を指定することもできます。これを行う場合は、ハンドラ実装に割り当てられている javax.xml.ws.handler.soap.SOAPMessageContext のインスタンス内で javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY を設定する必要があります。
Web サーバーによるサービスとクライアントの認証
標準のセキュリティポリシー (SAML 送信者保証や対称キーによるユーザー名認証など) を使用する場合は、Web サービスのサーブレットが Web サーバー認証によって保護されることなく展開されます。このような場合、Web サーバーではなく Web サービスが認証を行います。
サーブレットを Web サーバー認証の背後に展開することもできます。これを行うには、以下で説明されているように、展開時に webServerAuthenticated セキュリティポリシーを使用します。
<Windchill>/bin/adminTools/WebServices/security.properties
ツーリングは、<Windchill>/apacheConf 内の保護されたリソースコンフィギュレーションを自動的に更新します (プロジェクトを使用してサービスを構築および展開している場合)。実行中であれば、これらの変更はローカルの Apache のコンフィギュレーションに適用されます (その後は単に再起動する必要があるだけです)。Apache 以外の Web サーバーを使用している場合、または使用している Apache が Windchill と同じホストに配置されていない場合は、手動でこれらの変更を Web サーバーのコンフィギュレーションに適用する必要があります。
デフォルトでは、JAX-WS ハンドラチェーンは、Web サービスクライアントの送信リクエストでユーザーの資格証明を設定するためのハンドラ実装が含まれるように設定されます。これらの資格証明は、com.ptc.jws.client.handler.Credentials クラスで setUsername(String user) および setPassword(String password) メソッドを使用してプログラムによって指定できます。別の方法として、wt.webservice.user および wt.webservice.password システムプロパティで資格証明を指定することもできます。
また、build.xml ファイル内で handler.chain.authentication プロパティを使用してハンドラ実装をオーバーライドすることもできます。独自のハンドラを実装する場合は、ハンドラ実装に指定されている javax.xml.ws.handler.soap.SOAPMessageContext オブジェクト内の javax.xml.ws.BindingProvider.USERNAME_PROPERTY and javax.xml.ws.BindingProvider.PASSWORD_PROPERTY プロパティを設定する必要があります。
|
|
Web サーバー認証によって保護されている Web サービスの展開を解除する場合、ツーリングは以前保護されていたリソースを削除するために自動的に Web サーバーのコンフィギュレーションを更新しません。手動で Web サーバーを再設定する必要があります。
|