Installing and Configuring the .NET Client
This section includes the basic steps for setting up access to BigMemory from .NET applications.
Step 1: Verify you have the requirements
.NET 3.5 or higher.
Windows 2008 R2.
JDK 1.6 or higher.
Note: With BigMemory Max 4.1.4 and higher, JDK 1.7 is required.
An application server.
Your license key (
terracotta-license.key). Save the license key in your BigMemory home directory.
Step 2: Install the BigMemory Client
Install the BigMemory.NET Client by adding the following three .DLL files to your application:
${BIGMEMORY_HOME}/apis/csharp/bigmemory_csharp.dll ${BIGMEMORY_HOME}/apis/csharp/Nirvana DotNet.dll ${BIGMEMORY_HOME}/apis/csharp/Thrift.dll Step 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.
Step 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:
Worker threads that handle requests.
Security information. For more information, refer to the
BigMemory Max Security Guide.
Serializer factory to be used to bind the CacheSerializer to the caches (necessary if your data is in more than one language format).
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.
Note: If you will be working with .NET data only, comment out or remove the serializer line from the cross-lang-config.xml.
Step 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 shut down when you use net.sf.ehcache.CacheManager#shutdown.
Step 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 through 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).