INTRODUCTION:
=============

This is the implementation of the xmlBlaster client classes in c++.
They are helper classes for simple CORBA or SOCKET based access to xmlBlaster.

The C++ source code is compiled to a shared library

   xmlBlaster/lib/libxmlBlasterClient.so

(the extension is .so on Linux, .sl on HPUX, .dll on Windows)


Please read:

  http://www.xmlBlaster.org/xmlBlaster/doc/requirements/client.cpp.html
  
Communication protocol:

  You can choose to use the CORBA plugin or the SOCKET plugin
  or compile both simultanously to access the Java xmlBlaster server.

  http://www.xmlBlaster.org/xmlBlaster/doc/requirements/client.cpp.compile.html

  http://www.xmlBlaster.org/xmlBlaster/doc/requirements/client.cpp.socket.html

Logging:

  http://www.xmlBlaster.org/xmlBlaster/doc/requirements/client.cpp.logging.html

Xerces XML parser:

  http://www.xmlBlaster.org/xmlBlaster/doc/requirements/client.cpp.compile.html


HOW TO RUN THE TESTSUITE:
=========================

Read ${XMLBLASTER_HOME}/testsuite/src/c++/README

To manually start a test look at the file test.sh in that directory.


And now some additional implementation notes (you can skip this):
=================================================================

These C++ classes are practically a clone to the java-client & util classes (at
the time of writing this, some of the util classes in java have moved out from
xmlBlaster to jutil). Some slight differences are:

- The classes you will not find in the Java-implementation:
        StringStripper, StringStripper2, StringTrim and NameServerControl.
        These are used to simplify the use of the NameService. StringTrim
        implements methods to handle trimming of strings the same way as
        String.trim() does in java.

- Locales are not implemented (this affects the way logging looks like).

- Notes on corba compatibility

     It is well known that different corba implementors handle things in
     different ways. This starts with the names of the corba header files, the
     names of the files generated from the idl compiler, idl-compiler flags,
     and to some extend method-names (sometimes even things wich are
     well-defined by the specification).

     In writing the c++ client classes I tried to keep the implementor-
     specific stuff in a header- and a source file:

        client/protocol/corba/CompatibleCorba.h and client/protocol/corba/CompatibleCorba.cpp

     In the header file, macros, header file names etc. are specified, while
     in the source file, special non-standard functions encapsulate
     implementor-specific (but usefull) functions.

     So if you want to make xmlBlaster work with other corba implementors, you
     must first define a new name (in CompatibleCorba.h) telling which corba
     to use. At present the following names are identified:

        - XMLBLASTER_OMNIORB
        - XMLBLASTER_ORBACUS
        - XMLBLASTER_MICO
        - XMLBLASTER_TAO
        - XMLBLASTER_ORBIX

     Then you define all the header filenames  (look at the MICO or TAO
     case).

     To use this header do it in the following way:

     For each idl-file (in our case we only have one: xmlBlaster.idl) you
     have to assign to either CLIENT_HEADER or SERVER_HEADER the name of the
     prefix of the idl file (This is used to build defines for the
     idl-generated files).
     This is done because some corba implementors have one header file for the
     server and another for the client. Note that you have to include
     util/CompatibleCorba.h after each definition.

     So if you will use two different idl files in your source, lets say
     module1.idl and module2.idl, then you will call the following at the start
     of your implementation:

        #define SERVER_HEADER module1
        #include <util/CompatibleCorba.h>
        #define SERVER_HEADER module2
        #include <util/CompatibleCorba.h>

     You need to do this because CompatibleCorba will define macros for the
     implementor-names for the different headers (like nameservice, event
     service and more).

     You will call CLIENT_HEADER if the code you write will only be a pure
     client. In case you write a server, or a mixed client/server, then you
     will call SERVER_HEADER. Note that xmlBlaster is always a mixed
     client/server even if you are only writing a client (because of the
     callback).

     After having defined and included what explained, if you want to use
     a service (for example a naming service), you don't need to call
     the implementor-specific name for it, just include a macro like this:

     #include COSNAMING

     And from now on you do not bother about implementor specific stuff.
     The following names are defined for the different services:

        CORBA_HEADER (the corba header: you don't need to include this
                implicitly, because it is called already the first time you
                include util/CompatibleCorba.h)
        COSCONTAINEMENT
        COSOBJECTIDENTITY
        COSREFERENCE
        COSEVENTCHANNELADMIN
        COSEVENTCOMM
        COSRELATIONSHIPS
        COSGRAPHS
        COSTIME
        COSGRAPHEXTENTSION
        COSTRADING
        COSNAMING
        COSPROPERTY
        COSTRADINGREPOS
        COSTYPEDEVENTCHANNELADMIN
        COSTYPEDEVENT

    Note that not all these are implemented by all vendors. If a particular
    vendor does not implement a certain feature, then it links to a file called
    not_implemented.h which does not exist. This will automatically result in
    a compile error.

    See this article on a STL based CORBA mapping approach:
    http://www.cuj.com/experts/1901/vinoski.htm?topic=experts

Cheers & good Luck

Michele (laghi@swissinfo.org)
Marcel (xmlBlaster@marcelruff.info)
