Using the Coherence Java gRPC Client

26 Using the Coherence Java gRPC Client

The Coherence gRPC Java client allows Java applications to access Coherence clustered services, including data, data events, and data processing from outside the Coherence cluster. Typical uses for Java gRPC clients include desktop and web applications that require access to remote Coherence resources.

This provides an alternative to using Coherence*Extend when writing client applications.

Note:

The Coherence gRPC client and Coherence*Extend client feature sets do not match exactly; some functionality in Coherence gRPC is not available in Coherence*Extend and vice versa.

Like cache clients that are members of the cluster, Java gRPC clients use the Session API call to retrieve resources, such as NamedMap, NamedCache, and such. After it is obtained, a client accesses these resources in the same way as it would if it were part of the Coherence cluster. The fact that operations on Coherence resources are being sent to a remote cluster node (over gRPC) is completely transparent to the client application. For the Java gRPC client, you need to include the coherence-java-client module. For more information, see the topics in the following sections.

This chapter includes the following sections:

Before using custom payloads or server-side code, complete Preparing Remote Payloads and Executable Code. For Java lifecycle and resource ownership, see Using a Managed Java Remote Client Lifecycle. Native examples retain their own language and wire contracts; capability depends on the native release as well as the server.

Setting Up the Coherence gRPC Client
To set up and start using the Coherence gRPC Java client, you should declare it as a dependency of your project. The gRPC client is provided in the coherence-java-client module.
Configuring the Coherence gRPC Client
Like Coherence*Extend, a Coherence gRPC client accesses remote clustered resources by configuring remote schemes in the applications cache configuration file.
Accessing Coherence Resources
As the gRPC client is configured as a remote scheme in the cache configuration file, you can access the Coherence resources using the same Coherence APIs as used on cluster members or Extend clients.
Checking Remote Continuous Aggregation Capabilities
Check protocol support and application trust before using maintained aggregation and partition-local projections.
Creating a Complete Java gRPC Client Configuration
Configure endpoint discovery and an admitted serializer explicitly for a managed Java gRPC Session.

Parent topic: Getting Started with gRPC

Setting Up the Coherence gRPC Client

To set up and start using the Coherence gRPC Java client, you should declare it as a dependency of your project. The gRPC client is provided in the coherence-java-client module.

For example:

If using Maven, declare the server as follows:

pom.xml

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>${coherence.group.id}</groupId>
            <artifactId>coherence-bom</artifactId>
            <version>${coherence.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>${coherence.group.id}</groupId>
        <artifactId>coherence</artifactId>
    </dependency>
    <dependency>
        <groupId>${coherence.group.id}</groupId>
        <artifactId>coherence-java-client</artifactId>
    </dependency>
</dependencies>

In the pom.xml file, coherence.version property is the version of Coherence being used, and coherence.groupId property is either the Coherence commercial group id, com.oracle.coherence, or the CE group id, com.oracle.coherence.ce.

If using Gradle, declare the server as follows:

build.gradle

dependencies {
    implementation platform("${coherenceGroupId}:coherence-bom:${coherenceVersion}")

    implementation "${coherenceGroupId}:coherence"
    implementation "${coherenceGroupId}:coherence-java-client"
}

In the build.gradle file, coherenceVersion property is the version of Coherence being used, and coherenceGroupId property is either the Coherence commercial group id,com.oracle.coherence or the CE group id, com.oracle.coherence.ce.

Application requirements

These are POM/Gradle fragments, not complete build files. For the commercial release set the group to com.oracle.coherence and version to 26.1.0-0-0, or use the matching installed patch coordinates. Import the same BOM for all Coherence modules; do not mix independently chosen gRPC, proxy and client versions. Java 21 is the release baseline.

Application requirements

Use Creating a Complete Java gRPC Client Configuration for a complete local configuration with an explicitly admitted serializer. Configure TLS/identity before deployment.

Parent topic: Using the Coherence Java gRPC Client

Configuring the Coherence gRPC Client

Like Coherence*Extend, a Coherence gRPC client accesses remote clustered resources by configuring remote schemes in the applications cache configuration file.

This section includes the following topics:

Parent topic: Using the Coherence Java gRPC Client

Overview of Configuring gRPC Clients

You can configure a gRPC client using the following two approaches:

NameService - The simplest configuration in which the gRPC client uses the Coherence NameService to discover the gRPC endpoints in the cluster. In this configuration, Coherence discovers all the endpoints in the cluster that the gRPC proxy is listening on and the gRPC Java library’s standard client-side load balancer is used to load balance connections from the client to those proxy endpoints.
Fixed Endpoints - In this configuration, a fixed set of gRPC endpoints can be supplied via a custom AddressProvider configuration or the endpoints can be included in the software code. If multiple endpoints are provided, the gRPC Java library’s standard client-side load balancer is used to load balance connections from the client to those proxy endpoints.

These approaches work only in some deployment environments. For example, the NameService configurations works if both clients and cluster are inside the same containerized environment. In containerized environments such as Kubernetes, NameService configuration is typically configured with a single ingress point which load balances connections to the Coherence cluster Pods. The address of this ingress point is then used as a single fixed address in the remote gRPC cache configuration. But, the NameService configuration does not work in containerized environments where the cluster is inside a containerized environment, such as Kubernetes, and the client is external to the containerized environment.

Parent topic: Configuring the Coherence gRPC Client

Defining a Remote gRPC Cache

A remote cache is specialized cache service that routes cache operations to a cache on the Coherence cluster. The remote cache and the cache on the cluster must have the same cache name. Coherence gRPC clients use the NamedMap or NamedCache interface as normal to get an instance of the cache. At runtime, the cache operations are not executed locally but instead are sent using gRPC to a gRPC proxy service on the cluster. The fact that the cache operations are delegated to a cache on the cluster is transparent to the client.

A remote cache is defined within a <caching-schemes> node using the <remote-grpc-cache-scheme> element.

In the case of a minimal NameService configuration (simplest configuration), the gRPC client uses the NameService to locate the gRPC proxy endpoints, but without adding any address or port information in the <remote-grpc-cache-scheme> in the configuration file. As this configuration uses Coherence’s default cluster discovery mechanism to locate the Coherence cluster’s NameService and look up the gRPC endpoints, you must configure the client with the same cluster name and well-known address list (or multicast configuration) as the cluster being connected to.

The following example shows an absolute minimum, required configuration, in which a <remote-grpc-cache-scheme> is configured with <scheme-name> and <service-name> elements:

coherence-cache-config.xml

<caching-scheme-mapping>
   <cache-mapping>
      <cache-name>*</cache-name>
         <scheme-name>remote-grpc</scheme-name>
   </cache-mapping>
</caching-scheme-mapping>

<caching-schemes>
   <remote-grpc-cache-scheme>
      <scheme-name>remote-grpc</scheme-name>
      <service-name>RemoteGrpcCache</service-name>
   </remote-grpc-cache-scheme>
</caching-schemes>

In the case of minimal NameService configuration with different cluster name, wherein, the client is configured with a different cluster name to the cluster being connected to (that is, the client is in a different Coherence cluster), you can configure the <remote-grpc-cache-scheme> with a cluster name.

The following example shows <remote-grpc-cache-scheme> configured with <cluster-name>test-cluster</cluster-name>, so Coherence uses the NameService to discover the gRPC endpoints in the Coherence cluster named test-cluster:

coherence-cache-config.xml

<caching-scheme-mapping>
   <cache-mapping>
      <cache-name>*</cache-name>
         <scheme-name>remote-grpc</scheme-name>
   </cache-mapping>
</caching-scheme-mapping>

<caching-schemes>
   <remote-grpc-cache-scheme>
      <scheme-name>remote-grpc</scheme-name>
      <service-name>RemoteGrpcCache</service-name>
      <cluster-name>test-cluster</cluster-name>
   </remote-grpc-cache-scheme>
</caching-schemes>

Parent topic: Configuring the Coherence gRPC Client

Configuring the NameService Endpoints

If the client cannot use the standard Coherence cluster discovery mechanism to look up the target cluster, you can specify the NameService endpoints in the <grpc-channel> node of the <remote-grpc-cache-scheme> configuration.

The following example shows how to create a remote cache scheme that is named RemoteGrpcCache, which connects to the Coherence NameService on 198.168.1.5:7574, and then redirects the request to the address of the gRPC proxy service:

coherence-cache-config.xml

<caching-scheme-mapping>
   <cache-mapping>
      <cache-name>*</cache-name>
         <scheme-name>remote-grpc</scheme-name>
   </cache-mapping>
</caching-scheme-mapping>

<caching-schemes>
    <remote-grpc-cache-scheme>
        <scheme-name>remote-grpc</scheme-name>
        <service-name>RemoteGrpcCache</service-name>
        <grpc-channel>
            <name-service-addresses>
               <socket-address>
                  <address>198.168.1.5</address>
                  <port>7574</port>
               </socket-address>
            </name-service-addresses>
        </grpc-channel>
    </remote-grpc-cache-scheme>
</caching-schemes>

Parent topic: Configuring the Coherence gRPC Client

Configuring the Fixed Endpoints

If the NameService cannot be used to discover the gRPC endpoints, you can configure a fixed set of addresses by specifying a <remote-addresses> element containing one or more <socket-address> elements in the <grpc-channel> node.

The following example shows the client configuration that connects to a gRPC proxy listening on the endpoint test-cluster.svc:1408:

coherence-cache-config.xml

<caching-scheme-mapping>
   <cache-mapping>
      <cache-name>*</cache-name>
         <scheme-name>remote-grpc</scheme-name>
   </cache-mapping>
</caching-scheme-mapping>

<caching-schemes>
    <remote-grpc-cache-scheme>
        <scheme-name>remote-grpc</scheme-name>
        <service-name>RemoteGrpcCache</service-name>
        <grpc-channel>
            <remote-addresses>
               <socket-address>
                  <address>test-cluster.svc</address>
                  <port>1408</port>
               </socket-address>
            </remote-addresses>
        </grpc-channel>
    </remote-grpc-cache-scheme>
</caching-schemes>

Parent topic: Configuring the Coherence gRPC Client

Configuring SSL

Like other Coherence services, to configure the client to use SSL, configure the socket provider in the <grpc-channel> node of the <remote-grpc-cache-scheme> configuration . The<socket-provider> element can either contain the name of a socket provider configured in the operational override file, or can be configured with an inline socket provider configuration.

The following example shows the configuration of <remote-grpc-cache-scheme> with a reference to the socket provider named ssl that is configured in the operational override file:

coherence-cache-config.xml

<remote-grpc-cache-scheme>
    <scheme-name>remote-grpc</scheme-name>
    <service-name>RemoteGrpcCache</service-name>
    <grpc-channel>
        <remote-addresses>
           <socket-address>
              <address>test-cluster.svc</address>
              <port>1408</port>
           </socket-address>
        </remote-addresses>
        <socket-provider>ssl</socket-provider>
    </grpc-channel>
</remote-grpc-cache-scheme>

The following example shows the configuration of <remote-grpc-cache-scheme> with an inline socket provider:

coherence-cache-config.xml

<remote-grpc-cache-scheme>
    <scheme-name>remote-grpc</scheme-name>
    <service-name>RemoteGrpcCache</service-name>
    <grpc-channel>
        <remote-addresses>
           <socket-address>
              <address>test-cluster.svc</address>
              <port>1408</port>
           </socket-address>
        </remote-addresses>
        <socket-provider>
            <ssl>
                <identity-manager>
                    <key>server.key</key>
                    <cert>server.cert</cert>
                </identity-manager>
                <trust-manager>
                    <cert>server-ca.cert</cert>
                </trust-manager>
            </ssl>
        </socket-provider>
    </grpc-channel>
</remote-grpc-cache-scheme>

For more information about socket providers and how to configure them, see Using TLS to Secure Communication in Securing Oracle Coherence.

Application requirements

For 26.1 secure-transport enforcement, current socket-provider configuration and custom-channel responsibilities, see Requiring Secure gRPC Transport. Older credentials properties in this topic are specific to the provider/version that consumes them; do not assume they configure every current proxy/client implementation. Avoid embedding a real password in command lines, source files or logs.

Parent topic: Configuring the Coherence gRPC Client

Configuring the Client Thread Pool

Unlike an Extend client, the gRPC client is built on top of a gRPC asynchronous client that is configured with a thread pool to allow the client to process multiple parallel requests and responses. The gRPC client uses a standard Coherence dynamically sized thread pool where the number of threads automatically adjust depending on the load. Sometimes if Coherence does not adjust the thread pool optimally for an application use case, you can configure the pool size by adjusting the minimum thread count and the maximum thread count. The thread count must be greater than or equal to the minimum count, and less than or equal to the maximum count, and the maximum count must be greater than or equal to the minimum count.

If you want to configure a fixed size pool, set the minimum and maximum to the same value.

The following example shows how to configure all three thread counts, fixed, minimum, and maximum. The pool starts with 10 threads and is automatically sized between 5 and 15 threads depending on load.

coherence-cache-config.xml

<remote-grpc-cache-scheme>
    <scheme-name>remote-grpc</scheme-name>
    <service-name>RemoteGrpcCache</service-name>
    <grpc-channel>
        <remote-addresses>
           <socket-address>
              <address>test-cluster.svc</address>
              <port>1408</port>
           </socket-address>
        </remote-addresses>
    </grpc-channel>
    <thread-count>10</thread-count>
    <thread-count-max>15</thread-count-max>
    <thread-count-min>5</thread-count-min>
</remote-grpc-cache-scheme>

Parent topic: Configuring the Coherence gRPC Client

Accessing Coherence Resources

As the gRPC client is configured as a remote scheme in the cache configuration file, you can access the Coherence resources using the same Coherence APIs as used on cluster members or Extend clients.

If you started the client using the Coherence Bootstrap API, running a com.tangosol.net.Coherence instance, you can access a Session and NamedMap as shown below:

var session = Coherence.getInstance().getSession();
NamedMap<String, String> map = session.getMap("test-cache");

This section includes the following topic:

Using a Remote gRPC Cache As a Back Cache

Parent topic: Using the Coherence Java gRPC Client

Using a Remote gRPC Cache As a Back Cache

The gRPC client uses remote gRPC cache as a back cache of a near cache or a view cache in the same way as other types of caches.

The following example shows the configuration of a near cache that uses a <remote-grpc-cache-scheme> as the back cache:

coherence-cache-config.xml

<caching-scheme-mapping>
   <cache-mapping>
      <cache-name>*</cache-name>
         <scheme-name>near</scheme-name>
   </cache-mapping>
</caching-scheme-mapping>

<caching-schemes>
    <near-scheme>
      <scheme-name>near</scheme-name>
      <front-scheme>
        <local-scheme>
          <high-units>10000</high-units>
        </local-scheme>
      </front-scheme>
      <back-scheme>
        <remote-grpc-cache-scheme>
          <scheme-ref>remote-grpc</scheme-ref>
        </remote-grpc-cache-scheme>
      </back-scheme>
    </near-scheme>

    <remote-grpc-cache-scheme>
      <scheme-name>remote-grpc</scheme-name>
      <service-name>RemoteGrpcCache</service-name>
    </remote-grpc-cache-scheme>
</caching-schemes>

Parent topic: Accessing Coherence Resources

Checking Remote Continuous Aggregation Capabilities

Check protocol support and application trust before using maintained aggregation and partition-local projections.

Negotiate the connection first and require the protocol capability for the requested operation. A connection to an older proxy does not imply support for every API compiled into the new client.

Table 26-1 Continuous Aggregation remote requirements

Transport	Required capability	Older peer behavior
Java Extend	CacheService protocol 13 or later, with compatible storage members.	Unsupported registration/handle operations are rejected. Ordinary operations retain negotiated support.
Java gRPC	CacheService protocol 2 or later, with compatible storage members.	Older protocol 0/1 channels can serve supported ordinary cache operations; Continuous Aggregation is unavailable.
Native or other-language clients	An independently released client implementation of the corresponding operation.	A new server alone does not add a method to a C++, .NET, JavaScript, Python or Go client.

Continuous Aggregation registers a supported streaming aggregator/filter definition and maintains it with mutations. Reuse a handle for repeated queries; remove a registration when it is no longer needed. Affinity projection executes against partition-local maintained results through the entry-processor path; all requested associated keys must belong to one partition. It is not a distributed multi-partition transaction.

Complete API/lifecycle, supported aggregators, fallback and metadata requirements are in Using Continuous Aggregation, Continuous Aggregation Requirements and Compatibility and Projecting a Continuous Aggregation by Data Affinity. Normal on-demand aggregation, maintained-query fallback and unsupported-protocol rejection are distinct outcomes. Test the oldest proxy/storage combination in the supported deployment, including reconnect and failover.

Parent topic: Using the Coherence Java gRPC Client

Creating a Complete Java gRPC Client Configuration

Configure endpoint discovery and an admitted serializer explicitly for a managed Java gRPC Session.

Save this complete configuration as grpc-client-config.xml on the client classpath for Obtaining a Remote Session. Start a matching proxy on loopback port 1408 and the mapped storage service first. This isolated local demonstration uses cleartext and built-in string values; configure the protected channel from Requiring Secure gRPC Transport for deployment.

<?xml version="1.0"?>
<cache-config xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd">
  <caching-scheme-mapping>
    <cache-mapping><cache-name>*</cache-name><scheme-name>remote-grpc</scheme-name></cache-mapping>
  </caching-scheme-mapping>
  <caching-schemes>
    <remote-grpc-cache-scheme>
      <scheme-name>remote-grpc</scheme-name>
      <service-name>RemoteGrpcCache</service-name>
      <grpc-channel>
        <remote-addresses>
          <socket-address><address>127.0.0.1</address><port>1408</port></socket-address>
        </remote-addresses>
      </grpc-channel>
      <serializer>pof</serializer>
    </remote-grpc-cache-scheme>
  </caching-schemes>
</cache-config>

The client explicitly selects POF, one of the default admitted gRPC formats. Hardened proxies reject explicitly selected Java/defaultserializer formats unless the server serializer allowlist permits them. Serializer negotiation is separate from model/executable admission and transport identity. Do not depend on an older-protocol fallback to bypass a rejected serializer selection.

For custom POF types, provide compatible POF definitions and generated trust metadata on every receiving tier. Follow gRPC Serializer and Diagnostic Policy for client-selectable format policy. Use a non-default port/address by changing this configuration to match the intended proxy.

Parent topic: Using the Coherence Java gRPC Client