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:

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.

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

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

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:

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

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