10.4.1 Webサービス側のフォルトおよび例外の処理
(1) サービス固有例外の処理
WSDLのフォルトとJavaの例外は,JAX-WS 2.2仕様に従ってマッピングされます。WSDLのフォルトとJavaの例外クラスのマッピング例を次の図に示します。
図10-7 WSDLのフォルトとJavaの例外クラスのマッピング例
![[図データ]](figure/zu090600.gif)
マッピング例では,UserDefinedFaultフォルトがフォルトbean(com.example.sample.UserDefinedFault)と,ラッパ例外クラス(com.example.sample.UserDefinedException)にマッピングされていることがわかります。
フォルトと例外クラスのマッピングについては,「15.1.7 フォルトから例外クラスへのマッピング」,および「16.1.7 Javaのラッパ例外クラスからフォルトへのマッピング」を参照してください。
Webサービス側のJAX-WSエンジンによって,ラッパ例外クラスは次の表のようにSOAPフォルトにバインディングされます。
表10-6 ラッパ例外クラスのバインディング
項番 | SOAPフォルトの子要素 | 内容 |
---|
SOAP 1.1仕様 | SOAP 1.2仕様 |
---|
1 | faultcode | soapenv12:Code | - SOAP 1.1仕様
- QName soapenv:serverで固定です。
- SOAP 1.2仕様
- QName soapenv12:Receiverで固定です。
|
2 | faultstring | soapenv12:Reason | ラッパ例外クラスに対してgetMessageメソッドを実行した結果になります。 |
3 | faultactor | soapenv12:Role | ありません。 |
4 | detail | soapenv12:Detail | フォルトbeanをマーシャルした結果になります。 |
ラッパ例外クラスをWebサービス実装クラスでスローする例を示します。
//フォルトbeanを生成し,マーシャルすべき情報を設定する
UserDefinedFault fault = new UserDefinedFault();
fault.additionalInfo = 257;
fault.detail = "Failed by some reason.";
fault.message = "Contact your administrator.";
//ラッパ例外クラスをスロー
throw new UserDefinedException(
"Something happens.", fault ); |
送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します(実際は,改行およびインデントはありません)。
<?xml version="1.0" ?>
<S:Envelope xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<faultcode>ns2:Server</faultcode>
<faultstring>Something happens.</faultstring>
<detail>
<ns2:UserDefinedFault xmlns:ns2="http://example.com/sample">
<additionalInfo>257</additionalInfo>
<detail>Failed by some reason.</detail>
<message>Contact your administrator.</message>
</ns2:UserDefinedFault>
</detail>
</ns2:Fault>
</S:Body>
</S:Envelope> |
- 注
- SOAPフォルトメッセージには,SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。
送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します(実際は,改行およびインデントはありません)。
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text xml:lang="ja">Something happens.</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<env:UserDefinedFault xmlns:env="http://example.com/sample">
<additionalInfo>257</additionalInfo>
<detail>Failed by some reason.</detail>
<message>Contact your administrator.</message>
</env:UserDefinedFault>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope> |
- 注
- SOAPフォルトメッセージには,SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。
(2) ランタイム例外のバインディング
Webサービス実装クラス内でjavax.xml.ws.WebServiceException以外のランタイム例外がスローされた場合,Webサービス側のJAX-WSエンジンによって,ランタイム例外がSOAPフォルトにバインディングされます(JAX-WS 2.2仕様に基づいてバインディング)。
ランタイム例外のバインディングの例を次の表に示します。
表10-7 ランタイム例外のバインディング
項番 | SOAPフォルトの子要素 | 内容 |
---|
SOAP 1.1仕様 | SOAP 1.2仕様 |
---|
1 | faultcode | soapenv12:Code | - SOAP 1.1仕様
- QName soapenv:serverで固定です。
- SOAP 1.2仕様
- QName soapenv12:Receiverで固定です。
|
2 | faultstring | soapenv12:Reason | ランタイム例外に対してgetMessageメソッドを実行した結果になります。 |
3 | faultactor | soapenv12:Role | ありません。 |
4 | detail | soapenv12:Detail | ありません。 |
ランタイム例外のスローの例を示します。
//ランタイム例外をスロー
throw new IllegalArgumentException( "Something illegal." ); |
送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します(実際は,改行およびインデントはありません)。
<?xml version="1.0" ?>
<S:Envelope xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<faultcode>ns2:Server</faultcode>
<faultstring>Something illegal.</faultstring>
</ns2:Fault>
</S:Body>
</S:Envelope> |
- 注
- SOAPフォルトメッセージには,SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。
送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します(実際は,改行およびインデントはありません)。
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text xml:lang="ja">Something illegal.</ns3:Text>
</ns3:Reason>
</ns3:Fault>
</S:Body>
</S:Envelope> |
- 注
- SOAPフォルトメッセージには,SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。
(3) javax.xml.ws.WebServiceExceptionのバインディング
Webサービス実装クラスまたはプロバイダ実装クラス内でjavax.xml.ws.soap.SOAPFaultException以外のjavax.xml.ws.WebServiceExceptionがスローされた場合,Webサービス側のJAX-WSエンジンによって,javax.xml.ws.WebServiceExceptionがSOAPフォルトにバインディングされます(JAX-WS 2.2仕様に基づいてバインディング)。
javax.xml.ws.WebServiceExceptionのバインディングの例を次の表に示します。
表10-8 javax.xml.ws.WebServiceExceptionのバインディング
項番 | SOAPフォルトの子要素 | 内容 |
---|
SOAP 1.1仕様 | SOAP 1.2仕様 |
---|
1 | faultcode | soapenv12:Code | - SOAP 1.1仕様
- QName soapenv:serverで固定です。
- SOAP 1.2仕様
- QName soapenv12:Receiverで固定です。
|
2 | faultstring | soapenv12:Reason | javax.xml.ws.soap.SOAPFaultExceptionに対してgetMessageメソッドを実行した結果になります。SOAP 1.2の場合,xml:lang属性にはJavaVMのデフォルトのロケールが設定されます。 |
3 | faultactor | soapenv12:Role | ありません。 |
4 | detail | soapenv12:Detail | ありません。 |
javax.xml.ws.WebServiceExceptionのスローの例を示します。
//javax.xml.ws.WebServiceExceptionをスロー
throw new javax.xml.ws.WebServiceException( "Web Service Exception." ); |
送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します(実際は,改行およびインデントはありません)。
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<faultcode>ns2:Server</faultcode>
<faultstring>Web Service Exception.</faultstring>
</ns2:Fault>
</S:Body>
</S:Envelope> |
- 注
- SOAPフォルトメッセージには,SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。
送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します(実際は,改行およびインデントはありません)。
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text xml:lang="ja">Something illegal.</ns3:Text>
</ns3:Reason>
</ns3:Fault>
</S:Body>
</S:Envelope> |
- 注
- SOAPフォルトメッセージには,SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。
(4) javax.xml.ws.soap.SOAPFaultExceptionのバインディング
Webサービス実装クラスまたはプロバイダ実装クラス内で,javax.xml.ws.soap.SOAPFaultExceptionがスローされた場合,Webサービス側のJAX-WSエンジンによって,javax.xml.ws.soap.SOAPFaultExceptionがSOAPフォルトにバインディングされます(JAX-WS 2.2仕様に基づいてバインディング)。
javax.xml.ws.soap.SOAPFaultExceptionのバインディングの例を次の表に示します。
表10-9 javax.xml.ws.soap.SOAPFaultExceptionのバインディング
項番 | SOAPフォルトの子要素 | 内容 |
---|
SOAP 1.1仕様 | SOAP 1.2仕様 |
---|
1 | faultcode | soapenv12:Code | - SOAP 1.1仕様
- getFault().getFaultCodeAsQNameメソッドの結果になります。
- ただし,nullの場合はQName soapenv:serverで固定です。
- SOAP 1.2仕様
- QName soapenv12:Senderで固定です。soapenv12:Codeの子要素のsoapenv12:Subcodeが結果を持ちます。
|
2 | faultstring | soapenv12:Reason | getFaultReasonTextメソッドの結果になります。 ただし,nullの場合はgetMessageメソッドを実行した結果になります。 |
3 | faultactor | soapenv12:Role | getFault().getFaultRoleメソッドの結果になります。 ただし,nullの場合はありません。 |
4 | detail | soapenv12:Detail | getFault().getDetailメソッドを実行した結果をマーシャルした結果になります。 ただし,nullの場合はありません。 |
SOAP 1.1仕様の場合の,javax.xml.ws.soap.SOAPFaultExceptionのスローの例を示します。
SOAPFault soapFault = ...;
soapFault.setFaultCode( new QName( "http://sample.org", "UserDefined" ) );
soapFault.setFaultActor( "http://example.com/sample" );
soapFault.setFaultString( "SOAPFaultException happens." );
Detail detail = soapFault.addDetail();
SOAPElement soapElement = detail.addChildElement( new QName( "", "detailTest" ) );
soapElement.addTextNode( "TEST." );
//javax.xml.ws.soap.SOAPFaultExceptionをスロー
throw new SOAPFaultException( soapFault ); |
SOAP 1.2仕様の場合の,javax.xml.ws.soap.SOAPFaultExceptionのスローの例を示します。
SOAPFactory soapFactory = SOAPFactory.newInstance( SOAPConstants.SOAP_1_2_PROTOCOL );
SOAPFault soapFault = soapFactory.createFault();
soapFault.appendFaultSubcode( new QName( "http://sample.org", "UserDefined" ) );
soapFault.setFaultRole( "http://example.com/sample" );
soapFault.addFaultReasonText( "SOAPFaultException happens.", Locale.getDefault() );
Detail detail = soapFault.addDetail();
SOAPElement soapElement = detail.addChildElement( new QName( "", "detailTest" ) );
soapElement.addTextNode( "TEST." );
//javax.xml.ws.soap.SOAPFaultExceptionをスロー
throw new SOAPFaultException( soapFault ); |
送信されるSOAP 1.1仕様のSOAPフォルトメッセージの例を示します(実際は,改行およびインデントはありません)。
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<faultcode xmlns:ns0="http://sample.org">ns0:UserDefined</faultcode>
<faultstring>SOAPFaultException happens.</faultstring>
<faultactor>http://example.com/sample</faultactor>
<detail><detailTest>TEST.</detailTest></detail>
</ns2:Fault>
</S:Body>
</S:Envelope> |
- 注
- SOAPフォルトメッセージには,SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。
送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します(実際は,改行およびインデントはありません)。
<?xml version="1.0" ?>
<S:Envelope xmlns:S= "http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Sender</ns3:Value>
<ns3:Subcode>
<ns3:Value xmlns:ns0="http://sample.org">ns0:UserDefined</ns3:Value>
</ns3:Subcode>
</ns3:Code>
<ns3:Reason>
<ns3:Text xml:lang="ja">SOAPFaultException happens.</ns3:Text>
</ns3:Reason>
<ns3:Role>http://example.com/sample</ns3:Role>
<ns3:Detail>
<env:Detail xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<detailTest>TEST.</detailTest>
</env:Detail>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope> |
- 注
- SOAPフォルトメッセージには,SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。