POCO Remoting User Guide

Introduction

POCO Remoting is a framework for implementing distributed objects and web services in C++. It is

non intrusive: no need to extend interfaces or change already existing code so that it can run remotely
simple: take your C++ class and add one single property to it. The code generators will do the rest.
transport independent (binary and XML based transports are supported)
fast
offers SOAP and WSDL support

Requirements

Packages

The following packages (which are not part of the free POCO distribution) are required:

CodeGeneration: a CodeGeneration framework for C++
CppParser: parses C++ header files
RemoteGen: The Remote Generator
Remoting: the remoting framework itself

Code Quality

The remoting package parses only the C++ header files to detect for which classes code needs to be generated. The parser depends heavily on developers following the POCO coding guidelines:

documentation: POCO requires first the attributes followed by the class/method/variable declaration in the next line.

//@ remote
class NetConf_API ConfigurationService
/// ConfigurationService...

Enums are currently not supported.
C-style pointers are deliberately not supported. Use Poco::SharedPtr or Poco::AutoPtr from the Foundation package instead.
Code generation for templates is currently not supported.
Dynamic inheritance is not supported for parameter passing, the data gets truncated to the static type. This is due to the non-intrusive nature of de-/serializing.
The only templates supported as method parameters are std::vector, std::set, std::multiset, Poco::SharedPtr and Poco::AutoPtr.
setter/getter methods: Due to the non-intrusive nature of de-/serializing, a De-/Serializer needs to access the members of a class via its get and set methods. Thus, every data type that is used in a remoting interface must have for all of its private/protected members one get and one set method. The same must be true for all parent classes! If a data member is public, the get/set is not needed.

//@ serialize
class NetConf_API ComplexType: public SomeOtherComplexType
/// some ComplexType
{
public:
    ComplexType();
    ~ComplexType();
    void setSomeInteger(int i);
    void setAString(const std::string& aString);
    int getSomeInteger() const;
    int getAString() const;

private:
    int _someInteger;
    int _aString;
};

Note that class members

SHOULD start with a leading underscore (can be ommitted, or the underscore can be at the end of the name). The Microsoft convention (m_varName) also works.
that the method name of a getter method of a member _varName MUST be getVarName (note the upper case of the first character and the ommitting of the '_'), also the method MUST be const
that the method name of a setter method of a member _varName MUST be setVarName (note the upper case of the first character and the ommitting of the '_'), also the method MUST NOT be const

In the above example SomeOtherComplexType must also have the attribute serialize set.

In the latest version, the Code Generator also supports public data members. This elimates the need for getter/setter methods and simplifies the above code to:

//@ serialize
struct NetConf_API ComplexType: public SomeOtherComplexType
/// some ComplexType
{
    int someInteger;
    int aString;
};

Properties

Properties are defined either at class or method level. The string //@ identifies a properties section. Properties are defined as name = value pair. If the value is missing, true is assumed. For the beginning, the following properties are probably enough:

remote: generates code to access a class remotely
serialize: generates code so that we can de-/serialize an object of the given class over the network
synchronized: only allow one single caller access to a remoteobject at one point of time

See the Attribute Reference for a complete list of properties, especially if you plan to use caching, one-way remote invocation or if you require your classes to follow a given XML schema.

How To Generate

Now assume you have written your C++ class, you have set all properties, only the generation itself is missing. Generation will require you to provide a configuration file for the RemoteGen application.

Configuration

This chapter shows the minimum configuration needed for RemoteGen. We assume that POCO is installed in p:\poco.

<AppConfig>
    <RemoteGen>
        <files>
            <include>
                p:/poco/Remoting/include/*/*/RemoteObject.h,
                p:/poco/Remoting/include/*/*/Proxy.h,
                p:/poco/Remoting/include/*/*/Skeleton.h,
                << add your own list of files here >>
            </include>
            <exclude>
            </exclude>
        </files>
        <output>
            <include>p:/poco/Remoting/samples/TestProject/include/</include>
            <flatincludes>false</flatincludes>
            <src>p:/poco/Remoting/samples/TestProject/src</src>
            <schema>p:/poco/Remoting/samples/TestProject/wsdl</schema>
            <bundle>false|true</bundle>
            <namespace>Remoting::Sample</namespace>
            <libraryname>RemotingSample</libraryname>
            <namespacedeclfile>GenProject/RemotingSample.h</namespacedeclfile>
            <copyright>
            All your code are
            belong to us!
            </copyright>
            <mode>[both|client|server]</mode>
            <remoteServices>false|true</remoteServices>
        </output>
        <schema>
            <MyClass>
                <serviceLocations>http://thinkpad:9999/xmlrpc/MyClass/class1</serviceLocations>
            </MyClass>
        </schema>
        <compiler>
            <exec>...</exec>
            <options>...</options>
            <path>...</path>
        </compiler>
    </RemoteGen>
</AppConfig>

RemoteObject.h, Skeleton.h and Proxy.h must be included in every project, simply add your own files to AppConfig.RemoteGen.files.include.
The whole output block is optional. If you don't define a namespace the namespace from the input class will be used.
The library name is used to indicate that the generated classes will be part of a library. Set the prefix for dllexport/dllimport directive here, i.e. a name TestSample will write a TestSample_API right after the class name.
If you defined a library name that is different from the one of the input class, you must also define the namespacedeclfile which contains the definition of the dll macro.
The include, src and schema entries in output allow you to override the default output directories. Per default, generated header files will be in the same directory as the original header file, generated source files will either be in the same folder, or — if your project has the same directory structure as all POCO projects — they will be in the src folder of the original class. The schema/wsdl files are per default written to the folder that contains the src directory.
flatincludes defines that each generated file should be included without any prefixing path when set to true.
The RemoteGen.schema folder contains for each class for which a WSDL file should be generated, a subfolder that has the same name as the class and which contains one serviceLocations entry. This entry can contain a comma seperated list of URIs.
The copyright field allows you to add your own copyright notice text to the standard h/cpp header.
The mode field can have the value both, client or server. In both mode all files will be generated, in client mode only files relevant for the client and in server mode only files for the server.
The bundle value defines if we generate interfaces to integrate the service into POCO Open Service Platform. Per default this property is set to false. If set to true, generated interface classes will be subclasses of OSP::Service instead of RefCountedObject.
remoteServices defines if the generated interface should inherit from Poco's OSP Service class instead of RefCountedObject. This allows to use remote services in OSP. Per default this feature is disabled.

Note that expansion of environment variables is supported. Use {ENVAR} on Linux and %ENVAR% on Windows. Depending on your compiler you must set compiler specific settings.

Visual Studio

If you are using Visual Studio 2003 or newer set the compiler block to the following:

<compiler>
    <exec>cl</exec>
    <options>
    /I "C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE",
    /I "C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK\include",
    /I "p:\poco\Foundation\include",
    /I "p:\poco\Remoting\include",
    /I "p:\poco\XML\include",
    /I "p:\poco\Util\include",
    /I "p:\poco\Net\include",
    << add your own include directories here >>
    /D "WIN32",
    /D "_DEBUG",
    /D "_WINDOWS",
    /D "_MBCS",
    /C,
    /P,
    /TP
    </options>
    <path>C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;
    C:\Program Files\Microsoft Visual Studio 8\VC\BIN;
    C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;
    C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\bin</path>
</compiler>

Update the path setting and the include paths if necessary.

GCC

Configuring GCC is a bit simpler. We assume that poco is installed in /ws/poco.

<compiler>
    <exec>g++</exec>
    <options>
    -I/ws/poco/Foundation/include,
    -I/ws/poco/XML/include,
    -I/ws/poco/Net/include,
    -I/ws/poco/Remoting/include,
    -I/ws/poco/Util/include,
    << add your own include directories here >>
    -E,
    -C,
    -o%.i
    </options>
    <path></path>
</compiler>

Execution

Start RemoteGen.exe /c=MyConfig.xml

Command Line Options

RemoteGen supports the following command line arguments

/help Display help information on command line arguments
/define=name=value Define a configuration property
/config=file Load configuration data from a file
/mode=generationmode Overwrites generation mode from config: set to either client, server or both
/bundle Create bundle wrapper for POCO OSP

Generated Files

The RemoteGenerator produces for each object several files. If the remote property is set, an Interface, a RemoteObject, a Proxy, a ProxyFactory, a Skeleton and helper classes are generated. If a class has the serialize property set, a Serializer and a Deserializer class is generated.

Interface

The Interface class will have the same name as the original class but prepended with an upper-case I character, i.e. for a class MyClass, an interface IMyClass will be generated. This class has the same method signature as the original class but acts — as the name suggests — as a pure interface. The interface will be always generated independent of the mode value in the configuration.

RemoteObject

The RemoteObject class implements the Interface and acts as a wrapper around the local object. All method calls are simply delegated to the local object. Generated in server|both mode.

Proxy

The Proxy class implements the Interface and is responsible for serializing requests and deserializing responses. Generated in client|both mode.

ProxyFactory

A factory class for generating proxies of the given type. Generated in client|both mode.

Skeleton

The Skeleton class runs on the server-side and is responsible for deserializing requests and serializing responses back to the caller. Generated in server|both mode.

ClientHelper

The client helper class offers helper functions for the client to easily find objects, i.e. to create Proxy/RemoteObject objects. Generated in client|both mode.

ServerHelper

The server helper class offers helper functions for the server side. It is used to register objects at the server. Generated in server|both mode.

Serializer

Contains code to serialize the given data type. Always generated.

Deserializer

Contains code to deserialize the given data type. Always generated.

Writing an Application

Having generated all the code, the last step is to finally write a server/client application. We assume that we have generated for a class TestProject::MyClass all the code and that we use the binary transport to access it. See Remoting/samples for the full code.

Server

#include "Poco/Remoting/ORB.h"

#include "Poco/Remoting/Binary/TransportFactory.h"
#include "Poco/Remoting/Binary/Listener.h"
#include "Poco/Remoting/Binary/Transport.h"

#include "TestProject/MyClassServerHelper.h"

[...]

// initialize the transport
Poco::Remoting::Binary::TransportFactory::registerFactory();
// register a listener
Poco::Remoting::ORB::instance().registerListener(new Poco::Remoting::Binary::Listener(10003));
// register a single object
Poco::SharedPtr<TestProject::MyClass> ptrObj(new TestProject::MyClass());
TestProject::MyClassServerHelper::registerObject(
ptrObj, "class1", 10003, Poco::Remoting::Binary::Transport::ID, false);

// wait for CTRL-C or kill
waitForTerminationRequest();
// Stop the ORB
Poco::Remoting::ORB::instance().shutdown();

Client

#include "Poco/Remoting/Binary/TransportFactory.h"
#include "Poco/Remoting/Binary/Transport.h"
#include "TestProject/MyClassClientHelper.h"

[...]

// initialize the transport
Poco::Remoting::Binary::TransportFactory::registerFactory();
Poco::AutoPtr<TestProject::IMyClass> ptrObj3 =
TestProject::MyClassClientHelper::findObject(serverName, "class1", 10003, 
    Poco::Remoting::Binary::Transport::ID, false);

Note that the Helper object actually returns an IMyClass. If the client asked for a local object, it would actually receive the RemoteObject, i.e. one would communicate locally!

Supported Transports

Currently three transport implementations exist:

SOAPLite: a light-weight implementation realizing SOAP and WSDL support. The server exports a WSDL file which allows you to write client-code, e.g. a C# client, that can communicate with the server.
NetConf: a transport that implements the NetConf standard
Binary: a proprietary and very fast transport implementation. Use this transport if speed is most important to you and client and server are written by the same company. If you require that other clients can also communicate with your RemoteObject, simply register the same RemoteObject at an additional transport:

Poco::SharedPtr<TestProject::MyClass> ptrObj(new TestProject::MyClass());
TestProject::MyClassHelper::registerObject(
ptrObj, "class1", 10003, Poco::Remoting::Binary::Transport::ID, false);
TestProject::MyClassHelper::registerObject(
ptrObj, "class1", 10005, Poco::Remoting::SoapLite::Transport::ID, false);