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>