Home | History | Annotate | Download | only in ksoap2 
      1 /* Copyright (c) 2003,2004, Stefan Haustein, Oberhausen, Rhld., Germany
      2  *
      3  * Permission is hereby granted, free of charge, to any person obtaining a copy
      4  * of this software and associated documentation files (the "Software"), to deal
      5  * in the Software without restriction, including without limitation the rights
      6  * to use, copy, modify, merge, publish, distribute, sublicense, and/or
      7  * sell copies of the Software, and to permit persons to whom the Software is
      8  * furnished to do so, subject to the following conditions:
      9  *
     10  * The  above copyright notice and this permission notice shall be included in
     11  * all copies or substantial portions of the Software.
     12  *
     13  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     14  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     15  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
     16  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     17  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
     18  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
     19  * IN THE SOFTWARE. */
     20 
     21 package org.ksoap2;
     22 
     23 import java.io.*;
     24 import org.ksoap2.kdom.*;
     25 import org.xmlpull.v1.*;
     26 
     27 /**
     28  * A SOAP envelope, holding head and body objects. While this basic envelope
     29  * supports literal encoding as content format via KDom, The
     30  * SoapSerializationEnvelope provides support for the SOAP Serialization format
     31  * specification and simple object serialization.
     32  */
     33 
     34 public class SoapEnvelope {
     35 
     36     /** SOAP Version 1.0 constant */
     37     public static final int VER10 = 100;
     38     /** SOAP Version 1.1 constant */
     39     public static final int VER11 = 110;
     40     /** SOAP Version 1.2 constant */
     41     public static final int VER12 = 120;
     42     public static final String ENV2003 = "http://www.w3.org/2003/05/soap-envelope";
     43     public static final String ENC2003 = "http://www.w3.org/2003/05/soap-encoding";
     44     /** Namespace constant: http://schemas.xmlsoap.org/soap/envelope/ */
     45     public static final String ENV = "http://schemas.xmlsoap.org/soap/envelope/";
     46     /** Namespace constant: http://schemas.xmlsoap.org/soap/encoding/ */
     47     public static final String ENC = "http://schemas.xmlsoap.org/soap/encoding/";
     48     /** Namespace constant: http://www.w3.org/2001/XMLSchema */
     49     public static final String XSD = "http://www.w3.org/2001/XMLSchema";
     50     /** Namespace constant: http://www.w3.org/2001/XMLSchema */
     51     public static final String XSI = "http://www.w3.org/2001/XMLSchema-instance";
     52     /** Namespace constant: http://www.w3.org/1999/XMLSchema */
     53     public static final String XSD1999 = "http://www.w3.org/1999/XMLSchema";
     54     /** Namespace constant: http://www.w3.org/1999/XMLSchema */
     55     public static final String XSI1999 = "http://www.w3.org/1999/XMLSchema-instance";
     56 
     57     public static final String NS20 = "http://www.wi-fi.org/specifications/hotspot2dot0/v1.0/spp";
     58 
     59 
     60     /**
     61      * Returns true for the string values "1" and "true", ignoring upper/lower
     62      * case and whitespace, false otherwise.
     63      */
     64     public static boolean stringToBoolean(String booleanAsString) {
     65         if (booleanAsString == null) {
     66             return false;
     67         }
     68         booleanAsString = booleanAsString.trim().toLowerCase();
     69         return (booleanAsString.equals("1") || booleanAsString.equals("true"));
     70     }
     71 
     72     /**
     73      * The body object received with this envelope. Will be an KDom Node for
     74      * literal encoding. For SOAP Serialization, please refer to
     75      * SoapSerializationEnvelope.
     76      */
     77     public Object bodyIn;
     78     /**
     79      * The body object to be sent with this envelope. Must be a KDom Node
     80      * modelling the remote call including all parameters for literal encoding.
     81      * For SOAP Serialization, please refer to SoapSerializationEnvelope
     82      */
     83     public Object bodyOut;
     84     /**
     85      * Incoming header elements
     86      */
     87     public Element[] headerIn;
     88     /**
     89      * Outgoing header elements
     90      */
     91     public Element[] headerOut;
     92     public String encodingStyle;
     93     /**
     94      * The SOAP version, set by the constructor
     95      */
     96     public int version;
     97     /** Envelope namespace, set by the constructor */
     98     public String env;
     99     /** Encoding namespace, set by the constructor */
    100     public String enc;
    101     /** Xml Schema instance namespace, set by the constructor */
    102     public String xsi;
    103     /** Xml Schema data namespace, set by the constructor */
    104     public String xsd;
    105 
    106     // HS20 change
    107     public String ns;
    108 
    109     /**
    110      * Initializes a SOAP Envelope. The version parameter must be set to one of
    111      * VER10, VER11 or VER12
    112      */
    113     public SoapEnvelope(int version) {
    114         this.version = version;
    115         if (version == SoapEnvelope.VER10) {
    116             xsi = SoapEnvelope.XSI1999;
    117             xsd = SoapEnvelope.XSD1999;
    118         } else {
    119             xsi = SoapEnvelope.XSI;
    120             xsd = SoapEnvelope.XSD;
    121         }
    122         if (version < SoapEnvelope.VER12) {
    123             enc = SoapEnvelope.ENC;
    124             env = SoapEnvelope.ENV;
    125         } else {
    126             enc = SoapEnvelope.ENC2003;
    127             env = SoapEnvelope.ENV2003;
    128         }
    129         // HS20 change
    130         ns = SoapEnvelope.NS20;
    131     }
    132 
    133     /** Parses the SOAP envelope from the given parser */
    134     public void parse(XmlPullParser parser) throws IOException, XmlPullParserException {
    135         parser.nextTag();
    136         parser.require(XmlPullParser.START_TAG, env, "Envelope");
    137         encodingStyle = parser.getAttributeValue(env, "encodingStyle");
    138         parser.nextTag();
    139         if (parser.getEventType() == XmlPullParser.START_TAG
    140                 && parser.getNamespace().equals(env)
    141                 && parser.getName().equals("Header")) {
    142             parseHeader(parser);
    143             parser.require(XmlPullParser.END_TAG, env, "Header");
    144             parser.nextTag();
    145         }
    146         parser.require(XmlPullParser.START_TAG, env, "Body");
    147         encodingStyle = parser.getAttributeValue(env, "encodingStyle");
    148         parseBody(parser);
    149         parser.require(XmlPullParser.END_TAG, env, "Body");
    150         parser.nextTag();
    151         parser.require(XmlPullParser.END_TAG, env, "Envelope");
    152     }
    153 
    154     public void parseHeader(XmlPullParser parser) throws IOException, XmlPullParserException {
    155         // consume start header
    156         parser.nextTag();
    157         // look at all header entries
    158         Node headers = new Node();
    159         headers.parse(parser);
    160         int count = 0;
    161         for (int i = 0; i < headers.getChildCount(); i++) {
    162             Element child = headers.getElement(i);
    163             if (child != null) {
    164                 count++;
    165             }
    166         }
    167         headerIn = new Element[count];
    168         count = 0;
    169         for (int i = 0; i < headers.getChildCount(); i++) {
    170             Element child = headers.getElement(i);
    171             if (child != null) {
    172                 headerIn[count++] = child;
    173             }
    174         }
    175     }
    176 
    177     public void parseBody(XmlPullParser parser) throws IOException, XmlPullParserException {
    178         parser.nextTag();
    179         // insert fault generation code here
    180         if (parser.getEventType() == XmlPullParser.START_TAG
    181                 && parser.getNamespace().equals(env)
    182                 && parser.getName().equals("Fault")) {
    183 
    184             SoapFault fault;
    185             if (this.version < SoapEnvelope.VER12) {
    186                 fault = new SoapFault(this.version);
    187             } else {
    188                 fault = new SoapFault12(this.version);
    189             }
    190             fault.parse(parser);
    191             bodyIn = fault;
    192         } else {
    193             Node node = (bodyIn instanceof Node) ? (Node) bodyIn : new Node();
    194             node.parse(parser);
    195             bodyIn = node;
    196         }
    197     }
    198 
    199     /**
    200      * Writes the complete envelope including header and body elements to the
    201      * given XML writer.
    202      */
    203     public void write(XmlSerializer writer) throws IOException {
    204         // HS 2.0 changes
    205         writer.setPrefix("soap", env); //the prefix for namespace env in xml output
    206         writer.setPrefix("spp", ns);
    207 
    208         writer.startTag(env, "Envelope");
    209         writer.startTag(env, "Header");
    210         writeHeader(writer);
    211         writer.endTag(env, "Header");
    212         writer.startTag(env, "Body");
    213         writeBody(writer);
    214         writer.endTag(env, "Body");
    215         writer.endTag(env, "Envelope");
    216     }
    217 
    218     /**
    219      * Writes the header elements contained in headerOut
    220      */
    221     public void writeHeader(XmlSerializer writer) throws IOException {
    222         if (headerOut != null) {
    223             for (int i = 0; i < headerOut.length; i++) {
    224                 headerOut[i].write(writer);
    225             }
    226         }
    227     }
    228 
    229     /**
    230      * Writes the SOAP body stored in the object variable bodyIn, Overwrite this
    231      * method for customized writing of the soap message body.
    232      */
    233     public void writeBody(XmlSerializer writer) throws IOException {
    234         if (encodingStyle != null) {
    235             writer.attribute(env, "encodingStyle", encodingStyle);
    236         }
    237         ((Node) bodyOut).write(writer);
    238     }
    239 
    240     /**
    241      * Assigns the object to the envelope as the outbound message for the soap call.
    242      * @param soapObject the object to send in the soap call.
    243      */
    244     public void setOutputSoapObject(Object soapObject) {
    245         bodyOut = soapObject;
    246     }
    247 
    248 }
    249