This chapter includes the following sections:
Configuring and using Coherence for C++ requires the following steps:
Building Integration Objects (C++) (See also Developing Applications with Oracle Coherence)
Launch the client 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
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).
Using the Coherence for C++ Client 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.
@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
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.
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 are different depending on your platform environment. For a list of the environment variables and library names for each platform, see Introduction to Coherence C++ Clients.
A reference to a configured cache can be obtained by name by using the coherence::net::CacheFactory class as follows:
NamedCache::Handle hCache = CacheFactory::getCache("cache_name");
Instances of all NamedCache implementations should be explicitly released by calling the NamedCache::release() method when they are no longer needed, to free up any resources they might hold.
If the particular NamedCache is used for the duration of the application, then the resources are cleaned up when the application is shut down or otherwise stops. However, if it is only used for a period, the application should call its release() method when finished using it.
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 "Setting the run-time Library and Search Path", the coherence.cacheconfig system property specifies the location of the cache configuration file. To set the configuration location on Windows execute:
c:\coherence_cpp\examples> set 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).
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. For example:
static Handle coherence::net::DefaultConfigurableCacheFactory::create (String::View vsFile = String::NULL_STRING)
The configure method configures the CacheFactory and local member. The vXmlCache parameter specifies an XML element corresponding to a coherence-cache-config.xsd and vXmlCoherence specifies an XML element corresponding to coherence-operational-config.xsd. For example:
static void coherence::net::CacheFactory::configure (XmlElement::View vXmlCache, XmlElement::View vXmlCoherence = NULL)
The loadXmlFile method reads an XmlElement from the named file. This method does not configure the CacheFactory, but obtains a configuration which can be supplied to the configure method. The parameter vsFile specifies the name of the file to read from. For example:
static XmlElement::Handle coherence::net::CacheFactory::loadXmlFile (String::View vsFile)
The CacheFactory::configure method is used 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). For example:
... // Configure the cache CacheFactory::configure(CacheFactory::loadXmlFile(String::create( "C:\coherence-extend-config.xml")), CacheFactory::loadXmlFile(String::create( "C:\tangosol-operation-config.xml"))); ...
The operational configuration override file (called tangosol-coherence-override.xml by default), controls the operational and run-time 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. For details about the operational configuration override file, see Developing Applications with Oracle Coherence.
For a C++ client, the file specifies or overrides 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-operational-config.xsd schema and contains an element 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 uses. This allows multiple product editions to be used within the same cluster, with each member specifying the edition that it uses. 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 are 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, computer name, role, and so on, to which the member belongs. The member-identity is an optional subelement of the cluster-config element.
The following example illustrates a sample tangosol-coherence.xml file.
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/
coherence-operational-config coherence-operational-config.xsd">
<cluster-config>
<member-identity>
<site-name>extend site</site-name>
<rack-name>rack 1</rack-name>
<machine-name>computer 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>prod</license-mode>
</license-config>
</coherence>
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 processes from the message queue before discarding all remaining messages in the queue.
The following example illustrates an operational configuration that contains a logging configuration. For more information on operational configuration, see "Operational Configuration File (tangosol-coherence-override.xml)".
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/
coherence-operational-config coherence-operational-config.xsd">
<logging-config>
<destination>stderr</destination>
<severity-level>5</severity-level>
<message-format>(thread={thread}): {text}</message-format>
<character-limit>8192</character-limit>
</logging-config>
</coherence>