Running the Coherence Examples

6 Running the Coherence Examples

Coherence guides and tutorials are now hosted on the Coherence GitHub Repository and are documented here: Examples - Guides & Tutorials Overview. These examples can be run against Coherence 26 (26.1.0.0.0) and later.

Note:

In the rest of the document, examples refer to both guides and tutorials.

This chapter includes the following sections:

About Coherence Examples
There are two subsets of examples: Guides and Tutorials.
Obtaining the Examples
The examples are hosted on the Coherence GitHub repository.
Prerequisites
Each example has documentation outlining the prerequisites for building and running the specific example.
Running Examples Using Coherence 26 (26.1.0.0.0)
Perform the following procedures to run examples using Coherence 26 (26.1.0.0.0).

About Coherence Examples

There are two subsets of examples: Guides and Tutorials.

Guides - These simple guides are designed to be a quick hands-on introduction to a specific feature of Coherence. In most cases, they require nothing more than a Coherence JAR and an IDE (or a text editor). Guides are typically built as a combination of Maven and Gradle project, including the corresponding wrappers for those tools, making them simple to build as stand-alone projects without needing to build the whole Coherence source tree.

Tutorials - These tutorials provide a deeper understanding of larger Coherence features and concepts that cannot usually be explained with a few simple code snippets. They might, for example, require a running Coherence cluster to properly show a feature. Tutorials are typically built as a combination of Maven and Gradle project, including the corresponding wrappers for those tools, making them simple to build as stand-alone projects without needing to build the whole Coherence source tree.

Parent topic: Running the Coherence Examples

Obtaining the Examples

The examples are hosted on the Coherence GitHub repository.

In a directory of your choice, clone the examples using the following:

git clone https://github.com/oracle/coherence.git

This command clones the examples into a directory called coherence, off the current directory. You can find the examples in the prj/examples sub-directory.

The documentation for the examples is available online. See Examples - Guides & Tutorials Overview.

Application requirements

Select a published tag or commit that matches the Coherence API and example build you intend to use. A checkout of a moving development branch can require features or artifacts that are absent from the installed release. Use the example README to select its Java/toolchain requirements, then use the matching commercial Maven coordinates when running against Grid or Enterprise Edition.

Parent topic: Running the Coherence Examples

Prerequisites

Each example has documentation outlining the prerequisites for building and running the specific example.

As a minimum, you will require the following:

A JDK supported for Coherence 26.1; Java 21 is the minimum. Use Java 21 or 25 for the examples whose README supports that JDK.
Use the Maven or Gradle wrapper supplied by the selected example revision. When installing tools separately, use Maven 3.8.5 or later and a Gradle release that supports the JDK used to run Gradle. Java 21 requires Gradle 8.5 or later; Java 25 requires Gradle 9.1.0 or later. See Maven and Gradle.
You can also import the code straight into your IDE such as IntelliJ IDEA.

Parent topic: Running the Coherence Examples

Running Examples Using Coherence 26 (26.1.0.0.0)

Perform the following procedures to run examples using Coherence 26 (26.1.0.0.0).

This section includes the following topics:

Parent topic: Running the Coherence Examples

Installing the Prerequisites

After you have installed Oracle Coherence, you must install the required Coherence Maven POMs and JARs to run the examples. This step is required only once.

Set the COHERENCE_HOME environment variable to the coherence directory under your installation directory. For example, if Coherence is installed in the /u01/coherenceHome location, then COHERENCE_HOME=/u01/coherenceHome/coherence.

The examples below read the installed POMs and use their coordinates. Use a clean, single-release Oracle home; stop if metadata is missing or multiple versions are present. They install the listed Coherence artifacts only. Configure repositories for their transitive dependencies, or use the Maven synchronization plug-in to populate the complete distribution. Do not infer installed paths from a marketing version number.

Note:

You can also use the maven-sync plug-in to install all artifacts. See Introduction to the Maven Synchronization Plug-In in Developing Applications Using Continuous Integration.

For Linux/macOS:

install_coherence_artifact() {
  artifact=$1
  binary=$2
  metadata="$COHERENCE_HOME/plugins/maven/com/oracle/coherence/$artifact"
  test -d "$metadata" || { echo "Missing metadata: $metadata" >&2; return 1; }
  set -- "$metadata"/*/*.pom
  test "$#" -eq 1 && test -f "$1" || {
    echo "Select one matching installed POM for $artifact" >&2; return 1;
  }
  pom=$1
  test -f "$binary" || { echo "Missing artifact: $binary" >&2; return 1; }
  mvn install:install-file "-Dfile=$binary" "-DpomFile=$pom"
}
# The BOM is a POM artifact, not a JAR.
set -- "$COHERENCE_HOME"/plugins/maven/com/oracle/coherence/coherence-bom/*/*.pom
test "$#" -eq 1 && test -f "$1" || exit 1
mvn install:install-file -Dpackaging=pom "-Dfile=$1" "-DpomFile=$1" || exit 1
for artifact in coherence coherence-bedrock coherence-bedrock-testing-support \
                coherence-grpc coherence-grpc-proxy coherence-java-client coherence-json
do
  install_coherence_artifact "$artifact" "$COHERENCE_HOME/lib/$artifact.jar" || exit 1
done

Required for GraphQL:

for artifact in coherence-cdi-server coherence-cdi; do
  install_coherence_artifact "$artifact" "$COHERENCE_HOME/lib/$artifact.jar" || exit 1
done

For Windows PowerShell PowerShell:

function Install-CoherenceArtifact([string] $Artifact, [string] $Binary) {
    $metadata = Join-Path $env:COHERENCE_HOME "plugins/maven/com/oracle/coherence/$Artifact"
    $poms = @(Get-ChildItem -Path $metadata -Recurse -Filter '*.pom' -ErrorAction Stop)
    if ($poms.Count -ne 1) { throw "Select one matching installed POM for $Artifact" }
    if (-not (Test-Path $Binary -PathType Leaf)) { throw "Missing artifact: $Binary" }
    & mvn install:install-file "-Dfile=$Binary" "-DpomFile=$($poms[0].FullName)"
    if ($LASTEXITCODE -ne 0) { throw "Install failed: $Artifact" }
}
$boms = @(Get-ChildItem "$env:COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence-bom" -Recurse -Filter '*.pom' -ErrorAction Stop)
if ($boms.Count -ne 1) { throw 'Select one matching installed BOM' }
& mvn install:install-file -Dpackaging=pom "-Dfile=$($boms[0].FullName)" "-DpomFile=$($boms[0].FullName)"
if ($LASTEXITCODE -ne 0) { throw 'BOM installation failed' }
foreach ($artifact in @('coherence', 'coherence-bedrock', 'coherence-bedrock-testing-support',
                        'coherence-grpc', 'coherence-grpc-proxy', 'coherence-java-client', 'coherence-json')) {
    Install-CoherenceArtifact $artifact "$env:COHERENCE_HOME/lib/$artifact.jar"
}

Required for GraphQL:

foreach ($artifact in @('coherence-cdi-server', 'coherence-cdi')) {
    Install-CoherenceArtifact $artifact "$env:COHERENCE_HOME/lib/$artifact.jar"
}

For POF processing and hardened application metadata, synchronize the build plugins and their dependencies into the repository used by the examples. Maven uses pof-maven-plugin and security-config-maven-plugin. Gradle uses plug-in ID com.oracle.coherence; its marker is POM metadata that resolves the implementation, not a marker JAR to install by hand. Select an example that configures the required plug-in. These commands build that example after synchronization.

Building Examples with Application Security Metadata

For Linux/macOS:

# After repository synchronization, run the selected example wrapper.
./mvnw -Dcoherence.group.id=com.oracle.coherence \
  -Dcoherence.version=26.1.0-0-0 clean verify

For Windows PowerShell PowerShell:

.\mvnw.cmd -Dcoherence.group.id=com.oracle.coherence -Dcoherence.version=26.1.0-0-0 clean verify

Parent topic: Running Examples Using Coherence 26 (26.1.0.0.0)

Building and Running Any Example

To run any of the examples, you must change the group id and revision using the -D option in mvnw or the -P option in gradlew commands to set the Coherence version and group ID you are using.

Examples are shown below:

Maven:

./mvnw -Dcoherence.group.id=com.oracle.coherence -Drevision=26.1.0-0-0 clean verify

Gradle:

./gradlew -PcoherenceGroupId=com.oracle.coherence -PcoherenceVersion=26.1.0-0-0 clean build

Run these commands from the example build directory documented by the selected revision. Its wrapper version and dependency graph must support the selected JDK. Keep application classes, POF configuration and generated META-INF/coherence/security-config.xml on the runtime classpath. For a complete metadata-generating build, see Building Examples with Application Security Metadata.

Parent topic: Running Examples Using Coherence 26 (26.1.0.0.0)