This site hosts historical documentation. Visit www.terracotta.org for recent product information.
This section includes the basic steps for setting up access to BigMemory from .NET applications.
terracotta-license.key
). Save the license key in your BigMemory home directory. 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
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.
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:
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
.
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
.
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.
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.
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).
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.
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));
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());
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);
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.