Installing and Configuring the BigMemory C++ Client
This section includes the basic steps for setting up access to BigMemory from C++ applications.
1: Verify you have the requirements
Microsoft Windows Server 2008 R2 (64-bit), or Red Hat Enterprise Linux 6.4 (32-bit or 64-bit)
Microsoft Visual Studio 2012 VC110
GNU G++ Compiler
Oracle Java Development Kit 1.6 or higher (Note: With BigMemory Max 4.1.4 and higher, JDK 1.7 is required.)
An application server
Downloadand unpack the BigMemory Max kit, which includes Cross-Language Support.
Your license key (
terracotta-license.key). Save the license key in your BigMemory home directory.
2: Install the BigMemory Client
Install the BigMemory C++ Client by compiling your application with A and B below:
A. Include
${BIGMEMORY_HOME}/apis/cpp/include/bigmemoryB. Link to one of the following, depending upon whether you are using Linux or Windows:
${BIGMEMORY_HOME}/apis/cpp/linux/x86 ${BIGMEMORY_HOME}/apis/cpp/linux/x86_64 ${BIGMEMORY_HOME}/apis/cpp/windows/win32 ${BIGMEMORY_HOME}/apis/cpp/windows/x64 3: Install the Cross-Language Connector
Create the JVM that will host the BigMemory instance and the CL Connector, and add the following JAR files to the JVM's classpath.
${BIGMEMORY_HOME}/apis/ehcache/lib/ehcache-ee-<version>.jar ${BIGMEMORY_HOME}/apis/ehcache/lib/slf4j-api-<version>.jar ${BIGMEMORY_HOME}/apis/toolkit/lib/terracotta-toolkit-runtime-ee-<version>.jar ${BIGMEMORY_HOME}/server/lib/commons-codec-<version>.jar ${BIGMEMORY_HOME}/server/lib/commons-lang-<version>.jar ${BIGMEMORY_HOME}/server/lib/commons-logging-<version>.jar ${BIGMEMORY_HOME}/server/lib/httpclient-<version>.jar ${BIGMEMORY_HOME}/server/lib/httpcore-<version>.jar ${BIGMEMORY_HOME}/server/lib/libthrift-<version>.jar ${BIGMEMORY_HOME}/server/lib/nServer-<version>.jar ${BIGMEMORY_HOME}/server/lib/security-core-<version>.jar ${BIGMEMORY_HOME}/server/lib/security-keychain-<version>.jar ${BIGMEMORY_HOME}/server/lib/server-embedded-<version>.jar ${BIGMEMORY_HOME}/server/lib/server-main-<version>.jar ${BIGMEMORY_HOME}/server/lib/server-standalone-<version>.jar ${BIGMEMORY_HOME}/server/lib/slf4j-jdk14-<version>.jar ${BIGMEMORY_HOME}/server/lib/thrift-java-<version>.jar Note: In the file names above, <version> is the current version of the JAR.
4: Customize the cross-lang-config.xml file
A sample cross-lang-config.xml file is provided in the config-samples/ directory of the kit. You will need to customize it with the IP address and port where the CL Connector should bind. Below is an example:
<?xml version="1.0"?>
<xplatform
xmlns="http://www.ehcache.org/xplatform"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ehcache.org/xplatform xplatform.xsd">
<bind ip="*" port="8199" type="nirvana"/>
<!--
<workers min="10" max="100" />
<serializer factoryClass="net.sf.ehcache.xplatform.serializer.MyFactory" />
<secureinterface>
<keystore location="/path/to/keystore.jks"/>
<truststore location="/path/to/truststore.jks">
</secureinterface>
-->
</xplatform>
The optional configurations are:
The number of worker threads to handle requests.
Security information. For more about security, refer to the
BigMemory Max Security Guide.
Serializer factory to be used to bind the CacheSerializer to the caches.
MyFactory can implement the default
net.sf.ehcache.xplatform.serialization.CacheSerializerFactory. This class is responsible for creating CacheSerializers for each Cache of the CacheManager. For more information, refer to
.NET Client Serialization.
5: Customize the ehcache.xml file
A sample ehcache.xml configuration file is provided in the config-samples/ directory of the kit. If you will be using the Terracotta Server Array, you will also need to customize the tc-config.xml file. For more information about these configuration files, refer to the BigMemory Max Configuration Guide.
If you will be deploying the CL Connector as an embedded server process in an existing CacheManager, add the EmbeddedXplatformServer class to your ehcache.xml file, with the cfgFile property pointing to the cross-lang-config.xml:
<ehcache name="existingCacheManager">
<cacheManagerEventListenerFactory
class="net.sf.ehcache.xplatform.EmbeddedXplatformServer"
properties="cfgFile=path/to/cross-lang-config.xml"/>
<!-- my caches and other ehcache config -->
</ehcache>
All the caches of that "existingCacheManager" will now be accessible from all BigMemory Clients. The server's lifecycle will be tied to the CacheManager. It will start as soon as you instantiate the CacheManager using the configuration, and it will shutdown when you use net.sf.ehcache.CacheManager#shutdown.
6: Start the CL Connector
This step is for starting the CL Connector as a standalone server process. If you have deployed the CL Connector as an embedded server process, it will be started and stopped via your application.
Note: You might want to run the CL Connector as a Windows service. If so, see "Configuring the Terracotta Server to Run as a Service" in the BigMemory Max Administrator Guide.
In a terminal, change to your Terracotta server/ directory. Then run the start script with your cross-lang-config.xml and the ehcache.xml files:
%> cd /path/to/bigmemory-max-<version>/server
%> ./bin/start-cross-lang-connector.sh ../config-samples/cross-lang-config.xml
../config-samples/ehcache.xml
Note: | For Microsoft Windows installations, use the BAT scripts, and where forward slashes ("/") are given in directory paths, substitute back slashes ("\"). |
Optionally, you can include the -pid <pidFileLocation> argument to provide a file for storing the process identifier (pid) of the started server process (for example, -pid /var/tmp/pid). This pidFileLocation can later be used to stop the server.
Logging
By default, logging goes to console and to a file called bigmem-connector-%u.log, located in the directory that contains the start script. You can override this by including -Dxplatform.log=/path/to/my.log with the start script. You can also re-enable console logging by including -Dxplatform.log.console with the start script.
Stopping the server (for future reference)
Use the stop-cross-lang-connector.sh script in server/bin/ directory of your kit. You can pass as an argument either <pid> (the pid of the server to stop) or -pid <pidFileLocation> (the file containing the pid of the server to stop).
