Configuration and Usage for C++ Clients

Skip to end of metadata
Go to start of metadata

This section provides general instructions for setting up Coherence for C++, integrating Coherence*Extend, and configuring the logger.

 This section contains the following information:

General Instructions

Configuring and using Coherence for C++ requires five basic steps:

  1. Implement the C++ client application using the Coherence for C++ API.
  2. Compile and Link the application.
  3. Configure Paths.
  4. Configure Coherence*Extend on both the client and on one or more JVMs within the cluster.
  5. Configure a POF context on the client and on all of the JVMs within the cluster that are running the Coherence*Extend clustered service.
  6. Make sure the Coherence cluster is up and running.
  7. Launch the C++ client application.

The following sections describe each of these steps in detail.

Implementing the C++ Application

Coherence for C++ provides an API that allows C++ applications to access Coherence clustered services, including data, data events, and data processing from outside the Coherence cluster.

Coherence for C++ API consists of:

  • a set of C++ public header files
  • version of static libraries build by all supported C++ compilers
  • a number of samples

The library allows C++ applications to connect to a Coherence*Extend clustered service instance running within the Coherence cluster using a high performance TCP/IP-based communication layer. The 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).

Understanding the Coherence for C++ API provides an overview of the key classes in the API. For a detailed description of the classes, see the API itself which is included in the doc directory of the Coherence for C++ distribution.

Compiling and Linking the Application

The platforms on which you can compile applications that employ Coherence for C++ are listed in the Supported Platforms and Operating Systems topic.

For example, the following build.cmd file for the Windows 32-bit platform builds, compiles, and links the files for the Coherence for C++ demo. The variables in the file have the following meanings:

  • OPT and LOPT point to compiler options
  • INC points to the Coherence for C++ API files in the include directory
  • SRC points to the C++ header and code files in the common directory
  • OUT points to the file that the compiler/linker should generate when it is finished compiling the code
  • LIBPATH points to the library directory
  • LIBS points to the Coherence for C++ shared library file

After setting these environment variables, the file compiles the C++ code and header files, the API files and the OPT files, links the LOPT, the Coherence for C++ shared library, the generated object files, and the OUT files. It finishes by deleting the object files.

Configuring Paths

Set up the configuration path to the Coherence for C++ library. This involves setting an environment variable to point to the library. The name of the environment variable and the file name of the library will be different depending on your platform environment. For a list of the environment variables and library names for each platform, see the Setting Environment Variables for Compiling and Linking topic.

Configuring Coherence*Extend

To configure Coherence*Extend, add the appropriate configuration elements to both the cluster and client-side cache configuration descriptors. The cluster-side cache configuration elements instruct a Coherence DefaultCacheServer to start a Coherence*Extend clustered service that will listen for incoming TCP/IP requests from Coherence*Extend clients. The client-side cache configuration elements are used by the client library connect to the cluster. The configuration specifies the IP address and port of one or more servers in the cluster that are running the Coherence*Extend clustered service so that it can connect to the cluster. It also contains various connection-related parameters, such as connection and request timeouts.

Configuring Coherence*Extend in the Cluster

For a Coherence*Extend client to connect to a Coherence cluster, one or more DefaultCacheServer JVMs within the cluster must run a TCP/IP Coherence*Extend clustered service. To configure a DefaultCacheServer to run this service, a proxy-scheme element with a child tcp-acceptor element must be added to the cache configuration descriptor used by the DefaultCacheServer.

For example, the following cache configuration descriptor defines two clustered services, one that allows remote Coherence*Extend clients to connect to the Coherence cluster over TCP/IP and a standard Partitioned cache service. Since this descriptor is used by a DefaultCacheServer, it is important that the autostart configuration element for each service is set to true so that clustered services are automatically restarted upon termination. The proxy-scheme element has a tcp-acceptor child element which includes all TCP/IP-specific information needed to accept client connection requests over TCP/IP. The acceptor-config has also been configured to use a ConfigurablePofContext for its serializer. The C++ Extend client requires the use of POF for serialization.

See the Integrating user data types topic for more information on serialization and PIF/POF.

The Coherence*Extend clustered service configured below will listen for incoming requests on the localhost address and port 9099. When, for example, a client attempts to connect to a Coherence cache called dist-extend, the Coherence*Extend clustered service will proxy subsequent requests to the NamedCache with the same name which, in this example, will be a Partitioned cache.

Configuring Coherence*Extend on the Client

The key element within the Coherence*Extend client configuration is cache-config. This element contains the path to a cache configuration descriptor which contains the cache configuration. This cache configuration descriptor is used by the DefaultConfigurableCacheFactory.

A Coherence*Extend client uses the information within an initiator-config cache configuration descriptor element to connect to and communicate with a Coherence*Extend clustered service running within a Coherence cluster.

For example, the following cache configuration descriptor defines a caching scheme that connects to a remote Coherence cluster. The remote-cache-scheme element has a tcp-initiator child element which includes all TCP/IP-specific information needed to connect the client with the Coherence*Extend clustered service running within the remote Coherence cluster.

When the client application retrieves a named cache via the CacheFactory using, for example, the name dist-extend, the Coherence*Extend client will connect to the Coherence cluster via TCP/IP (using the address localhost and port 9099) and return a NamedCache implementation that routes requests to the NamedCache with the same name running within the remote cluster. Note that the remote-addresses configuration element can contain multiple socket-address child elements. The Coherence*Extend client will attempt to connect to the addresses in a random order, until either the list is exhausted or a TCP/IP connection is established.

Connection Error Detection and Failover

When a Coherence*Extend client service detects that the connection between the client and cluster has been severed (for example, due to a network, software, or hardware failure), the Coherence*Extend client service implementation (that is, CacheService or InvocationService) will raise a MemberEventType.Left event (by using the MemberEventHandler delegate) and the service will be stopped. If the client application attempts to subsequently use the service, the service will automatically restart itself and attempt to reconnect to the cluster. If the connection is successful, the service will raise a MemberEventType.Joined event; otherwise, a fatal exception will be thrown to the client application.

A Coherence*Extend service has several mechanisms for detecting dropped connections. Some mechanisms are inherit to the underlying protocol (such as TCP/IP in Extend-TCP), whereas others are implemented by the service itself. The latter mechanisms are configured by using the outgoing-message-handler configuration element.

The primary configurable mechanism used by a Coherence*Extend client service to detect dropped connections is a request timeout. When the service sends a request to the remote cluster and does not receive a response within the request timeout interval (see <request-timeout>), the service assumes that the connection has been dropped. The Coherence*Extend client and clustered services can also be configured to send a periodic heartbeat over the connection (see <heartbeat-interval> and <heartbeat-timeout>). If the service does not receive a response within the configured heartbeat timeout interval, the service assumes that the connection has been dropped.

Configuring and Using the Coherence for C++ Client Library

To use the Coherence for C++ library in your C++ applications, you must link Coherence for C++ library with your application and provide a Coherence for C++ cache configuration and its location. 

The location of the cache configuration file can be set by an environment variable specified in the sample application section or programmatically.

Setting the Configuration File Location with an Environment Variable

As described in Coherence Configuration, the tangosol.coherence.cacheconfig system property can be used to specify the location of the cache configuration file.  To set the configuration location on Windows execute:

c:\coherence_cpp\examples> set tangosol.coherence.cacheconfig=config\extend-cache-config.xml

Setting the Configuration File Location Programmatically

You can set the location programmatically by using either DefaultConfigurableCacheFactory::create or CacheFactory::configure (using the CacheFactory::loadXmlFile helper method, if needed).

The create method of the DefaultConfigurableCacheFactory class creates a new Coherence cache factory. The vsFile parameter specifies the name and location of the Coherence configuration file to load.

The configure method configures the CacheFactory and local member. The vXmlCache parameter specifies an XML element corresponding to a cache-config.dtd and vXmlCoherence specifies an XML element corresponding to coherence.dtd.

The loadXmlFile method reads an XmlElement from the named file. This method does not configure the CacheFactory, but it can be used to obtain a configuration which can be supplied to the configure method. The parameter vsFile specifies the name of the file to read from.


The following sample C++ code sets the CacheFactory::configure method to set the location of the cache configuration files for the server/cluster (coherence-extend-config.xml) and for the C++ client (tangosol-operation-config.xml).

Operational Configuration File (tangosol-coherence-override.xml)

The operational configuration override file (typically called tangosol-coherence-override.xml), controls the operational and runtime settings used by Oracle Coherence to create, configure and maintain its clustering, communication, and data management services. As with the Java client use of this file is optional for the C++ client.

In the case of a C++ client, the file can be used to specify or override general operations settings for a Coherence application that are not specifically related to caching. For a C++ client, the key elements are for logging, the Coherence product edition, and the location and role assignment of particular cluster members.

The operational configuration can be configured either programmatically or in the tangosol-coherence-override.xml file. To configure the operational configuration programmatically, specify an XML file that follows the coherence.dtd and contains at lest one of the following elements in the vXmlCoherence parameter of the CacheFactory::configure method (coherence::net::CacheFactory::configure (View vXmlCache, View vXmlCoherence)).

  • license-config - The license-config element contains sub-elements that allow you to configure the edition and operational mode for Coherence. The edition-name sub-element specifies the product edition (such as Grid Edition, Enterprise Edition, Real Time Client, and so on) that the member will utilize. This allows multiple product editions to be used within the same cluster, with each member specifying the edition that it will be using. Only the RTC (real time client) and DC (data client) values are recognized for the Coherence for C++ client. license-config is an optional sub-element of the coherence element, and defaults to RTC.
  • logging-config - The logging-config element contains sub-elements that allow you to configure how messages will be logged for your system. This element allows you to specify destination of the log messages, the severity level for logged messages, and the log message format. logging-config is a required sub-element of the coherence element. For more information on logging, see Configuring a Logger
  • member-identity - The member-identity element specifies detailed identity information that is useful for defining the location and role of the cluster member. You can use this element to specify the name of the cluster, rack, site, machine, role, and so on, to which the member belongs. member-identity is an optional sub-element of the cluster-config element.
    The following XML code illustrates the contents of a sample tangosol-coherence.xml file.

Operational Configuration Elements provides more detailed information on the operational configuration file and the elements that it can define.

Configuring a Logger

The Logger is configured using the logging-config element of the operational configuration file. The element provides the following attributes that can record detailed information about logged errors.

  • destination - determines the type of LogOutput used by the Logger. Valid values are:
    • "stderr" for Console.Error
    • "stdout" for Console.Out
    • file path if messages should be directed to a file
  • severity-level - determines the log level that a message must meet or exceed in order to be logged.
  • message-format - determines the log message format.
  • character-limit - determines the the maximum number of characters that the logger daemon will process from the message queue before discarding all remaining messages in the queue.
    The following sample code illustrates an operational configuration that contains a logging configuration. For more information on operational configuration, see Operational Configuration File.

Launching a Coherence DefaultCacheServer Proxy

To start a DefaultCacheServer that uses the cluster-side Coherence cache configuration described earlier to allow Coherence for C++ clients to connect to the Coherence cluster via TCP/IP, you need to do the following:

  1. Change the current directory to the Oracle Coherence library directory (%COHERENCE_HOME%\lib on Windows and $COHERENCE_HOME/lib on Unix).
  2. Make sure that the paths are configured so that the Java command will run.
  3. Start the DefaultCacheServer using the command line below:
    java -cp coherence.jar -Dtangosol.coherence.cacheconfig=file://<path to the server-side cache configuration descriptor>
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.