This section provides general instructions for setting up Coherence for C++, integrating Coherence*Extend, and configuring the logger.
Configuring and using Coherence for C++ requires five basic steps:
Implement the C++ Application using the Coherence for C++ API. See Chapter 5, "Understanding the Coherence for C++ API." for more information on the API.
Compile and Link the application.
Configure Coherence*Extend on both the client and on one or more JVMs within the cluster.
Configure a POF context on the client and on all of the JVMs within the cluster that run the Coherence*Extend clustered service.
Make sure the Coherence cluster is up and running.
Launch the C++ client application.
The following sections describe each of these steps in detail.
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
several 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).
Chapter 5, "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.
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. A sample run of the build.cmd file is illustrated in Example 4-1.
Example 4-1 Sample Run of the build.cmd File
@echo off setlocal set EXAMPLE=%1% if "%EXAMPLE%"=="" ( echo You must supply the name of an example to build. goto exit ) set OPT=/c /nologo /EHsc /Zi /RTC1 /MD /GR /DWIN32 set LOPT=/NOLOGO /SUBSYSTEM:CONSOLE /INCREMENTAL:NO set INC=/I%EXAMPLE% /Icommon /I..\include set SRC=%EXAMPLE%\*.cpp common\*.cpp set OUT=%EXAMPLE%\%EXAMPLE%.exe set LIBPATH=..\lib set LIBS=%LIBPATH%\coherence.lib echo building %OUT% ... cl %OPT% %INC% %SRC% link %LOPT% %LIBS% *.obj /OUT:%OUT% del *.obj echo To run this example execute 'run %EXAMPLE%' :exit
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 "Setting Environment Variables for Compiling and Linking".
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 run 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.
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 cache configuration descriptor in Example 4-2 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 Chapter 3, "Building Integration Objects for C++ Clients" 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.
Example 4-2 Cache Configuration for Two Clustered Services
<?xml version="1.0"?>
<!DOCTYPE cache-config SYSTEM "cache-config.dtd">
<cache-config>
<caching-scheme-mapping>
<cache-mapping>
<cache-name>dist-*</cache-name>
<scheme-name>dist-default</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<distributed-scheme>
<scheme-name>dist-default</scheme-name>
<lease-granularity>member</lease-granularity>
<backing-map-scheme>
<local-scheme/>
</backing-map-scheme>
<autostart>true</autostart>
</distributed-scheme>
<proxy-scheme>
<service-name>ExtendTcpProxyService</service-name>
<thread-count>5</thread-count>
<acceptor-config>
<tcp-acceptor>
<local-address>
<address>localhost</address>
<port>9099</port>
</local-address>
</tcp-acceptor>
<serializer>
<class-name>com.tangosol.io.pof.ConfigurablePofContext</class-name>
</serializer>
</acceptor-config>
<autostart>true</autostart>
</proxy-scheme>
</caching-schemes>
</cache-config>
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 cache configuration descriptor in Example 4-3 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 with CacheFactory using, for example, the name dist-extend, the Coherence*Extend client will connect to the Coherence cluster by using 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.
Example 4-3 A Caching Scheme that Connects to a Remote Coherence Cluster
<?xml version="1.0"?>
<!DOCTYPE cache-config SYSTEM "cache-config.dtd">
<cache-config>
<caching-scheme-mapping>
<cache-mapping>
<cache-name>local-*</cache-name>
<scheme-name>local-example</scheme-name>
</cache-mapping>
<cache-mapping>
<cache-name>dist-extend</cache-name>
<scheme-name>extend-dist</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<local-scheme>
<scheme-name>local-example</scheme-name>
</local-scheme>
<remote-cache-scheme>
<scheme-name>extend-dist</scheme-name>
<service-name>ExtendTcpCacheService</service-name>
<initiator-config>
<tcp-initiator>
<remote-addresses>
<socket-address>
<address system-property="tangosol.coherence.proxy.address">localhost</address>
<port system-property="tangosol.coherence.proxy.port">9099</port>
</socket-address>
</remote-addresses>
<connect-timeout>10s</connect-timeout>
</tcp-initiator>
<outgoing-message-handler>
<request-timeout>5s</request-timeout>
</outgoing-message-handler>
</initiator-config>
</remote-cache-scheme>
</caching-schemes>
</cache-config>
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.
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.
As described in "Runtime Library and Search Path", 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
You can set the location programmatically by using either DefaultConfigurableCacheFactory::create or CacheFactory::configure (using the CacheFactory::loadXmlFile helper method, if needed).
Example 4-4 Setting the Configuration File Location
static Handle coherence::net::DefaultConfigurableCacheFactory::create (String::View vsFile = String::NULL_STRING)
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.
Example 4-5 Creating a Coherence Cache Factory
static void coherence::net::CacheFactory::configure (XmlElement::View vXmlCache, XmlElement::View vXmlCoherence = NULL)
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.
Example 4-6 Configuring a CacheFactory and a Local Member
static XmlElement::Handle coherence::net::CacheFactory::loadXmlFile (String::View vsFile)
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 C++ code in Example 4-7 uses 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).
The operational configuration override file (called tangosol-coherence-override.xml by default), 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 least 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 subelements that allow you to configure the edition and operational mode for Coherence. The edition-name subelement specifies the product edition (such as Grid Edition, Enterprise Edition, Real Time Client, and so on) that the member will use. 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. The license-config is an optional subelement of the coherence element, and defaults to RTC.
logging-config— The logging-config element contains subelements that allow you to configure how messages will be logged for your system. This element enables you to specify destination of the log messages, the severity level for logged messages, and the log message format. The logging-config is a required subelement 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. The member-identity is an optional subelement of the cluster-config element. Example 4-8 illustrates the contents of a sample tangosol-coherence.xml file.
Example 4-8 Sample Operational Configuration
<?xml version='1.0'?>
<coherence>
<cluster-config>
<member-identity>
<site-name>extend site</site-name>
<rack-name>rack 1</rack-name>
<machine-name>machine 1</machine-name>
</member-identity>
</cluster-config>
<logging-config>
<destination>stderr</destination>
<severity-level>5</severity-level>
<message-format>(thread={thread}): {text}</message-format>
<character-limit>8192</character-limit>
</logging-config>
<license-config>
<edition-name>RTC</edition-name>
<license-mode>production</license-mode>
</license-config>
</coherence>
Operational Configuration Elements provides more detailed information on the operational configuration file and the elements that it can define.
The Logger is configured using the logging-config element in 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 to be logged.
message-format—determines the log message format.
character-limit—determines the maximum number of characters that the logger daemon will process from the message queue before discarding all remaining messages in the queue. Example 4-9 illustrates an operational configuration that contains a logging configuration. For more information on operational configuration, see "Operational Configuration File (tangosol-coherence-override.xml)".
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 by using TCP/IP, you need to do the following:
Change the current directory to the Oracle Coherence library directory (%COHERENCE_HOME%\lib on Windows and $COHERENCE_HOME/lib on UNIX).
Make sure that the paths are configured so that the Java command will run.
Start the DefaultCacheServer using the command line below: