---

Oracle Coherence for C++ Community Edition

Contents

1. Introduction to Coherence
2. How to Get Coherence Community Edition
3. Introduction to Coherence for C++
4. Building
5. CLI Hello Coherence Example
6. Programmatic Hello Coherence Example
7. Testing
8. Documentation
9. Contributing

Introduction to Coherence

Coherence is a scalable, fault-tolerant, cloud-ready, distributed platform for building grid-based applications and reliably storing data. The product is used at scale, for both compute and raw storage, in a vast array of industries such as critical financial trading systems, high performance telecommunication products and eCommerce applications.

Typically these deployments do not tolerate any downtime and Coherence is chosen due to its novel features in death detection, application data evolvability, and the robust, battle-hardened core of the product that enables it to be seamlessly deployed and adapted within any ecosystem.

At a high level, Coherence provides an implementation of the familiar Map interface but rather than storing the associated data in the local process it is partitioned (or sharded) across a number of designated remote nodes. This partitioning enables applications to not only distribute (and therefore scale) their storage across multiple processes, machines, racks, and data centers but also to perform grid-based processing to truly harness the CPU resources of the machines.

The Coherence interface NamedCache (an extension of Map) provides methods to query, aggregate (map/reduce style) and compute (send functions to storage nodes for locally executed mutations) the data set. These capabilities, in addition to numerous other features, enable Coherence to be used as a framework for writing robust, distributed applications.

How to Get Coherence Community Edition

For more details on how to obtain and use Coherence, please see the Coherence CE README.

Introduction to Coherence for C++

Coherence for C++ allows C++ applications to access Coherence clustered services, including data, data events, and data processing from outside the Coherence cluster. Typical uses of Coherence for C++ include desktop and web applications that require access to Coherence caches.

Coherence for C++ consists of a native C++ library that connects to a Coherence*Extend clustered service instance running within the Coherence cluster using a high performance TCP/IP-based communication layer. This library sends all client requests to the Coherence*Extend clustered service which, in turn, responds to client requests by delegating to an actual Coherence clustered service (for example, a partitioned or replicated cache service).

A NamedCache instance is retrieved by using the CacheFactory::getCache(...) API call. After it is obtained, a client accesses the NamedCache in the same way as it would if it were part of the Coherence cluster. The fact that NamedCache operations are being sent to a remote cluster node (over TCP/IP) is completely transparent to the client application.

NOTE: The C++ client follows the interface and concepts of the Java client, and users familiar with Coherence for Java should find migrating to Coherence for C++ straightforward.

See Developing Remote Clients for Oracle Coherence for further details.

Building

Prerequisites

1. A supported hardware platform and C++ compiler. See Supported Environments for Coherence C++ Client.
2. Oracle Java 8 JDK
3. Apache Ant version 1.7.0 or later
4. Ant-Contrib version 1.0b3
5. Ant-Contrib cpptasks version 1.0b4

Building the shared library

The Coherence for C++ build system is based on Ant. To build Coherence for C++:

1. Clone this repository
2. Download Apache Ant version 1.7.0 or later and install it at tools/internal/common/ant
3. Download ant-contrib-1.0b3.jar and install it at tools/internal/common/ant-contrib/lib
4. Download cpptasks-1.0b4.jar and install it at tools/internal/common/ant-contrib/lib
5. Set the JAVA_HOME environment variable to point to the Oracle JDK 8 home
6. cd bin
7. On unix flavor platforms source cfglocal.sh from a bash shell (e.g. . cfglocal.sh). On windows open a Visual Studio native tools command prompt and run cfgwindows.cmd
8. cd ../prj/coherence
9. ant -Dbuild.type=release clean build dist - can take from 20 minutes to over an hour depending on platform type and CPU speed

The resulting files:

• dist/14.1.2.0.0b0/include - the public header files
• dist/14.1.2.0.0b0/lib - the Coherence for C++ shared library

CLI Hello Coherence Example

The following example illustrates starting a storage enabled Coherence Server, followed by a Coherence for C++ console application. Using the console, data is inserted and retrieved. The console is then terminated and restarted and data is once again retrieved to illustrate the permanence of the data.

Prerequisites

1. The Coherence for C++ shared library see Building
2. Coherence Community Edition coherence.jar

Build Sanka

Sanka is a command line tool which can be used to run the main method on Coherence C++ classes

1. Set the JAVA_HOME environment variable to point to the Oracle JDK 8 home
2. cd bin
3. On unix flavor platforms source cfglocal.sh from a bash shell (e.g. . cfglocal.sh). On windows open a Visual Studio native tools command prompt and run cfgwindows.cmd
4. cd ../prj/sanka
5. ant -Dbuild.type=release build dist

Start a Coherence server

Unix shell:

$JAVA_HOME/bin/java -Dcoherence.pof.enabled=true -Dcoherence.log.level=6 -jar coherence.jar

Windows command prompt:

"%JAVA_HOME%/bin/java" -Dcoherence.pof.enabled=true -Dcoherence.log.level=6 -jar coherence.jar

Run the coherence::net::CacheFactory::main() (console) using sanka

Unix shell:

cd dist/14.1.2.0.0b0/bin
./sanka -l ../lib/libcoherence.so coherence::net::CacheFactory

Windows command prompt:

.\sanka -l ..\lib\coherence.dll coherence::net::CacheFactory

Console:

Map (?): cache welcomes

Map (welcomes): get english
NULL

Map (welcomes): put english Hello
NULL

Map (welcomes): put spanish Hola
NULL

Map (welcomes): put french Bonjour
NULL

Map (welcomes): get english
Hello

Map (welcomes): list
french = Bonjour
english = Hello
spanish = Hola

Map (welcomes): bye

Start the console again

Unix shell:

./sanka -l ../lib/libcoherence.so coherence::net::CacheFactory

Windows command prompt:

.\sanka -l ..\lib\coherence.dll coherence::net::CacheFactory

Console:

Map (?): cache welcomes

Map (welcomes): list
french = Bonjour
english = Hello
spanish = Hola

Programmatic Hello Coherence Example

The following example illustrates starting a storage enabled Coherence server, followed by running the HelloCoherence application. The HelloCoherence application inserts and retrieves data from the Coherence server.

Prerequisites

1. The Coherence for C++ shared library see Building
2. Coherence Community Edition coherence.jar

Build HelloCoherence

Copy and paste the following source to a file named HelloCoherence.cpp:

#include "coherence/lang.ns"

#include "coherence/net/CacheFactory.hpp"
#include "coherence/net/NamedCache.hpp"
#include "coherence/util/Iterator.hpp"

#include <iostream>

using namespace coherence::lang;

using coherence::net::CacheFactory;
using coherence::net::NamedCache;
using coherence::util::Iterator;

int main()
    {
    try
        {
        // access/create the "welcomes" cache in the Coherence cluster
        NamedCache::Handle hCache = CacheFactory::getCache("welcomes");
        std::cout << "Accessing cache \"" << hCache->getCacheName()
                  << "\" containing " << hCache->size() << " entries"
                  << std::endl;

        hCache->put(String::create("english"), String::create("Hello"));
        hCache->put(String::create("spanish"), String::create("Hola"));
        hCache->put(String::create("french"), String::create("Bonjour"));

        // list
        for (Iterator::Handle hIterator = hCache->entrySet()->iterator();
             hIterator->hasNext(); )
            {
            std::cout << hIterator->next() << std::endl;
            }

        // disconnect from the Coherence cluster
        CacheFactory::shutdown();
        }
    catch (const std::exception& e)
        {
        std::cerr << "error: " << e.what() << std::endl;
        return 1;
        }
    return 0;
    }

Compile HelloCoherence.cpp using the Coherence for C++ header files and shared library:

Using GCC on Linux and macOS:

g++ -Idist/14.1.2.0.0b0/include -lcoherence -L dist/14.1.2.0.0b0/lib -o HelloCoherence HelloCoherence.cpp

From a Visual Studio native tools command prompt on Windows:

cl -Idist\14.1.2.0.0b0\include dist\14.1.2.0.0b0\lib\coherence.lib -o HelloCoherence HelloCoherence.cpp

Start a Coherence server

Unix shell:

$JAVA_HOME/bin/java -Dcoherence.pof.enabled=true -Dcoherence.log.level=6 -jar coherence.jar

Windows command prompt:

"%JAVA_HOME%/bin/java" -coherence.pof.enabled=true -Dcoherence.log.level=6 -jar coherence.jar

Run HelloCoherence

Unix shell:

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:dist/14.1.2.0.0b0/lib
./HelloCoherence

Windows command prompt:

set PATH=%DEV_ROOT%\dist\14.1.2.0.0b0\lib;%PATH%
HelloCoherence

Testing

Coherence for C++ has unit and functional tests to validate builds and code changes.

Prerequisites

1. The Coherence for C++ shared library see Building
2. Perl
3. Download CxxTest version 3.10.1 and install it at tools/internal/common/cxxtest
4. Comment out the -Werror flag in prj/build-import.xml (e.g. <!-- compilerarg if="cc.g++" value="-Werror"/ -->) as CxxTest source files will produce warnings when compiling with GCC

Building and running the tests

1. Set the JAVA_HOME environment variable to point to the Oracle JDK 8 home
2. cd bin
3. On unix flavor platforms source cfglocal.sh from a bash shell (e.g. . cfglocal.sh). On windows open a Visual Studio native tools command prompt and run cfgwindows.cmd

cd ../prj/tests/unit (or cd ../prj/tests/functional)
ant -Dbuild.type=release build test