JavaTM Platform
Standard Ed. 6

javax.xml.soap
インタフェース SOAPFault

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

public interface SOAPFault
extends SOAPBodyElement

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

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


フィールドの概要
 
インタフェース org.w3c.dom.Node から継承されたフィールド
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
 
メソッドの概要
 Detail addDetail()
          省略可能な Detail オブジェクトを作成し、それをこの SOAPFault オブジェクトの Detail オブジェクトとして設定します。
 void addFaultReasonText(String text, Locale locale)
          指定したテキストメッセージおよび locale から派生した xml:lang を含む Reason Text 項目を追加または置換します。
 void appendFaultSubcode(QName subcode)
          この SOAPFault によって格納されるサブコードのシーケンスの最後に、サブコードを追加します。
 Detail getDetail()
          この SOAPFault オブジェクトの、省略可能な詳細要素を返します。
 String getFaultActor()
          この SOAPFault オブジェクトのフォルトアクターを取得します。
 String getFaultCode()
          この SOAPFault オブジェクトのフォルトコードを取得します。
 Name getFaultCodeAsName()
          この SOAPFault オブジェクトの必須 SOAP 1.1 フォルトコードを、SAAJ Name オブジェクトとして取得します。
 QName getFaultCodeAsQName()
          この SOAPFault のフォルトコードを QName オブジェクトとして取得します。
 String getFaultNode()
          この SOAPFault オブジェクトの、省略可能な Node 要素を返します。
 Iterator getFaultReasonLocales()
          関連付けられた Reason Text 項目がある Locale の別々のシーケンスについての Iterator を返します。
 String getFaultReasonText(Locale locale)
          指定した Locale と関連付けられた Reason Text を返します。
 Iterator getFaultReasonTexts()
          この SOAPFault の Reason Text 項目すべてを含む String オブジェクトのシーケンスについての Iterator を返します。
 String getFaultRole()
          この SOAPFault オブジェクトの、省略可能な Role 要素を返します。
 String getFaultString()
          この SOAPFault オブジェクトのフォルト文字列を取得します。
 Locale getFaultStringLocale()
          この SOAPFault オブジェクトのフォルト文字列のロケールを取得します。
 Iterator getFaultSubcodes()
          この SOAPFault のサブコードを、QName の反復子として取得します。
 boolean hasDetail()
          この SOAPFaultDetail サブ要素を保持する場合は true、そうでない場合は false を返します。
 void removeAllFaultSubcodes()
          この SOAPFault によって格納されるサブコードを削除します。
 void setFaultActor(String faultActor)
          指定したフォルトアクターで SOAPFault オブジェクトを設定します。
 void setFaultCode(Name faultCodeQName)
          指定したフォルトコードで SOAPFault オブジェクトを設定します。
 void setFaultCode(QName faultCodeQName)
          指定したフォルトコードで SOAPFault オブジェクトを設定します。
 void setFaultCode(String faultCode)
          指定したフォルトコードで SOAPFault オブジェクトを設定します。
 void setFaultNode(String uri)
          この SOAPFault オブジェクトの既存の Node 要素値を作成または置換します。
 void setFaultRole(String uri)
          この SOAPFault オブジェクトの既存の Role 要素値を作成または置換します。
 void setFaultString(String faultString)
          指定した文字列に対して、この SOAPFault のフォルト文字列を設定します。
 void setFaultString(String faultString, Locale locale)
          指定した文字列に対して、この SOAPFault のフォルト文字列を設定し、指定したロケールへローカライズします。
 
インタフェース javax.xml.soap.SOAPElement から継承されたメソッド
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
 
インタフェース javax.xml.soap.Node から継承されたメソッド
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
 
インタフェース org.w3c.dom.Element から継承されたメソッド
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
 
インタフェース org.w3c.dom.Node から継承されたメソッド
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData
 

メソッドの詳細

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 ツリーに追加するときに、エラーが発生した場合
導入されたバージョン:
SAAJ 1.2
関連項目:
getFaultCodeAsName()

setFaultCode

void setFaultCode(QName faultCodeQName)
                  throws SOAPException
指定したフォルトコードで SOAPFault オブジェクトを設定します。 このメソッドを setFaultCode(Name) に対して使用するのが適切です。

パラメータ:
faultCodeQName - 設定するフォルトコードを示す QName オブジェクト。名前空間で修飾されている必要がある
例外:
SOAPException - faultcode 要素を基本となる XML ツリーに追加するときに、エラーが発生した場合
導入されたバージョン:
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
導入されたバージョン:
SAAJ 1.2
関連項目:
setFaultCode(Name)

getFaultCodeAsQName

QName getFaultCodeAsQName()
この SOAPFault のフォルトコードを QName オブジェクトとして取得します。

戻り値:
フォルトコードを表現する QName
導入されたバージョン:
SAAJ 1.3
関連項目:
setFaultCode(QName)

getFaultSubcodes

Iterator getFaultSubcodes()
この SOAPFault のサブコードを、QName の反復子として取得します。

戻り値:
QNames のシーケンスにアクセスする Iterator。この Iterator は、省略可能な remove メソッドをサポートすべきではない。サブコードが返される順序には、フォルトに存在する上から下へのサブコードの階層が反映される
例外:
UnsupportedOperationException - このメッセージが、SOAP 1.2 のサブコードの概念をサポートしない場合
導入されたバージョン:
SAAJ 1.3

removeAllFaultSubcodes

void removeAllFaultSubcodes()
この SOAPFault によって格納されるサブコードを削除します。以降 getFaultSubcodes を呼び出すと、appendFaultSubcode への呼び出しが行われるまで空の反復子が返されます。

例外:
UnsupportedOperationException - このメッセージが、SOAP 1.2 のサブコードの概念をサポートしない場合
導入されたバージョン:
SAAJ 1.3

appendFaultSubcode

void appendFaultSubcode(QName subcode)
                        throws SOAPException
この SOAPFault によって格納されるサブコードのシーケンスの最後に、サブコードを追加します。サブコードは SOAP 1.2 で導入されましたが、SOAP Fault の必須 Code サブ要素をルートとする、サブ要素の再帰的なシーケンスによって表現されます。

パラメータ:
subcode - サブコードの値を格納する QName
例外:
SOAPException - サブコードの設定時にエラーが発生した場合
UnsupportedOperationException - このメッセージが、SOAP 1.2 のサブコードの概念をサポートしない場合
導入されたバージョン:
SAAJ 1.3

getFaultCode

String getFaultCode()
この SOAPFault オブジェクトのフォルトコードを取得します。

戻り値:
フォルトコードを含む String
関連項目:
getFaultCodeAsName(), setFaultCode(javax.xml.soap.Name)

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 ツリーに追加するときに、エラーが発生した場合
導入されたバージョン:
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
導入されたバージョン:
SAAJ 1.2
関連項目:
setFaultString(String, Locale)

hasDetail

boolean hasDetail()
この SOAPFaultDetail サブ要素を保持する場合は true、そうでない場合は false を返します。(getDetail()!=null) と同じです。

戻り値:
この SOAPFaultDetail サブ要素を保持する場合は true、そうでない場合は false
導入されたバージョン:
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 getFaultReasonLocales()
                               throws SOAPException
関連付けられた Reason Text 項目がある Locale の別々のシーケンスについての Iterator を返します。これらの Locale はどれでも、Reason Text 文字列のローカライズされたバージョンを取得するために getFaultReasonText への呼び出しで使用できます。

戻り値:
関連付けられた Reason Text 項目がある Locale オブジェクトのシーケンスの Iterator
例外:
SOAPException - フォルト Reason のロケールの取得でエラーが発生した場合
UnsupportedOperationException - このメッセージが、SOAP 1.2 の Fault Reason の概念をサポートしない場合
導入されたバージョン:
SAAJ 1.3

getFaultReasonTexts

Iterator getFaultReasonTexts()
                             throws SOAPException
この SOAPFault の Reason Text 項目すべてを含む String オブジェクトのシーケンスについての Iterator を返します。

戻り値:
env:Fault/env:Reason/env:Text 項目についての Iterator
例外:
SOAPException - フォルト Reason のテキストの取得でエラーが発生した場合
UnsupportedOperationException - このメッセージが、SOAP 1.2 の Fault Reason の概念をサポートしない場合
導入されたバージョン:
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 テキストの取得でエラーが発生した場合
UnsupportedOperationException - このメッセージが、SOAP 1.2 の Fault Reason の概念をサポートしない場合
導入されたバージョン:
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 テキストの追加でエラーが発生した場合、または渡された localenull の場合
UnsupportedOperationException - このメッセージが、SOAP 1.2 の Fault Reason の概念をサポートしない場合
導入されたバージョン:
SAAJ 1.3

getFaultNode

String getFaultNode()
この SOAPFault オブジェクトの、省略可能な Node 要素を返します。Node 要素は、SOAP 1.2 では省略可能です。

戻り値:
String としての env:Fault/env:Node 要素のコンテンツ。ない場合は null
例外:
UnsupportedOperationException - このメッセージが、SOAP 1.2 の Fault Node の概念をサポートしない場合
導入されたバージョン:
SAAJ 1.3

setFaultNode

void setFaultNode(String uri)
                  throws SOAPException
この SOAPFault オブジェクトの既存の Node 要素値を作成または置換します。Node 要素は、SOAP 1.2 では省略可能です。

例外:
SOAPException - この SOAPFault オブジェクトの Node の設定時にエラーが発生した場合
UnsupportedOperationException - このメッセージが、SOAP 1.2 の Fault Node の概念をサポートしない場合
導入されたバージョン:
SAAJ 1.3

getFaultRole

String getFaultRole()
この SOAPFault オブジェクトの、省略可能な Role 要素を返します。Role 要素は、SOAP 1.2 では省略可能です。

戻り値:
String としての env:Fault/env:Role 要素のコンテンツ。ない場合は null
例外:
UnsupportedOperationException - このメッセージが、SOAP 1.2 の Fault Role の概念をサポートしない場合
導入されたバージョン:
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 の概念をサポートしない場合
導入されたバージョン:
SAAJ 1.3

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。