10.4.1 Webサービス側のフォルトおよび例外の処理

Webサービス側のJAX-WSエンジンでのフォルトおよび例外の処理について説明します。なお,Webサービスがプロバイダ実装クラスで実装されている場合,この処理は実行されません。

<この項の構成>
(1) サービス固有例外の処理
(2) ランタイム例外のバインディング
(3) javax.xml.ws.WebServiceExceptionのバインディング
(4) javax.xml.ws.soap.SOAPFaultExceptionのバインディング

(1) サービス固有例外の処理

WSDLのフォルトとJavaの例外は,JAX-WS 2.2仕様に従ってマッピングされます。WSDLのフォルトとJavaの例外クラスのマッピング例を次の図に示します。

図10-7 WSDLのフォルトとJavaの例外クラスのマッピング例

[図データ]

マッピング例では,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仕様
1faultcodesoapenv12:Code
SOAP 1.1仕様
QName soapenv:serverで固定です。
SOAP 1.2仕様
QName soapenv12:Receiverで固定です。
2faultstringsoapenv12:Reasonラッパ例外クラスに対してgetMessageメソッドを実行した結果になります。
3faultactorsoapenv12:Roleありません。
4detailsoapenv12: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仕様
1faultcodesoapenv12:Code
SOAP 1.1仕様
QName soapenv:serverで固定です。
SOAP 1.2仕様
QName soapenv12:Receiverで固定です。
2faultstringsoapenv12:Reasonランタイム例外に対してgetMessageメソッドを実行した結果になります。
3faultactorsoapenv12:Roleありません。
4detailsoapenv12: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仕様
1faultcodesoapenv12:Code
SOAP 1.1仕様
QName soapenv:serverで固定です。
SOAP 1.2仕様
QName soapenv12:Receiverで固定です。
2faultstringsoapenv12:Reasonjavax.xml.ws.soap.SOAPFaultExceptionに対してgetMessageメソッドを実行した結果になります。SOAP 1.2の場合,xml:lang属性にはJavaVMのデフォルトのロケールが設定されます。
3faultactorsoapenv12:Roleありません。
4detailsoapenv12: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仕様
1faultcodesoapenv12:Code
SOAP 1.1仕様
getFault().getFaultCodeAsQNameメソッドの結果になります。
ただし,nullの場合はQName soapenv:serverで固定です。
SOAP 1.2仕様
QName soapenv12:Senderで固定です。soapenv12:Codeの子要素のsoapenv12:Subcodeが結果を持ちます。
2faultstringsoapenv12:ReasongetFaultReasonTextメソッドの結果になります。
ただし,nullの場合はgetMessageメソッドを実行した結果になります。
3faultactorsoapenv12:RolegetFault().getFaultRoleメソッドの結果になります。
ただし,nullの場合はありません。
4detailsoapenv12:DetailgetFault().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仕様の名前空間定義が必ず含まれます。