Hitachi

Cosminexus V11 アプリケーションサーバ Webサービス開発ガイド

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

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

〈この項の構成〉

(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仕様

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" encoding="utf-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <faultcode>S: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>
    </S:Fault>
  </S:Body>
</S:Envelope>
注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/">
      <S:Code>
        <S:Value>S:Receiver</S:Value>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">Something happens.</S:Text>
      </S:Reason>
      <S: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>
      </S:Detail>
    </S: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" encoding="utf-8"?>
<S:Envelope xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <faultcode>S:Server</faultcode>
      <faultstring>Something illegal.</faultstring>
    </S:Fault>
  </S:Body>
</S:Envelope
注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/">
      <S:Code>
        <S:Value>S:Receiver</S:Value>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">Something illegal.</S:Text>
      </S:Reason>
    </S: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" encoding="utf-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <faultcode>S:Server</faultcode>
      <faultstring>Web Service Exception.</faultstring>
    </S:Fault>
  </S:Body>
</S:Envelope>
注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/>
      <S:Code>
        <S:Value>S:Receiver</S:Value>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">Something illegal.</S:Text>
      </S:Reason>
    </S: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" encoding="utf-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault 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>
    </S:Fault>
  </S:Body>
</S:Envelope>
注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

送信されるSOAP 1.2仕様のSOAPフォルトメッセージの例を示します（実際は，改行およびインデントはありません）。

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <S:Fault xmlns:ns3="http://schemas.xmlsoap.org/soap/envelope/">
      <S:Code>
        <S:Value>S:Sender</S:Value>
        <S:Subcode>
          <S:Value xmlns:ns0="http://sample.org">ns0:UserDefined</S:Value>
        </S:Subcode>
      </S:Code>
      <S:Reason>
        <S:Text xml:lang="ja">SOAPFaultException happens.</S:Text>
      </S:Reason>
      <S:Role>http://example.com/sample</S:Role>
      <S:Detail>
        <detailTest>TEST.</detailTest>
      </S:Detail>
    </S:Fault>
  </S:Body>
</S:Envelope>
注

SOAPフォルトメッセージには，SOAP 1.1仕様とSOAP 1.2仕様の名前空間定義が必ず含まれます。

ページの先頭へ

商品名称に関する表示

All Rights Reserved. Copyright (C) 2020, 2022, Hitachi, Ltd.