Installing a Client Distribution

3 Installing a Client Distribution

Coherence provides C++ and .NET client distributions that can be installed as required. There is no separate Java client distribution. Java extend clients are created using Coherence for Java. In addition, the Coherence cluster is implemented in Java. Therefore, Coherence for Java must be installed to use any client distribution.

This chapter includes the following sections:

Installing Coherence for Java
The Coherence for Java distribution is used to build and use Java-based extend clients.
Installing the C++ Client Distribution
The Oracle Coherence for C++ distribution is used to develop and run C++ extend clients.
Installing the .NET Client Distribution
The Oracle Coherence for .NET distribution is used to develop and use .NET extend clients. It is published as a nuget package. The package name is Coherence and it can be downloaded from nuget.org.
Compatibility Between Coherence*Extend Versions
The extend protocol supports both forward and backwards version compatibility between extend clients and cluster proxies.

Installing Coherence for Java

The Coherence for Java distribution is used to build and use Java-based extend clients. To install Coherence for Java, see Installing Oracle Coherence for Java.

Parent topic: Installing a Client Distribution

Installing the C++ Client Distribution

The Oracle Coherence for C++ distribution is used to develop and run C++ extend clients. The latest version of the distribution can be downloaded at Oracle Coherence Software Downloads.

This section contains the following topics:

Parent topic: Installing a Client Distribution

Supported Environments for Coherence C++ Client

Table 3-1 lists the supported platforms and operating systems for Coherence for C++:

Table 3-1 Platform and Operating System Support for Coherence for C++

Operating System	Compiler	Architecture
Microsoft Windows Server: 2022+ Client: Windows 11+	Visual Studio 2015, 2017, and 2019	x86, x64
Linux	GCC 4.8.5+, GNU libc 2.1.7+	x86, x64, aarch64
Apple macOS 14+^Foot 1	Xcode 15+ (GCC)	aarch64

^Footnote 1

When building C++ applications with Apple macOS, you must compile with the command "g++" (as opposed to "CC").

Parent topic: Installing the C++ Client Distribution

Microsoft-Specific Requirements

When deploying on Microsoft Windows, just as with any Visual Studio based application, the corresponding Visual Studio runtime library package must be installed on the deployment computer.

Parent topic: Installing the C++ Client Distribution

Extracting the Coherence for C++ Distribution

Coherence for C++ is distributed as a ZIP file. Use a ZIP utility or the unzip command-line utility to extract the ZIP file to a location on the target computer. The extracted files are organized within a single directory called coherence-cpp.

The following example uses the unzip utility to extract the distribution to the /opt directory which is the suggested installation directory on UNIX-based operating systems. Use the ZIP utility provided with the target operating system if the unzip utility is not available.

unzip /path_to_zip/coherence-cpp-version_number-platform-architecture-compiler.zip -d /opt

The following example extracts the distribution using the unzip utility to the C:\ directory on the Windows operating system.

unzip C:\path_to_zip\coherence-cpp-version_number-platform-architecture-compiler.zip -d C:\

The following list describes the directories that are included in installation directory:

bin – This directory includes sanka.exe, which is an application launcher that is used to invoke executable classes embedded within a shared library.
doc – This directory contains Coherence for C++ documentation including the API documentation
include – This directory contains header files that use the Coherence API and must be compiled with an application.
lib – This directory includes the Coherence for C++ library. The coherence.dll file is the main development and run-time library and is discussed in detail throughout this documentation.

Parent topic: Installing the C++ Client Distribution

Installing the .NET Client Distribution

The Oracle Coherence for .NET distribution is used to develop and use .NET extend clients. It is published as a nuget package. The package name is Coherence and it can be downloaded from nuget.org.

Note:

As of 14.1.2.0.0, the Coherence .NET Client supports .NET 6.0 and later.

For earlier .NET versions, use Coherence 14.1.1.x. In 14.1.1.x, the package name for the .NET Core compatible implementation is Coherence.Core, while the package name for the .NET Framework 4.x compatible implementation is Coherence. For more information on the 14.1.1.x .NET Client, see Installing the .NET Client Distribution in Installing Oracle Coherence (14.1.1.0).

This section contains the following topics:

Parent topic: Installing a Client Distribution

Prerequisites

The following are required to use Coherence for .NET:

Microsoft .NET 6.0 or higher runtime and SDK
Supported Microsoft Windows operating system

Parent topic: Installing the .NET Client Distribution

Installing the Coherence .NET Client

Coherence for .NET is distributed as a nuget package and is published to nuget.org. You can install it from either Microsoft Visual Studio or the .NET command-line interface (.NET CLI).

To install Coherence for .NET using Visual Studio, follow these steps:
1. In Visual Studio, select Project, then Manage NuGet Packages.
2. On the NuGet Package Manager page, choose nuget.org as the Package source.
3. From the Browse tab, find Coherence in the list, and then select Install.
To install Coherence for .NET using the .NET CLI tool, follow these steps:
1. Open a command line interface and change to the directory that contains your project file.
2. Enter the following command to install the Coherence NuGet package: dotnet add package Coherence
  The dotnet add package command adds a package reference for Coherence to the project file, and then runs dotnet restore to install the package. After the command finishes, you can open the .csproj project file to see that the package reference was added.
```
 <ItemGroup>
    <PackageReference Include="Coherence" Version="14.1.2.0" />
</ItemGroup>
```
  By default, dotnet add package installs the latest version of the package. If you want to install a different version, add the -v or --version switches. For example, dotnet add package Coherence.Core --version 14.1.1.13
  
  Note:
  In 14.1.1.x, Coherence.Core is the package name for the .NET Core compatible implementation while Coherence is the package name for the .NET Framework 4.x compatible implementation.

Parent topic: Installing the .NET Client Distribution

Coherence .NET Version Number Mapping

A Coherence assembly uses a custom version number mapping. Oracle version numbers use 5 digits (N.N.N.N.N), but .NET version numbers can only have up to 4 digits (N.N.N.N). To support the .NET version convention, the 4th and 5th Oracle digits are combined for the 4th .NET version digit.

The following calculation is used to create the 4th .NET version digit:

4th .NET digit = 4th Oracle digit * 1000 + 5th Oracle digit

The following calculations are used to convert the 4th .NET version digit to the 4th and 5th Oracle version digits:

4th Oracle digit = int(4th .NET digit / 1000)

5th Oracle digit = 4th .NET digit - (4th Oracle digit * 1000)

For example:

.NET Version Number	Oracle Version Number
14.1.2.0	14.1.2.0.0
14.1.2.1	14.1.2.0.1
14.1.2.1000	14.1.2.1.0
14.1.2.1001	14.1.2.1.1
14.1.2.2010	14.1.2.2.10
14.1.2.10010	14.1.2.10.10

Note:

For logging, the .NET 4th digit is converted to the Oracle 4th and 5th digits so that logging messages appear the same as Java and C++ log messages.

Parent topic: Installing the .NET Client Distribution

Deploying Coherence for .NET

Coherence for .NET requires no specialized deployment configuration. Simply add a reference to the Coherence nuget package as described in Installing the Coherence .NET Client.

Parent topic: Installing the .NET Client Distribution

Compatibility Between Coherence*Extend Versions

The extend protocol supports both forward and backwards version compatibility between extend clients and cluster proxies.

In other words, cluster proxies support both older and newer version extend clients, and extend clients support both older and newer version cluster proxies. Compatibility for the extend protocol and POF is maintained between the second digit of major releases (for example, 14.1, 14.2, and so on) but may not be maintained between the first digit of major releases (for example, 14.x, 15.x, and so on).

Note:

Compatibility requires that the serializers in the different Coherence*Extend versions be compatible. For non-Java clients, compatibility requires the use of POF. For Java clients that use java.io.Serializable for serialization, the major version of Java Standard Edition used by the client must be the same as, or within one major version of, that used by the cluster.

Backward compatibility to cluster proxies is intended as an upgrade convenience and not as a long term solution. It allows extend clients to upgrade to a new version before the proxy server and cluster. However, a cluster should always be upgraded to the latest version as a best practice. When an extend client and the server it connects to are on different versions, the extend client is limited to the functionality of the older of the two releases or patch set versions.

Coherence Backward Compatibility Exception for 14.1.2.0.0

In general, compatibility for the extend protocol and POF is maintained between the second digit of major Coherence releases (for example, version 14.1.x would be compatible with version 14.2.x, and so on) but may not be maintained between the first digit of major releases (for example, version 14.x may not be compatible with version 15.x, and so on).

By exception to the extend compatibility policy, Coherence 14.1.2.0.0 extend protocol and POF support spans a broader range of versions. In addition to the standard extend version compatibility support, Coherence 14.1.2.0.0 proxy servers are also compatible with supported 12.x versions (for example, 12.2.1.4.x). And Coherence 14.1.2.0.0 extend clients are also compatible with Coherence 12.2.1.4.x proxy servers.

This exception to the extend compatibility policy may not be included in future Coherence releases. That is, future releases of Coherence proxy servers and extend clients that are a higher version than 14.1.2.0.x may not include this additional support for Coherence 12.x versions.

Parent topic: Installing a Client Distribution