2 Building Your First Coherence Application

You can follow step-by-step instructions for building and running a basic Coherence example that demonstrates a few fundamental Coherence concepts.

The sample application is a simple "Hello, World!" application and is implemented as a standalone Java application.

Depending on the deployment type, framework, or language that you use, see Using Different Deployment Models, Frameworks, or Languages with Coherence.

Note:

The example in this chapter is basic and is intended only to teach general concepts. For more advanced examples, see the examples available in the Coherence GitHub Repository. See Running the Coherence Examples in Installing Oracle Coherence.

Security Prerequisites

The examples use a started Coherence instance and its configured session. Coherence 26.1.0.0 defaults to hardened. Before adding custom keys, values or executable classes, classify them and generate the application security configuration during the build. Include the generated META-INF/coherence/security-config.xml resource in the deployed application artifact on every process that needs it. Closing a borrowed session is not a substitute for shutting down an owned Coherence instance.

For the complete configuration and policy, see Understanding Security Profiles, Generating Application Security Configuration, Developing Classified Application Types in Securing Oracle Coherence.

This chapter includes the following sections:

Parent topic: Getting Started

Task 1: Install Coherence

If you haven't already done so, install Coherence.

If you want to install the commercial edition of Coherence, then see Installing Oracle Coherence for Java in Installing Oracle Coherence.

Be sure to replace COHERENCE_HOME with the full path of the Coherence directory of your installation.

Use the matching Coherence 26.1 distribution for all members and the sample client. Java 21 is the minimum for these examples; a supported Java 25 toolchain is suitable for compiling and running them without preview features. Set JAVA_HOME and put its bin directory on PATH. Set COHERENCE_HOME to the installed distribution directory containing lib/coherence.jar.

Parent topic: Building Your First Coherence Application

Task 2: Configure and Start the Example Cluster

Caches are hosted on a Coherence cluster. At runtime, any JVM process that is running Coherence automatically joins the cluster and can access the caches and other services provided by the cluster. When a JVM joins the cluster, it is called a cluster node, or alternatively, a cluster member.

For the sample applications in this chapter, two separate Java processes form the cluster: a cache server process and the "Hello, World!" application process. For simplicity, the two processes are colocated on a single computer. The cache server, by default, is configured to store cache data.

In the example, the default configuration is modified to create a private cluster which ensures that the two processes do not attempt to join an existing Coherence cluster that may be running on the network. The examples use the default cache configuration which is sufficient for most applications.

This example uses system properties to modify the default configuration, but you can also modify it using the configuration file. Specifically, the default configuration is modified to create a private cluster, which ensures that the two processes do not attempt to join an existing Coherence cluster that may be running on the network. The default cache configuration is sufficient for most applications.

To configure and start the example cluster:

Note:

Throughout this example, replace COHERENCE_HOME with the Coherence installation directory.

Use the same unique coherence.cluster name on the sample storage member and HelloWorld process. For example, add -Dcoherence.cluster=hello-example-unique to both commands and replace that value for each independent run. Keep the loopback well-known address for this local exercise. Wait for the storage service to start before running the storage-disabled application.

Coherence 26.1 defaults to the hardened security profile. String data and built-in cache operations in this exercise need no application allowlist. A production cluster additionally needs the intended membership, transport and authentication configuration; a unique cluster name and loopback address are example isolation settings.

  1. Start a cache server instance.

    Open a command-line utility and enter:

    java -Dcoherence.wka=127.0.0.1 -jar "$COHERENCE_HOME/lib/coherence.jar"

    Setting java -Dcoherence.wka=127.0.0.1 specifies that the cluster is running only on localhost.

    By default, Coherence auto-generates the cluster name. If you want to specify the name of the cluster yourself, then add -Dcoherence.cluster=myCluster to all of the commands that include the server and client.

Parent topic: Building Your First Coherence Application

Task 3: Create and Run a Basic Coherence Standalone Application

Task 3 is a multi-part step that includes a sample Hello World application and instructions for running and verifying the example.The application is run from the command line and starts a cluster node that joins with a cache server. The application puts a key named k1 with the value Hello World! into the hello-example cache and then gets and prints out the value of the key before exiting. Lastly, an additional cluster node is started to verify that the key is in the cache.

This section includes the following topics:

Parent topic: Building Your First Coherence Application

Create the Sample Standalone Application

Save the following complete Java 21 or later application as HelloWorld.java. It starts a Coherence cluster member, waits for startup, obtains a typed map from the default session, and closes the owned Coherence instance on exit. The sample stores String keys and values, so it needs no custom application-type or executable metadata.

Example 2-1 The Sample HelloWorld Standalone Application

import com.tangosol.net.Coherence;
import com.tangosol.net.NamedMap;

public class HelloWorld {
    public static void main(String[] args) {
        try (var coherence = Coherence.clusterMember().start().join()) {
            NamedMap<String, String> greetings =
                    coherence.getSession().getMap("hello-example");
            greetings.put("k1", "Hello World!");
            System.out.println(greetings.get("k1"));
        }
    }
}

Parent topic: Task 3: Create and Run a Basic Coherence Standalone Application

Run the Sample Standalone Application

To run the standalone application example:

  1. From a command prompt, compile the "Hello, World!" application. For example:
    javac --release 21 -cp "$COHERENCE_HOME/lib/coherence.jar" HelloWorld.java
  2. Run the "Hello, World!" application and include the location of the coherence.jar library and the configuration files as a Java -cp option. In addition, restrict the client from locally storing partitioned data by setting the coherence.distributed.localstorage property to false. Also, specify the system properties to ensure the client joins the correct cluster. For example:
    java -cp ".:$COHERENCE_HOME/lib/coherence.jar"   -Dcoherence.cluster=hello-example-unique   -Dcoherence.wka=127.0.0.1   -Dcoherence.distributed.localstorage=false HelloWorld

    Note:

    If you are on Windows, use ".;%COHERENCE_HOME%\lib\coherence.jar" as the classpath in Command Prompt and "%COHERENCE_HOME%\lib\coherence.jar" for compilation. Put the run command on one line and omit the Unix continuation backslashes

    .

    The "Hello, World!" application starts. The Coherence instance starts as a storage-disabled cluster member and waits for startup before accessing its session. The k1 key with the Hello World! value is loaded into the hello-example cache. The key is then retrieved from the cache and the value is emitted as part of the output. Lastly, closing the owned Coherence instance stops its sessions and leaves the cluster before the "Hello, World!" application exits.

Parent topic: Task 3: Create and Run a Basic Coherence Standalone Application

Verify the Example Cache

The cache server in this example is configured, by default, to store the cache's data. The data is available to all members of the cluster and persists even after members leave the cluster. For example, the Hello World application exits after it loads and displays a key in the cache. However, the cache and key are still available for all cluster members.

This step uses the cache factory command-line tool to connect to the hello-example cache and list all items in the cache. It demonstrates both the persistent and distributed nature of Coherence caches.

To verify the cache:

  1. From a command prompt, start a standalone cache factory instance using the CacheFactory class and include the location of the coherence.jar library and the configuration files as a Java -cp option. For example:
    java -cp "$COHERENCE_HOME/lib/coherence.jar" -Dcoherence.wka=127.0.0.1  -Dcoherence.distributed.localstorage=false com.tangosol.net.CacheFactory

    The cache factory instance starts and becomes a member of the cluster and returns a command prompt for the command-line tool.

  2. At the command-line tool command prompt, get the hello-example cache using the cache command:
    cache hello-example
  3. At the command-line tool command prompt, retrieve the contents of the cache using the list command.
    list

    The command returns and displays:

    k1 = Hello World!

Parent topic: Task 3: Create and Run a Basic Coherence Standalone Application

Using Different Deployment Models, Frameworks, or Languages with Coherence

The previously described "Hello, World!" example application is a simple demonstration on how to use Coherence and Java together.

You can also use Coherence with other common frameworks, deployment types, and languages.

For general information on Coherence integration, see Oracle Coherence - Integrate.

Otherwise, review the following sections for additional integration possibilities.

Helidon

Project Helidon is a set of Java Libraries for writing microservices. Coherence provides out of the box integration with Helidon.

For information on getting started with Helidon MP and Coherence, see Quick Start at the Coherence Community website.

Spring

Oracle Coherence can be integrated with Spring, which is a platform for building and running Java-based enterprise applications.

For information on getting started with Spring and Coherence, see the Coherence Spring Integration project on GitHub.

Micronaut

Oracle Coherence can be integrated with Micronaut, which is an open source framework for building lightweight modular applications and microservices.

For information on getting started with Micronaut and Coherence, see the Micronaut Coherence project on GitHub.

Kubernetes

Oracle enables organizations using Coherence to move their clusters into the cloud. By supporting industry standards, such as Docker and Kubernetes, Oracle facilitates running Coherence on cloud-neutral infrastructure.

For information on getting started with Coherence and Kubernetes, see the Coherence Operator repository on GitHub.

WebLogic Server

For information on developing and deploying Coherence applications in WebLogic Server, see Introduction to Coherence Applications in Developing Oracle Coherence Applications for Oracle WebLogic Server.

.NET

The Coherence .NET client allows .NET based applications to act as cache clients using the Coherence*Extend protocol.

For information on getting started with the Coherence .NET client, see Oracle Coherence for .NET - Community Edition on GitHub.

C++

The Coherence C++ client allows C++ applications to act as cache clients using the Coherence*Extend protocol.

For information on getting started with the Coherence C++ client, see Oracle Coherence for C++ Community Edition on GitHub.

JavaScript

The Coherence JavaScript client allows Node applications to act as cache clients to a Coherence cluster using gRPC as the network transport.

For information on getting started with the Coherence JavaScript client, see Coherence JavaScript Client on GitHub.

Python

The Coherence Python Client allows Python applications to act as cache clients to an Oracle Coherence cluster using gRPC as the network transport.

For information on getting started with the Coherence Python client, see Coherence Python Client on GitHub.

Golang

The Coherence Go Client allows Go applications to act as cache clients to an Oracle Coherence cluster using gRPC as the network transport.

For information on getting started with the Coherence Go client, see Coherence Go Client on GitHub.

Parent topic: Building Your First Coherence Application