Introduction

The SoapLite Transport is a Transport implementation supporting the SOAP 1.1 protocol over HTTP or HTTPS. SOAP messages exchanged over the network are formtted according to the Document/Literal message format defined in the WSDL 1.1 specification.

This transport is a good choice if the remote service provided by a Remoting-based C++ application must be accessible by clients written using other frameworks or even other programming languages or runtimes, such as Java or .NET.

The SoapLite transport only supports interoperability with other SOAP 1.1 implementations (such as those available for Java or .NET) in one direction. Java or .NET clients can consume a web service implemented using Remoting and the SoapLite transport. However, the opposite is not supported. There is currently no way to take an arbitrary WSDL file generated by another SOAP implementation, and generate Remoting code from that.

Basic SoapLite Transport Usage

Server Usage

To use the SoapLite Transport in a server, the following three steps must be performed:

1. register the Poco::Remoting::SoapLite::TransportFactory with the ORB,
2. register a Poco::Remoting::SoapLite::Listener with the ORB, and finally,
3. register the individual objects with the ORB.

Furthermore, a @namespace attribute must be added to the service class declaration. Otherwise, a run time error will occur when trying to invoke the web service.

Following is an example code fragment for setting up a SoapLite Transport listener, and registering a service object for use with the listener.

Poco::Remoting::SoapLite::TransportFactory::registerFactory();
Poco::Remoting::ORB::instance().registerListener(
    new PocoRemoting::SoapLite::Listener(10001)
);
st::string uri = MyProject::MyClassHelper::registerObject(
    new MyProject::MyClass, 
    "MyObject", 
    10001, 
    Poco::Remoting::SoapLite::Transport::ID
);

Client Usage

To use the SoapLite Transport in a client, the following two steps must be performed:

1. register the Poco::Remoting::SoapLite::TransportFactory with the ORB, and
2. retrieve the interface (proxy) object using the helper class.

Following is an example code fragment for setting up a SoapLite Transport, and registering a service object for use with the transport.

Poco::Remoting::SoapLite::TransportFactory::registerFactory();
MyProject::IMyClass::Ptr ptrObj = MyProject::MyClassHelper::findObject(
    hostName, 
    "MyObject", 
    10001, 
    Poco::Remoting::SoapLite::Transport::ID
);

Performance Considerations

The performance of the SoapLite Transport is considerably lower than the that of the Binary Transport. Some of the reasons for this are:

• XML generation and especially XML parsing overhead,
• SOAP message overhead (SOAP envelope, header and body elements),
• XML uses way more bandwidth than a binary protocol, and
• the HTTP overhead is larger than the overhead for a simple socket connection.

Applications where remote method call performance is critical, and which do not need to work with non Remoting applications should therefore prefer the Binary transport to the SoapLite transport.

C++ to XML Schema Type Mappings

The following table shows how C++ (and POCO types) are mapped to XML Schema (XSD) types.

C++ Type              XSD Type
-----------------------------------
bool                  boolean
char                  byte
signed char           byte
unsigned char         unsignedByte
short                 short
unsigned short        unsignedShort
int                   int
unsigned int          unsignedInt
long                  int
unsigned long         unsignedInt
float                 float
double                double
std::string           string
std::vector<T>        sequence
std::vector<char>     base64Binary
std::set<T>           sequence
std::multiset<T>      sequence
Poco::Int8            byte
Poco::UInt8           unsignedByte
Poco::Int16           short
Poco::UInt16          unsignedShort
Poco::Int32           int
Poco::UInt32          unsignedInt
Poco::Int64           long
Poco::UInt64          unsignedLong
Poco::DateTime        dateTime
Poco::LocalDateTime   dateTime
Poco::Timestamp       dateTime
Poco::Timespan        long
Poco::URI             string

Using The SoapLite Transport With HTTPS

The SoapLite Transport normally uses a plain, unencrypted HTTP connection between the client and the server. To make the SoapLite Transport use a secure HTTP socket connection, the following steps must be performed.

HTTPS on The Server Side

On the server side, the listener must be created using a Poco::Net::SecureServerSocket.

Poco::Net::SecureServerSocket serverSocket(10011);
Poco::Remoting::ORB::instance().registerListener(
    new PocoRemoting::SoapLite::Listener(serverSocket)
);
std::string uri = MyProject::MyClassHelper::registerObject(
    new MyProject::MyClass, 
    "MyObject", 
    10001, 
    Poco::Remoting::SoapLite::Transport::ID,
    true
);

Note the last argument to the registerObject() function, having a value of true. This tells the ORB to generate an URI that contains a scheme that indicates that a secure connection is used.

HTTPS on The Client Side

On the client side, the SoapLite transport uses the default Poco::Net::HTTPSessionFactory object to create the Poco::Net::HTTPClientSession for talking to the server. So, all that needs to be done to enable HTTPS on the client is to register the Poco::Net::HTTPSSessionInstantiator with the session factory.

Poco::Net::HTTPSSessionInstantiator::registerInstantiator();
Poco::Remoting::SoapLite::TransportFactory::registerFactory();
MyProject::IMyClass::Ptr ptrObj = MyProject::MyClassHelper::findObject(
    hostName, 
    "MyObject", 
    10001, 
    Poco::Remoting::SoapLite::Transport::ID,
    true
);

Note the last argument to the registerObject() function, having a value of true. This tells the ORB to that a secure connection is used.