17 Introduction to Coherence .NET Clients

Learn about Coherence for .NET and how to set up Coherence .NET applications.

This chapter includes the following sections:

Parent topic: Creating .NET Extend Clients

17.1 Overview of Coherence for .NET

Coherence for .NET allows .NET applications to access Coherence clustered services, including data, data events, and data processing from outside the Coherence cluster. Typical uses of Coherence for .NET include desktop and web applications that require access to Coherence caches. See Installing the .NET Client Distribution in Installing Oracle Coherence.

Coherence for .NET consists of a lightweight .NET library that connects to a Coherence*Extend clustered service instance running within the Coherence cluster using a high performance TCP/IP-based communication layer. This 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).

An INamedCache instance is retrieved by using the CacheFactory.GetCache(...) API call. After it is obtained, a client accesses the INamedCache in the same way as it would if it were part of the Coherence cluster. The fact that INamedCache operations are being sent to a remote cluster node (over TCP/IP) is completely transparent to the client application.

17.2 Configuration and Usage for .NET Clients

Learn the main steps that are required to use Coherence .NET clients.

This section includes instructions for setting up .NET applications to use Coherence. This section includes the following topics:

17.2.1 General Instructions

You can follow a basic set of steps for creating and using Coherence .NET clients. The general steps include:

  1. Configuring Coherence*Extend for .NET

  2. Building Integration Objects (.NET)

  3. Using the Coherence .NET APIs

  4. Starting a Proxy Server

  5. Launching the .NET client application

17.2.2 Configuring Coherence*Extend for .NET

Coherence for .NET clients use a specific XML schema for the Coherence cache configuration file. Make sure the cache configuration file uses the following schema:

<cache-config xmlns="http://schemas.tangosol.com/cache"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://schemas.tangosol.com/cache
  assembly://Coherence/Tangosol.Config/cache-config.xsd">
  ...

For general instructions on setting up and configuring Coherence*Extend, refer to:

17.2.3 Obtaining a Cache Reference with .NET

A reference to a configured cache can be obtained by name by using the CacheFactory class:

INamedCache cache = CacheFactory.GetCache("example-local-cache");

17.2.4 Cleaning Up Resources Associated with a Cache

INamedCache instances, including LocalCache, should be explicitly released by calling the INamedCache.Release method when they are no longer needed. If the particular INamedCache 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 the instance is only used for a period of time, then the application should call its Release method when finished using it.

Alternatively, you can leverage the fact that INamedCache extends IDisposable and that all cache implementations delegate a call to IDisposable.Dispose to INamedCache.Release. If you want to obtain and release a cache instance within a single method, you can do so with a using block:

using (INamedCache cache = CacheFactory.GetCache("my-cache"))
{
   // use cache as usual
}

After the using block terminates, IDisposable.Dispose is called on the INamedCache instance, and all resources associated with it are released.

17.2.5 Using Network Filters

A network filter is a mechanism that allows transformation of data sent through TCP/IP sockets to be performed in a pluggable, layered fashion. Coherence for .NET supports custom filters, thus enabling users to modify the contents of the network traffic and is commonly used to add compression and encryption to data.

This section includes the following topics:

17.2.5.1 Custom Filters

To create a filter, create a .NET class that implements the Tangosol.IO.IWrapperStreamFactory interface and optionally implements the Tangosol.Util.IXmlConfigurable interface. The IWrapperStreamFactory interface defines two methods:

Stream GetInputStream(Stream stream);
Stream GetOutputStream(Stream stream);

that provide the I/O stream to be wrapped ("filtered") (on input—received message, or output—sending message) and expects a stream back that wraps the original stream. This method is called for each incoming and outgoing message.

17.2.5.2 Configuring Filters

There are two steps to configuring a filter. The first step is to declare the filter in the <filters> XML element in an operational override file. See filter in Developing Applications with Oracle Coherence.

...
<cluster-config>
   <filters>
      <filter>
         <filter-name>gzip</filter-name>
         <filter-class>Tangosol.Net.CompressionFilter, Coherence</filter-class>
      </filter>
   </filters>
</cluster-config>
...

Note:

GZip compression filter is supported in .NET framework version 2.0 or higher.

The second step is to attach the filter to one or more specific services. To specify the filter for a specific service, for example the ExtendTcpCacheService service, add a <filter-name> element to the <use-filters> element of the service declaration in the cache configuration file.

...
<remote-cache-scheme>
   <scheme-name>extend-direct</scheme-name>
   <service-name>ExtendTcpCacheService</service-name>
   <initiator-config>
      ...
      <use-filters>
         <filter-name>gzip</filter-name>
      </use-filters>
      ...
   </initiator-config>
</remote-cache-scheme>
...

If the filter implements IXmlConfigurable, after instantiating the filter, Coherence sets the Config property with the following XML element:

<config>
  <param1>value1</param1>
  <param2>value2</param2>
</config>