Call us: +1-415-738-4000

BigMemory .NET Client Setup

Get Started

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.
  • The BigMemory kit. Download and 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.

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}/common/lib/bigmemory-<version>.jar
  • ${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 about security, refer to Securing Terracotta Clusters.
  • 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 the Serialization page.

    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 Configuring BigMemory Max.

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.

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 Starting up TSA or CLC as Windows Service using the Service Wrapper.

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).

Access your data

This section provides basic code snippets for accessing BigMemory data from your application. For more explanation, refer to the Cross-Language API page. For the complete class library documentation, refer to the API documentation in the /apis/csharp/apidoc-csharp.zip directory in the kit.

Create a CacheManager

This snippet creates a CacheManager configuration that uses the Nirvana Shared Memory (SHM) transport and provisions a pool of 10 connections.

XPlatform.CreateCacheManager(new Terracotta.Ehcache.Config.Configuration("/dev/shm", 10));
Retrieve a Cache from the CacheManager

This snippet can be used with the demo code samples in the kit. Notice that a serializer must be specified.

cacheManager.GetCache("TestCache", new RecipeSerializer());
Get or put entries into the cache

This snippet can be used with the demo code samples in the kit. Notice that you have the option to specify a consistency type for get and put operations.

cache.Put(recipe.name, recipe, ConsistencyType.STRONG);
Close the CacheManager
cacheManager.Close();

Searches of BigMemory data can be made using the BigMemory Structured Query Language (SQL). Refer to the Search section on the API page.