モジュール java.xml.ws
パッケージ javax.xml.soap

インタフェースSOAPFault

  • すべてのスーパー・インタフェース:
    Element, Node, Node, SOAPBodyElement, SOAPElement

    public interface SOAPFault
extends SOAPBodyElement
    エラー情報またはステータス情報、あるいはその両方を格納するSOAPBodyオブジェクト内の要素。 この情報は、SOAPMessageオブジェクト内のエラーまたはメッセージ自体のコンテンツに関連しない問題に関連している場合があります。 メッセージ自体に関連しない問題は、通常、上流のサーバーと通信できないなどの処理上のエラーです。

    MessageFactoryインスタンスの作成中に指定されたprotocolによっては、SOAPFaultがSOAP 1.1/SOAP 1.2仕様で定義されたサブ要素を持ちます。

    導入されたバージョン:
    1.6

    • メソッドの詳細

      • setFaultCode

        void setFaultCode​(Name faultCodeQName)
           throws SOAPException
        指定したフォルト・コードでこのSOAPFaultオブジェクトを設定します。

        フォルト・コードはフォルトに関する情報を提供し、SOAP 1.1仕様で定義されています。 フォルト・コードは必須で、Name型である必要があります。 このメソッドは、フォルト・コードを設定する簡単な方法を提供します。 次に例を示します。 

        
 SOAPEnvelope se = ...;
 // Create a qualified name in the SOAP namespace with a localName
 // of "Client". Note that prefix parameter is optional and is null
 // here which causes the implementation to use an appropriate prefix.
 Name qname = se.createName("Client", null,
                            SOAPConstants.URI_NS_SOAP_ENVELOPE);
 SOAPFault fault = ...;
 fault.setFaultCode(qname);
        このメソッドをsetFaultCode(String)に対して使用するのが適切です。
        パラメータ:
        faultCodeQName - 設定するフォルト・コードを示すNameオブジェクト。 名前空間で修飾されている必要がある。
        例外:
        SOAPException - faultcode要素を基本となるXMLツリーに追加するときに、エラーが発生した場合。
        導入されたバージョン:
        1.6, SAAJ 1.2
        関連項目:
        getFaultCodeAsName()

      • setFaultCode

        void setFaultCode​(QName faultCodeQName)
           throws SOAPException
        指定したフォルト・コードでこのSOAPFaultオブジェクトを設定します。 このメソッドをsetFaultCode(Name)に対して使用するのが適切です。
        パラメータ:
        faultCodeQName - 設定するフォルト・コードを示すQNameオブジェクト。 名前空間で修飾されている必要がある。
        例外:
        SOAPException - faultcode要素を基本となるXMLツリーに追加するときに、エラーが発生した場合。
        導入されたバージョン:
        1.6, SAAJ 1.3
        関連項目:
        getFaultCodeAsQName(), setFaultCode(Name), getFaultCodeAsQName()

      • setFaultCode

        void setFaultCode​(String faultCode)
           throws SOAPException
        指定したフォルト・コードでこのSOAPFaultオブジェクトを設定します。

        フォルト・コードはフォルトに関する情報を提供し、SOAP 1.1仕様で定義されています。 この要素は、SOAP 1.1で必須です。 フォルト・コードはQNameである必要があるため、このメソッドのsetFaultCode(Name)形式を使用するのが適切です。

        パラメータ:
        faultCode - 設定するフォルト・コードを示すString。 接頭辞が名前空間宣言で定義された"prefix:localName"の形式であることが必要。
        例外:
        SOAPException - faultCodeを基本となるXMLツリーに追加するときに、エラーが発生した場合。
        関連項目:
        setFaultCode(Name), getFaultCode(), SOAPElement.addNamespaceDeclaration(java.lang.String, java.lang.String)

      • getFaultCodeAsName

        Name getFaultCodeAsName​()
        このSOAPFaultオブジェクトの必須SOAP 1.1フォルト・コードを、SAAJ Nameオブジェクトとして取得します。 SOAP 1.1仕様では、「faultcode」要素の値はQName型であることが必要です。 このメソッドは、要素のコンテンツをQNameとして、SAAJ Nameオブジェクトの形式で返します。 このメソッドは、アプリケーションが追加の解析を行うことなく名前空間名に容易にアクセスできるため、getFaultCodeメソッドの代わりに使用すべきです。
        戻り値:
        フォルト・コードを表現するName
        導入されたバージョン:
        1.6, SAAJ 1.2
        関連項目:
        setFaultCode(Name)

      • getFaultCodeAsQName

        QName getFaultCodeAsQName​()
        このSOAPFaultオブジェクトのフォルト・コードをQNameオブジェクトとして取得します。
        戻り値:
        フォルト・コードを表現するQName
        導入されたバージョン:
        1.6, SAAJ 1.3
        関連項目:
        setFaultCode(QName)

      • getFaultSubcodes

        Iterator<QName> getFaultSubcodes​()
        このSOAPFaultのサブコードを、QNamesのイテレータとして取得します。
        戻り値:
        QNamesのシーケンスにアクセスするIterator。 このIteratorは、オプションのremoveメソッドをサポートすべきではない。 サブコードが返される順序には、フォルトに存在する上から下へのサブコードの階層が反映される。
        例外:
        UnsupportedOperationException - このメッセージが、SOAP 1.2のサブコードの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • removeAllFaultSubcodes

        void removeAllFaultSubcodes​()
        このSOAPFaultによって格納されるサブコードを削除します。 以降getFaultSubcodesを呼び出すと、appendFaultSubcodeへの呼出しが行われるまで空のイテレータが返されます。
        例外:
        UnsupportedOperationException - このメッセージが、SOAP 1.2のサブコードの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • appendFaultSubcode

        void appendFaultSubcode​(QName subcode)
                 throws SOAPException
        このSOAPFaultによって格納されるサブコードのシーケンスの最後に、サブコードを追加します。 サブコードはSOAP 1.2で導入されましたが、SOAP Faultの必須Codeサブ要素をルートとする、サブ要素の再帰的なシーケンスによって表現されます。
        パラメータ:
        subcode - サブコードの値を格納するQName。
        例外:
        SOAPException - サブコードの設定時にエラーが発生した場合
        UnsupportedOperationException - このメッセージが、SOAP 1.2のサブコードの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • setFaultActor

        void setFaultActor​(String faultActor)
            throws SOAPException
        指定したフォルト・アクターでこのSOAPFaultオブジェクトを設定します。

        フォルト・アクターは、フォルトを発生させたメッセージ・パス内での受信者です。

        このSOAPFaultがSOAP 1.2をサポートする場合、この呼出しはsetFaultRole(String)と等しくなります

        パラメータ:
        faultActor - このSOAPFaultオブジェクトを発生させたアクターを識別するString
        例外:
        SOAPException - faultActorを基本となるXMLツリーに追加するときに、エラーが発生した場合。
        関連項目:
        getFaultActor()

      • getFaultActor

        String getFaultActor​()
        このSOAPFaultオブジェクトのフォルト・アクターを取得します。

        このSOAPFaultがSOAP 1.2をサポートする場合、この呼出しはgetFaultRole()と等しくなります

        戻り値:
        このSOAPFaultオブジェクトを発生させたメッセージ・パス内でのアクターを示すString
        関連項目:
        setFaultActor(java.lang.String)

      • setFaultString

        void setFaultString​(String faultString)
             throws SOAPException
        指定した文字列に対して、このSOAPFaultオブジェクトのフォルト文字列を設定します。

        このSOAPFaultがSOAP 1.2をサポートするメッセージの一部である場合、この呼出しは次と等しくなります。 

        
      addFaultReasonText(faultString, Locale.getDefault());
        パラメータ:
        faultString - エラーの説明を提供するString
        例外:
        SOAPException - faultStringを基本となるXMLツリーに追加するときに、エラーが発生した場合。
        関連項目:
        getFaultString()

      • setFaultString

        void setFaultString​(String faultString,
                    Locale locale)
             throws SOAPException
        指定した文字列に対して、このSOAPFaultオブジェクトのフォルト文字列を設定し、指定したロケールにローカライズします。

        このSOAPFaultがSOAP 1.2をサポートするメッセージの一部である場合、この呼出しは次と等しくなります。 

        
      addFaultReasonText(faultString, locale);
        パラメータ:
        faultString - エラーの説明を提供するString
        locale - faultStringのネイティブ言語を示すLocaleオブジェクト
        例外:
        SOAPException - faultStringを基本となるXMLツリーに追加するときに、エラーが発生した場合。
        導入されたバージョン:
        1.6, SAAJ 1.2
        関連項目:
        getFaultString()

      • getFaultString

        String getFaultString​()
        このSOAPFaultオブジェクトのフォルト文字列を取得します。

        このSOAPFaultがSOAP 1.2をサポートするメッセージの一部である場合、この呼出しは次と等しくなります。 

        
    String reason = null;
    try {
        reason = (String) getFaultReasonTexts().next();
    } catch (SOAPException e) {}
    return reason;
        戻り値:
        フォルトの説明を示すString
        関連項目:
        setFaultString(String), setFaultString(String, Locale)

      • getFaultStringLocale

        Locale getFaultStringLocale​()
        このSOAPFaultオブジェクトのフォルト文字列のロケールを取得します。

        このSOAPFaultがSOAP 1.2をサポートするメッセージの一部である場合、この呼出しは次と等しくなります。 

        
    Locale locale = null;
    try {
        locale = (Locale) getFaultReasonLocales().next();
    } catch (SOAPException e) {}
    return locale;
        戻り値:
        フォルト文字列のネイティブ言語を示すLocaleオブジェクト。ロケールが指定されていなかった場合はnull
        導入されたバージョン:
        1.6, SAAJ 1.2
        関連項目:
        setFaultString(String, Locale)

      • hasDetail

        boolean hasDetail​()
        このSOAPFaultがDetailサブ要素を保持する場合はtrue、それ以外の場合はfalseを返します。 (getDetail()!=null)と同等です。
        戻り値:
        このSOAPFaultがDetailサブ要素を保持する場合はtrue、それ以外の場合はfalse。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • getDetail

        Detail getDetail​()
        このSOAPFaultオブジェクトの、オプションの詳細要素を返します。

        Detailオブジェクトは、アプリケーション固有のエラー情報を伝え、エラー情報のスコープは、これがSOAP 1.1 Faultの場合SOAPBodyElementオブジェクト内のフォルトに制限されます。

        戻り値:
        アプリケーション固有のエラー情報がある場合はそれを含むDetailオブジェクト、ない場合はnull

      • addDetail

        Detail addDetail​()
          throws SOAPException
        オプションのDetailオブジェクトを作成し、それをこのSOAPFaultオブジェクトのDetailオブジェクトとして設定します。

        フォルトにすでにDetailが含まれる場合は、Detailを追加することができません。 そのため、このメソッドは既存のDetailが削除されたあとでのみ呼び出すべきです。

        戻り値:
        新しいDetailオブジェクト
        例外:
        SOAPException - SOAPFaultオブジェクトにすでに有効なDetailオブジェクトが含まれている場合

      • getFaultReasonLocales

        Iterator<Locale> getFaultReasonLocales​()
                                throws SOAPException
        関連付けられたReason Text項目があるLocaleの別々のシーケンスについてのIteratorを返します。 これらのLocaleはどれでも、Reason Text文字列のローカライズされたバージョンを取得するためにgetFaultReasonTextへの呼出しで使用できます。
        戻り値:
        関連付けられたReason Text項目があるLocaleオブジェクトのシーケンスのIterator。
        例外:
        SOAPException - フォルトReasonロケールの取得でエラーが発生した場合。
        UnsupportedOperationException - このメッセージが、SOAP 1.2のFault Reasonの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • getFaultReasonTexts

        Iterator<String> getFaultReasonTexts​()
                              throws SOAPException
        このSOAPFaultのReason Text項目すべてを含むStringオブジェクトのシーケンスについてのIteratorを返します。
        戻り値:
        env:Fault/env:Reason/env:Text項目についてのIterator。
        例外:
        SOAPException - フォルトReason Textの取得でエラーが発生した場合。
        UnsupportedOperationException - このメッセージが、SOAP 1.2のFault Reasonの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • getFaultReasonText

        String getFaultReasonText​(Locale locale)
                   throws SOAPException
        指定したLocaleと関連付けられたReason Textを返します。 そのようなReason Textが複数存在する場合、最初に一致するTextが返されます。
        パラメータ:
        locale - -- ローカライズされたReason Textが要求されているLocale
        戻り値:
        localeと関連付けられたReason Text
        例外:
        SOAPException - 指定したロケールのフォルトReason Textの取得でエラーが発生した場合。
        UnsupportedOperationException - このメッセージが、SOAP 1.2のFault Reasonの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3
        関連項目:
        getFaultString()

      • addFaultReasonText

        void addFaultReasonText​(String text,
                        Locale locale)
                 throws SOAPException
        指定したテキスト・メッセージおよびlocaleから派生したxml:langを含むReason Text項目を追加または置換します。 このxml:langを含むReason Text項目がすでに存在する場合、テキストの値はtextで置換されます。 localeパラメータは、nullにすべきではありません

        コード例: 

        
 SOAPFault fault = ...;
 fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
        パラメータ:
        text - -- 理由メッセージの文字列
        locale - -- メッセージのロケールを表現するLocaleオブジェクト
        例外:
        SOAPException - Reason Textの追加でエラーが発生した場合、または渡されたlocaleがnullの場合。
        UnsupportedOperationException - このメッセージが、SOAP 1.2のFault Reasonの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • getFaultNode

        String getFaultNode​()
        このSOAPFaultオブジェクトの、オプションのNode要素値を返します。 Node要素は、SOAP 1.2では省略可能です。
        戻り値:
        Stringとしてのenv:Fault/env:Node要素のコンテンツ。ない場合はnull
        例外:
        UnsupportedOperationException - このメッセージが、SOAP 1.2のFault Nodeの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • setFaultNode

        void setFaultNode​(String uri)
           throws SOAPException
        このSOAPFaultオブジェクトの既存のNode要素値を作成または置換します。 Node要素は、SOAP 1.2では省略可能です。
        パラメータ:
        uri - - ノードのURI
        例外:
        SOAPException - このSOAPFaultオブジェクトのNodeの設定時にエラーが発生した場合。
        UnsupportedOperationException - このメッセージが、SOAP 1.2のFault Nodeの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • getFaultRole

        String getFaultRole​()
        このSOAPFaultオブジェクトの、オプションのRole要素値を返します。 Role要素は、SOAP 1.2では省略可能です。
        戻り値:
        Stringとしてのenv:Fault/env:Role要素のコンテンツ。ない場合はnull
        例外:
        UnsupportedOperationException - このメッセージが、SOAP 1.2のFault Roleの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3

      • setFaultRole

        void setFaultRole​(String uri)
           throws SOAPException
        このSOAPFaultオブジェクトの既存のRole要素値を作成または置換します。 Role要素は、SOAP 1.2では省略可能です。
        パラメータ:
        uri - - RoleのURI
        例外:
        SOAPException - このSOAPFaultオブジェクトのRoleの設定時にエラーが発生した場合。
        UnsupportedOperationException - このメッセージが、SOAP 1.2のFault Roleの概念をサポートしない場合。
        導入されたバージョン:
        1.6, SAAJ 1.3