Building Your First Coherence Application

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, refer to the examples available in the Coherence GitHub Repository. See Running the Coherence Examples in Installing Oracle Coherence.

This chapter includes the following sections:

Task 1: Install Coherence
If you haven't already done so, install Coherence.
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.
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.
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.

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.

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

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

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

Applications use the Coherence API to access and interact with a cache. The CoherenceSession class creates a Session instance using a default session provider then gets a reference to a NamedCache instance using the getCache method. The NamedCache instance is then used to retrieve and store objects in the cache. The Hello World application is very basic, but it does demonstrate using the Session and NamedCache APIs.

Example 2-1 The Sample HelloWorld Standalone Application

import com.tangosol.net.CoherenceSession;
import com.tangosol.net.NamedCache;
import com.tangosol.net.Session;

public class HelloWorld {
   public static void main(String[] args) throws Exception {

      String key = "k1";
      String value = "Hello World!";
        
      Session session = new CoherenceSession();
      NamedCache<String, String> cache = session.getCache("hello-example");
        
      cache.put(key, value);
      System.out.println(cache.get(key));
      session.close();

   }
}

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

Run the Sample Standalone Application

To run the standalone application example:

From a command prompt, compile the "Hello, World!" application. For example:
```
javac -cp COHERENCE_HOME/lib/coherence.jar com/examples/HelloWorld.java
```
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.distributed.localstorage=false -Dcoherence.wka=127.0.0.1 HelloWorld
```
Note:

If you are on Windows, then replace the : separator with ;
.

The "Hello, World!" application starts. The CoherenceSession instance is created and becomes a member of the cluster. 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, the session is closed 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:

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.
At the command-line tool command prompt, get the hello-example cache using the cache command:
```
cache hello-example
```
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