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() この SOAPFault が Detail サブ要素を保持する場合は 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()

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

戻り値:

この SOAPFault が Detail サブ要素を保持する場合は 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 テキストの追加でエラーが発生した場合、または渡された locale が null の場合

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