26 Using the Coherence Java gRPC Client

The Coherence Java gRPC Client is a library that enables a Java application to connect to a Coherence gRPC proxy server.

This chapter includes the following sections:

• 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.

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.groupId}</groupId>
        <artifactId>coherence</artifactId>
    </dependency>
    <dependency>
        <groupId>${coherence.groupId}</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.

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:

• Overview of Configuring gRPC Clients
  
• Defining a Remote gRPC Cache
  
• Configuring the NameService Endpoints
  
• Configuring the Fixed Endpoints
  
• Configuring SSL
  
• Configuring the Client Thread Pool
  

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.

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>

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>

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>

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 SSL to Secure Communication in Securing Oracle Coherence.

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>

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:

Sessionsession = 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
  

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>