Home | History | Annotate | Download | only in transport 
      1 /* Copyright (c) 2003,2004, Stefan Haustein, Oberhausen, Rhld., Germany
      2  * Copyright (c) 2006, James Seigel, Calgary, AB., Canada
      3  *
      4  * Permission is hereby granted, free of charge, to any person obtaining a copy
      5  * of this software and associated documentation files (the "Software"), to deal
      6  * in the Software without restriction, including without limitation the rights
      7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or
      8  * sell copies of the Software, and to permit persons to whom the Software is
      9  * furnished to do so, subject to the following conditions:
     10  *
     11  * The  above copyright notice and this permission notice shall be included in
     12  * all copies or substantial portions of the Software.
     13  *
     14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
     17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
     19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
     20  * IN THE SOFTWARE. */
     21 
     22 package org.ksoap2.transport;
     23 
     24 import java.io.IOException;
     25 import java.io.InputStream;
     26 import java.io.OutputStream;
     27 import java.util.List;
     28 
     29 /**
     30  * Interface to allow the abstraction of the raw transport information
     31  */
     32 public interface ServiceConnection {
     33 
     34     public static final int DEFAULT_TIMEOUT = 20000; // 20 seconds
     35     public static final int DEFAULT_BUFFER_SIZE = 256 * 1024; // 256 Kb
     36 
     37     /**
     38      * Make an outgoing connection.
     39      */
     40     public void connect() throws IOException;
     41 
     42     /**
     43      * Disconnect from the outgoing connection
     44      */
     45     public void disconnect() throws IOException;
     46 
     47     /**
     48      * Returns to the caller all of the headers that were returned with the
     49      * response to the SOAP request. Primarily this gives the caller an
     50      * opportunity to save the cookies for later use.
     51      *
     52      * @return List of HeaderProperty instances that were returned as part of the http response
     53      * as http header
     54      * properties
     55      */
     56     public List getResponseProperties() throws IOException;
     57 
     58     /**
     59      * Returns the numerical HTTP status to the caller
     60      *
     61      * @return an integer status value
     62      */
     63     public int getResponseCode() throws IOException;
     64 
     65     /**
     66      * Set properties on the outgoing connection.
     67      *
     68      * @param propertyName the name of the property to set. For HTTP connections these
     69      *                     are the request properties in the HTTP Header.
     70      * @param value        the string to set the property header to.
     71      */
     72     public void setRequestProperty(String propertyName, String value) throws IOException;
     73 
     74     /**
     75      * Sets how to make the requests. For HTTP this is typically POST or GET.
     76      *
     77      * @param requestMethodType the type of request method to make the soap call with.
     78      */
     79     public void setRequestMethod(String requestMethodType) throws IOException;
     80 
     81     /**
     82      * If the length of a HTTP request body is known ahead, sets fixed length
     83      * to enable streaming without buffering. Sets after connection will cause an exception.
     84      *
     85      * @param contentLength the fixed length of the HTTP request body
     86      * @see http://developer.android.com/reference/java/net/HttpURLConnection.html
     87      **/
     88     public void setFixedLengthStreamingMode(int contentLength);
     89 
     90     public void setChunkedStreamingMode();
     91 
     92     /**
     93      * Open and return the outputStream to the endpoint.
     94      *
     95      * @return the output stream to write the soap message to.
     96      */
     97     public OutputStream openOutputStream() throws IOException;
     98 
     99     /**
    100      * Opens and returns the inputstream from which to parse the result of the
    101      * soap call.
    102      *
    103      * @return the inputstream containing the xml to parse the result from the
    104      * call from.
    105      */
    106     public InputStream openInputStream() throws IOException;
    107 
    108     /**
    109      * @return the error stream for the call.
    110      */
    111     public InputStream getErrorStream();
    112 
    113     /**
    114      * Return the name of the host that is specified as the web service target
    115      *
    116      * @return Host name
    117      */
    118     abstract public String getHost();
    119 
    120     /**
    121      * Return the port number of the host that is specified as the web service target
    122      *
    123      * @return Port number
    124      */
    125     abstract public int getPort();
    126 
    127     /**
    128      * Return the path to the web service target
    129      *
    130      * @return The URL's path
    131      */
    132     abstract public String getPath();
    133 }
    134