org.ksoap2.transport
Class HttpTransport

java.lang.Object
  org.ksoap2.transport.Transport
      org.ksoap2.transport.HttpTransport

Direct Known Subclasses:

HttpTransportBasicAuth

public class HttpTransport
extends Transport

Methods to facilitate SOAP calls over HTTP using the J2ME generic connection framework.

Instances of HttpTransport can be in one of two states: connected and not connected. When an invocation on call is made the instance is in a connected state until call returns or throws an IOException. in any case once control is returned to the caller the instance is again in the not connected state. HttpTransport is not thread safe and applications should ensure that only one thread is inside the call method at any given time. It is designed in such a way that applications can reuse a single instance for all soap calls to one, or multiple, target endpoints.

The underlying HttpConnection is opened with the timeout flag set. In the MIDP API this flag is only a hint to the underlying protocol handler to throw an InterrruptIOException, however, there are no guarantees that it will be handled. So rather than support a timeout mechanism internally the design is such that applications can manage timeouts in an environment dependent way.

For example some environments may allow for a timeout parameter that can be externally specified in perhaps a system property (which? I don't know. it's in the api). Others like the emulator (ok, who cares) and the Motorola i85s can use a simple and effective timeout mechanism that closes the connection and associated streams in an asynchronous fashion. Calling the close( ) method inside of a separate thread can provide for this timeout handling by releasing threads that maybe stuck inside of call( ) performing network io.

Here is some sample code to demonstrate how such a timeout mechanism may look:

    private HttpTransport soap;
    ...
    TimerTask task =
    new TimerTask( ) { public void run( ) { soap.close( ); } };
   
    try {
    new Timer( ).schedule( task, TIMEOUT );
    soap.call( soapobject );  // invoke method
    task.cancel( );           // cancel the timeout
   
    } catch ( InterruptedIOException e ) {
    // handle timeout here...
   
    } catch ( IOException e ) {
    // some other io problem...
    }
 

The call( ) method will throw and InterruptedIOException if the instance is no longer in the connected state before control is returned to the caller. The call to soap.close( ) inside the TimerTask transitions the HttpConnection into a not connected state.

Note: The InterruptedIOException will be caught by a thread waiting on network io, however, it may not be immediate. It is assumed that the protocol handler will gracefully handle the lifecycle of the outputstream and therefore it is not closed inside the close method. IOW the waiting thread will be interrupted after the outputstream has been flushed. If the waiting thread is hung up waiting for input a call to close from a separate thread the exception is observed right away and will return before the thread calling close. At least this is what has been observation on the i85s handset. On this device, if a call to outputstream.close( ) is made while the outputstream is being flushed it seems to cause a deadlock, ie outputstream will never return.

Field Summary

Fields inherited from class org.ksoap2.transport.Transport

debug, requestDump, responseDump

Constructor Summary

HttpTransport(java.lang.String url)
Creates instance of HttpTransport with set url

Method Summary

void	call(java.lang.String soapAction, SoapEnvelope envelope) set the desired soapAction header field
void	reset() Closes the connection and associated streams.

Methods inherited from class org.ksoap2.transport.Transport

setUrl, setXmlVersionTag

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HttpTransport

public HttpTransport(java.lang.String url)

Creates instance of HttpTransport with set url

Parameters:

url - the destination to POST SOAP data

Method Detail

call

public void call(java.lang.String soapAction,
                 SoapEnvelope envelope)
          throws java.io.IOException,
                 org.xmlpull.v1.XmlPullParserException

set the desired soapAction header field

Specified by:

call in class Transport

Parameters:

soapAction - the desired soapAction

envelope - the envelope the contains the information for the call.

Throws:

java.io.IOException

org.xmlpull.v1.XmlPullParserException

reset

public void reset()

Closes the connection and associated streams. This method does not need to be explictly called since the uderlying connections and streams are only opened and valid inside of the call method. Close can be called ansynchronously, from another thread to potentially release another thread that is hung up doing network io inside of call. Caution should be taken, however when using this as a psedu timeout mechanism. it is a valid and suggested approach for the motorola handsets. oh, and it works in the emulator...

Overrides:

reset in class Transport