8 Configuration and Usage for C++ Clients
This chapter includes the following sections:
- General Instructions
You can follow a basic set of steps for creating and using Coherence C++ clients. - Implement 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. - Compile and Link the Application
Review a sample Windows build file that demonstrates how to compiles a C++ application. - Configure Paths
Set up the configuration path to the Coherence for C++ library. This involves setting an environment variable to point to the library. - Obtaining a Cache Reference with C++
You can obtained a reference to a configured cache by name using thecoherence::net::CacheFactory
class. - Cleaning up Resources Associated with a Cache
NamedCache
implementations should be explicitly released by calling theNamedCache::release()
method when they are no longer needed. - Configuring and Using the Coherence for C++ Client Library
To use the Coherence for C++ library in your applications, link the library to your application and provide a cache configuration file. - Operational Configuration File (tangosol-coherence-override.xml)
The operational configuration override file (calledtangosol-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. - Configuring a Logger
The Coherence logger is configured using thelogging-config
element in the operational configuration file.
Parent topic: Creating C++ Extend Clients
General Instructions
The general steps include:
Parent topic: Configuration and Usage for C++ Clients
Implement the C++ Application
The 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).
Parent topic: Configuration and Usage for C++ Clients
Compile and Link the Application
For the list of platforms on which you can compile applications that employ Coherence for C++, see Supported Environments for Coherence C++ Client in the Installing Oracle Coherence.
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
andLOPT
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.
Parent topic: Configuration and Usage for C++ Clients
Configure Paths
Parent topic: Configuration and Usage for C++ Clients
Obtaining a Cache Reference with C++
coherence::net::CacheFactory
class.For example:
NamedCache::Handle hCache = CacheFactory::getCache("cache_name");
Parent topic: Configuration and Usage for C++ Clients
Cleaning up Resources Associated with a Cache
NamedCache
implementations should be explicitly released by calling the NamedCache::release()
method when they are no longer needed.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.
Parent topic: Configuration and Usage for C++ Clients
Configuring and Using the Coherence for C++ Client Library
This section includes the following topics:
- Setting the Configuration File Location with an Environment Variable
- Setting the Configuration File Location Programmatically
Parent topic: Configuration and Usage for C++ Clients
Setting the Configuration File Location with an Environment Variable
The coherence.cacheconfig
system property specifies the location of the cache configuration file. See Setting the run-time Library and Search Path.
To set the configuration location on Windows execute:
c:\coherence_cpp\examples> set 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. 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"))); ...
Operational Configuration File (tangosol-coherence-override.xml)
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. See Using the Default Operational Override File in 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
—Thelicense-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. Thelicense-config
is an optional subelement of thecoherence
element, and defaults to RTC. -
logging-config
— Thelogging-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. Thelogging-config
is a required subelement of thecoherence
element. -
member-identity
—Themember-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. Themember-identity
is an optional subelement of thecluster-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>
Parent topic: Configuration and Usage for C++ Clients
Configuring a Logger
logging-config
element in the operational configuration file. See Operational Configuration File (tangosol-coherence-override.xml). The element provides the following attributes that can record detailed information about logged errors.
-
destination
—determines the type ofLogOutput
used by the Logger. Valid values are:-
stderr
forConsole.Error
-
stdout
forConsole.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:
<?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>
Parent topic: Configuration and Usage for C++ Clients