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

インタフェースSOAPEnvelope

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

    public interface SOAPEnvelope
extends SOAPElement
    SOAPPartオブジェクトのSOAPHeaderとSOAPBody部分のコンテナです。 デフォルトでは、SOAPMessageオブジェクトはSOAPEnvelopeオブジェクトを保持するSOAPPartオブジェクトで作成されます。 デフォルトではSOAPEnvelopeオブジェクトは、空のSOAPBodyオブジェクトと空のSOAPHeaderオブジェクトを保有しています。 SOAPBodyオブジェクトは必須です。SOAPHeaderオブジェクトはオプションですが、ほとんどの場合に使用されています。 SOAPHeaderオブジェクトが不要な場合には、削除できます(後述)。

    クライアントは、SOAPEnvelope.getHeaderやSOAPEnvelope.getBodyメソッドを呼び出すことで、SOAPHeaderやSOAPBodyオブジェクトにアクセスできます。 次のコードでは、まずSOAPMessageオブジェクトのmessageでSOAPPartオブジェクトのspを取得した後、これらの2つのメソッドを使用します。spは次に、SOAPEnvelopeオブジェクトのseを取得するのに使用します。 

    
     SOAPPart sp = message.getSOAPPart();
     SOAPEnvelope se = sp.getEnvelope();
     SOAPHeader sh = se.getHeader();
     SOAPBody sb = se.getBody();

    SOAPEnvelopeオブジェクトの本体やヘッダーは、現行のものを取得したり、削除したり、新しいものを追加したりすることで変更できます。 javax.xml.soap.NodeのメソッドdeleteNodeは、呼び出されたXML要素(ノード)を削除します。 たとえば、次のコードは、getBodyメソッドで取得したSOAPBodyオブジェクトを削除します。 

    
      se.getBody().detachNode();
    SOAPHeaderオブジェクトを作成して削除したオブジェクトと置き換える場合、クライアントは、SOAPEnvelope.addHeaderメソッドを使用します。このメソッドを使用すると、新しいヘッダーが作成され、SOAPEnvelopeオブジェクトに追加されます。 同様に、addBodyメソッドも新しいSOAPBodyオブジェクトを作成し、SOAPEnvelopeオブジェクトに追加します。 次のコードの抜粋では、現在のヘッダーを取得してそれを削除し、新しいヘッダーを追加します。 続いて、現在の本体を取得してそれを削除し、新しい本体を追加します。 
    
     SOAPPart sp = message.getSOAPPart();
     SOAPEnvelope se = sp.getEnvelope();
     se.getHeader().detachNode();
     SOAPHeader sh = se.addHeader();
     se.getBody().detachNode();
     SOAPBody sb = se.addBody();
    すでにSOAPBodyオブジェクトやSOAPHeaderオブジェクトが存在している場合、これらを追加するとエラーになります。

    SOAPEnvelopeインタフェースは、Nameオブジェクトを作成する3つのメソッドを提供します。 1つ目のメソッドは、ローカル名、名前空間接頭辞、名前空間URIを使用してNameオブジェクトを作成します。 2つ目のメソッドは、ローカル名と名前空間の接頭辞を使用してNameオブジェクトを作成します。3つ目のメソッドは、ローカル名のみを使用してNameオブジェクトを作成します。 次のコード行(seはSOAPEnvelopeオブジェクト)では、3つすべてを使用して新しいNameオブジェクトを作成します。 

    
     Name name = se.createName("GetLastTradePrice", "WOMBAT",
                                "http://www.wombat.org/trader");
    導入されたバージョン:
    1.6

    • メソッドの詳細

      • createName

        Name createName​(String localName,
                String prefix,
                String uri)
         throws SOAPException
        指定したローカル名、名前空間接頭辞および名前空間URIを使用して初期化された新しいNameオブジェクトを作成します。

        このファクトリ・メソッドは、SOAP/XMLドキュメントで使用するNameオブジェクトを作成します。

        パラメータ:
        localName - ローカル名を指定するString
        prefix - 名前空間の接頭辞を指定するString
        uri - 名前空間のURIを指定するString
        戻り値:
        指定のローカル名、名前空間接頭辞、および名前空間URIで初期化されたNameオブジェクト
        例外:
        SOAPException - SOAPエラーが存在する場合

      • createName

        Name createName​(String localName)
         throws SOAPException
        指定されたローカル名を使用して初期化された新しいNameオブジェクトを作成します。

        このファクトリ・メソッドは、SOAP/XMLドキュメントで使用するNameオブジェクトを作成します。

        パラメータ:
        localName - ローカル名を指定するString
        戻り値:
        指定のローカル名で初期化されたNameオブジェクト
        例外:
        SOAPException - SOAPエラーが存在する場合

      • getHeader

        SOAPHeader getHeader​()
              throws SOAPException
        このSOAPEnvelopeオブジェクトのSOAPHeaderオブジェクトを返します。

        デフォルトでは、新しいSOAPMessageオブジェクトの作成に、空のSOAPHeaderオブジェクトを保持するSOAPEnvelopeオブジェクトを使用します。 そのため、getHeaderメソッドは、ヘッダーを削除して新しいものが追加されなかった場合を除き、常にSOAPHeaderオブジェクトを返します。

        戻り値:
        SOAPHeaderオブジェクト。ない場合はnull
        例外:
        SOAPException - SOAPHeaderオブジェクトの取得時に問題が発生した場合

      • getBody

        SOAPBody getBody​()
          throws SOAPException
        このSOAPEnvelopeオブジェクトに関連付けられたSOAPBodyオブジェクトを返します。

        デフォルトでは、新しいSOAPMessageオブジェクトの作成に、空のSOAPBodyオブジェクトを保持するSOAPEnvelopeオブジェクトを使用します。 そのため、getBodyメソッドは、本体を削除して新しいものが追加されなかった場合を除き、常にSOAPBodyオブジェクトを返します。

        戻り値:
        このSOAPEnvelopeのSOAPBodyオブジェクト。存在しない場合はnull
        例外:
        SOAPException - SOAPBodyオブジェクトの取得時に問題が発生した場合

      • addHeader

        SOAPHeader addHeader​()
              throws SOAPException
        SOAPHeaderオブジェクトを作成し、それをこのSOAPEnvelopeオブジェクトのSOAPHeaderオブジェクトとして設定します。

        エンベロープにすでにヘッダーが含まれている場合、ヘッダーを追加することはできません。 そのため、このメソッドは既存のヘッダーを削除してから呼び出してください。

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

      • addBody

        SOAPBody addBody​()
          throws SOAPException
        SOAPBodyオブジェクトを作成し、それをこのSOAPEnvelopeオブジェクトのSOAPBodyオブジェクトとして設定します。

        エンベロープにすでに本体が含まれている場合、本体を追加することはできません。 そのため、このメソッドは既存の本体を削除してから呼び出してください。

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