- Introduction to Coherence
- How to Get Coherence Community Edition
- Getting Started
- Building
- CLI Hello Coherence Example
- Testing
- Documentation
- Contributing
Coherence is a scalable, fault-tolerant, cloud-ready, distributed platform for building grid-based applications and reliably storing data. The product is used at scale, for both compute and raw storage, in a vast array of industries such as critical financial trading systems, high performance telecommunication products and eCommerce applications.
Typically these deployments do not tolerate any downtime and Coherence is chosen due to its novel features in death detection, application data evolvability, and the robust, battle-hardened core of the product that enables it to be seamlessly deployed and adapted within any ecosystem.
At a high level, Coherence provides an implementation of the familiar IDictionary
interface but rather than storing the associated data in the local process it is partitioned
(or sharded) across a number of designated remote nodes. This partitioning enables
applications to not only distribute (and therefore scale) their storage across multiple
processes, machines, racks, and data centers but also to perform grid-based processing
to truly harness the CPU resources of the machines.
The Coherence interface INamedCache (an extension of IDictionary) provides methods
to query, aggregate (map/reduce style) and compute (send functions to storage nodes
for locally executed mutations) the data set. These capabilities, in addition to
numerous other features, enable Coherence to be used as a framework for writing robust,
distributed applications.
For more details on how to obtain and use Coherence, please see the Coherence CE README.
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.
Coherence for .NET consists of a lightweight .NET library that connects to a Coherence 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 clustered proxy service which, in turn, responds to client requests by delegating to an actual Coherence clustered service (for example, a Partitioned or Replicated cache service).
See the documentation for details on building Coherence applications using .NET.
- Microsoft .NET 6.0 or higher runtime and SDK
- Microsoft Visual Studio 2022+, or Visual Studio Code with the NET plugin installed is required to build
The Coherence for .NET also depends on docfx to build documentation.
The following additional dependencies are required for testing:
- Java 17 or later
To build Coherence for .NET, you must run the dotnet build utility, passing in the desired target that you would like to execute.
Using .NET 6, the output from the build is located in the src/<project>/bin/<Debug|Release>/net6.0 subdirectory.
Using .NET 8, the output from the build is located in the src/<project>/bin/<Debug|Release>/net8.0 subdirectory.
To build Coherence clone this repository and run the following commands:
For debug build run:
dotnet build
The resulting files:
src/Coherence/bin/Debug/net6.0/Coherence.dll
src/Coherence.SessionStore/bin/Debug/net6.0/Coherence.SessionStore.dll
For release build run:
dotnet build --configuration Release
The resulting files:
src/Coherence/bin/Release/net6.0/Coherence.dll
src/Coherence.SessionStore/bin/Release/net6.0/Coherence.SessionStore.dll
src/Coherence/bin/Release/Coherence.15.1.1.nupkg - nuget package
To clean all build artifacts from your build system, run the following command:
dotnet clean
The following example illustrates starting a storage enabled Coherence server, followed by running the HelloCoherence console application. The HelloCoherence application inserts and retrieves data from the Coherence server.
- Using dotnet-cli to create a HelloCoherence console application:
dotnet new console --name "HelloCoherence"
- Add the following references to the HelloCoherence.csproj (provide the Coherence.dll location in the
<HintPath>):
<ItemGroup>
<Reference Include="Coherence, Version=15.1.1.0, Culture=neutral, PublicKeyToken=0ada89708fdf1f9a, processorArchitecture=MSIL">
<HintPath>Coherence.dll</HintPath>
</Reference>
<PackageReference Include="Common.Logging" Version="3.4.1" />
<PackageReference Include="Microsoft.Extensions.Configuration" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="6.0.0" />
<PackageReference Include="System.Configuration.ConfigurationManager" Version="6.0.1" />
</ItemGroup>
Also include any Coherence configuration files you may have.
- Replace Program.cs code with the following source:
/*
* Copyright (c) 2000, 2024, Oracle and/or its affiliates.
*
* Licensed under the Universal Permissive License v 1.0 as shown at
* https://oss.oracle.com/licenses/upl.
*/
using System;
using Tangosol.Net;
using Tangosol.Net.Cache;
using Tangosol.Run.Xml;
namespace Hello
{
class Program
{
static void Main(string[] args)
{
// Display title as the C# console Coherence app and
// show user the valid commands:
Console.WriteLine("Coherence for .NET Extend Client");
Console.WriteLine("The following are the available cache operations:");
Console.WriteLine("\tcache <cacheName> - specify a cache name to use");
Console.WriteLine("\tput <key> <value> - put a <key, value> pair into the cache");
Console.WriteLine("\tget <key> - get the value of a given key from the cache");
Console.WriteLine("\tremove <key> - remove an entry of the given key from the cache");
Console.WriteLine("\tlist - list all the entries in the cache");
Console.WriteLine("\tsize - get the size of the cache");
Console.WriteLine("\tbye - exit the console");
Console.WriteLine();
Console.Write("Map (?): ");
// Declare variabs.
String cacheName = null;
INamedCache namedCache = null;
String op = Console.ReadLine().ToLower();
String[] opList = op.Split();
// Processing cache operations.
while (opList[0].CompareTo("bye") != 0)
{
String key;
String value;
if (!opList[0].Equals("cache") && namedCache == null)
{
Console.WriteLine("No named cache. Please specify a named cache to use.");
}
else
{
switch (opList[0])
{
case "cache":
if (opList.Length < 2)
{
Console.WriteLine("No cache name. Please specify a cache name to use.");
}
else
{
cacheName = opList[1];
namedCache = CacheFactory.GetCache(cacheName);
}
break;
case "put":
if (opList.Length < 3)
{
Console.WriteLine("No key/value pair. Please specify the key and value to be put into the cache.");
}
else
{
key = opList[1];
value = opList[2];
namedCache[key] = value;
}
break;
case "get":
if (opList.Length < 2)
{
Console.WriteLine("No key. Please specify the key to get.");
}
else
{
key = opList[1];
var result = namedCache[key];
Console.WriteLine(result == null ? "NULL" : namedCache[key]);
}
break;
case "remove":
if (opList.Length < 2)
{
Console.WriteLine("No key. Please specify the key to remove.");
}
else
{
key = opList[1];
namedCache.Remove(key);
}
break;
case "list":
foreach (ICacheEntry entry in namedCache.Entries)
{
Console.WriteLine(entry.Key + " = " + entry.Value);
}
break;
case "size":
Console.WriteLine(namedCache.Count);
break;
default:
Console.WriteLine("Valid operations are: cache, put, get, remove, list, size, and bye.");
break;
}
}
Console.WriteLine("");
if (namedCache == null)
{
Console.Write("Map (?): ");
}
else
{
Console.Write("Map (" + cacheName + "): ");
}
// Read cache operation
op = Console.ReadLine().ToLower();
opList = op.Split();
}
}
}
}
By default, you need to provide a POF configure file, pof-config.xml, in the TargetFramework directory. Below are a sample pof-config.xml file:
<?xml version="1.0"?>
<!--
Copyright (c) 2000, 2020, Oracle and/or its affiliates.
Licensed under the Universal Permissive License v 1.0 as shown at
https://oss.oracle.com/licenses/upl.
-->
<pof-config xmlns="http://schemas.tangosol.com/pof">
<user-type-list>
<!-- include all "standard" Coherence POF user types -->
<include>assembly://Coherence/Tangosol.Config/coherence-pof-config.xml</include>
<!-- include all application POF user types -->
</user-type-list>
</pof-config>
- Build the HelloCoherence project
dotnet build
"%JAVA_HOME%\bin\java" -Dcoherence.pof.enabled=true -Dcoherence.log.level=9 -jar coherence.jar
dotnet runCoherence for .NET Extend Client
The following are the available cache operations:
cache <cacheName> - specify a cache name to use
put <key> <value> - put a <key, value> pair into the cache
get <key> - get the value of a given key from the cache
remove <key> - remove an entry of the given key from the cache
list - list all the entries in the cache
size - get the size of the cache
bye - exit the console
Map (?): cache welcomes
Map (welcomes): get english
NULL
Map (welcomes): put english hello
Map (welcomes): put spanish hola
Map (welcomes): put french bonjour
Map (welcomes): get english
Hello
Map (welcomes): list
french = bonjour
english = hello
spanish = hola
Map (welcomes): bye
dotnet run
Coherence for .NET Extend Client
The following are the available cache operations:
cache <cacheName> - specify a cache name to use
put <key> <value> - put a <key, value> pair into the cache
get <key> - get the value of a given key from the cache
remove <key> - remove an entry of the given key from the cache
list - list all the entries in the cache
size - get the size of the cache
bye - exit the console
Map (?): cache welcomes
Map (welcomes): list
french = bonjour
english = hello
spanish = hola
Map (welcomes): bye
To run Coherence for .NET test suite, first you must run a Coherence server. Go to tests/test-server folder and start server:
cd tests/test-server
mvn clean package -Dcoherence.groupid=com.oracle.coherence.ce -Drevision=24.09 && mvn exec:exec -Dcoherence.groupid=com.oracle.coherence.ce -Drevision=24.09 -Dmain=com.tangosol.net.Coherence
To run the test suite (excluding ASP.NET session tests that require the commercial edition of Coherence), use the following command:
dotnet test --filter FullyQualifiedName\!~Tangosol.Web
To build Coherence for .NET API documentation, run the following command. The API documentation can be viewed using Microsoft help viewer.
cd doc
docfx docfx.json
For further details on developing Coherence for .NET applications, see the documentation here.
This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide
Please consult the security guide for our responsible security vulnerability disclosure process.
Copyright (c) 2020, 2024 Oracle and/or its affiliates.
Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.