Getting Started

1 Getting Started

This chapter introduces Coherence applications for WebLogic Server and provides an overview of creating and packaging Coherence Applications.

This chapter includes the following sections:

Introduction to Coherence Applications

Coherence is a distributed caching and in-memory data grid computing solution. Applications typically use Coherence to improve scalability, availability, and performance.

Coherence is tightly integrated with WebLogic Server. The integration aligns the lifecycle of a Coherence cluster member with the lifecycle of a managed server: starting or stopping a managed server JVM starts and stops a Coherence cluster member. Managed servers that are cluster members are referred to as managed Coherence servers. Some common use cases for Coherence include data caching, HTTP session replication, and database cache store (such as a Java Persistence API (JPA) level-two cache).

Like other Java EE modules, Coherence supports its own application module, which is called a Grid ARchive (GAR). The GAR contains the artifacts of a Coherence application and includes a deployment descriptor. A GAR is deployed and undeployed in the same way as Java EE modules and the application lifecycle is decoupled from the cluster service lifetime. Coherence applications and managed Coherence servers are not mandated by the JavaEE specification and are specific to WebLogic Server.

Typical Uses for Coherence

Coherence is used to provide solutions such as application data caching, data grid computing, session state persistence and management and access Java Persistence API (JPA) entities in the data cache.

This section describes typical uses for Coherence in WebLogic Server. The WebLogic Server Coherence integration allows applications to easily use Coherence data caches and incorporate Coherence*Web for session management and TopLink Grid as an object-to-relational persistence framework.

Providing Application Data Caching and Data Grid Computing

Applications use Coherence for replicated and distributed caching. Applications access data caches either through resource injection or component-based JNDI lookup. The Oracle WebLogic Server Administration Console and Oracle WebLogic Scripting Tool are used to manage and configure Coherence clusters.Using the Coherence integration enables you to create a data tier dedicated to caching application data and storing replicated session state. This is separate from the application tier—the WebLogic Server instances dedicated to running applications.

See Creating Coherence Applications for WebLogic Server.

Providing Session State Persistence and Management

Using Coherence*Web enables you to provide Coherence-based HTTP session state persistence to applications running on WebLogic Server. Coherence*Web enables HTTP session sharing and management across different Web applications, domains, and heterogeneous application servers. Session data can be stored in data caches outside of the application server, thus freeing application server heap space and enabling server restarts without losing session data.

See Introduction to Coherence*Web.

Accessing Java Persistence API (JPA) Entities in the Data Cache

TopLink Grid's relational-to-object mapping capabilities allows you to store copies of database queries and result sets in Coherence data caches. With this feature, database access occurs only when no cached copy of the required data exists, or when the application performs a create, update, or delete operation that must be persisted to the database. This added optimization provides improved scalability and performance to the system.

TopLink Grid allows JPA Entity caching. This lets you support very large, shared grid caches that span cluster nodes. If the data cache does not contain the object, then the database is queried.

TopLink Grid also enables you to direct queries to Coherence. If the desired query result is not found in the cache, it can be read from the database and then placed in the cache, making it available for subsequent queries. The ability of Coherence to manage very large numbers of objects increases the likelihood of a result being found in the cache, as read operations in one cluster member become immediately available to others.

Writing JPA Entities to the database is also made possible by TopLink Grid. Applications can directly write JPA Entities to the database, then put them into the data cache (so that it reflects the database state), or put JPA Entities into the data cache, and then have the data cache write them to the database.

See Accessing and Retrieving Relational Data.

Understanding Coherence Application Configuration Files

Coherence applications contain the Cache Configuration, POF Configuration, and Coherence Application Deployment Descriptor files used to configure caches, data types and so on.

A typical Coherence application that is deployed to WebLogic Server contains the following configuration files. See Developing Applications with Oracle Coherence.

Cache Configuration File – This file is used to specify the various types of caches which can be used within a Coherence cluster and is most often named coherence-cache-config.xml. This file is commonly referred to as the cache configuration deployment descriptor. The schema for this file is the coherence-cache-config.xsd file. See Developing Applications with Oracle Coherence for a complete reference of the elements in this file.
POF Configuration File – This file is used to specify custom data types when using Portable Object Format (POF) to serialize objects and is typically named pof-config.xml. This file is commonly referred to as the POF configuration deployment descriptor. The schema for this file is the coherence-pof-config.xsd file. See Developing Applications with Oracle Coherence for a complete reference of the elements in this file.
Coherence Application Deployment Descriptor – This file is used to configure a Coherence application module that is deployed to a managed Coherence server. See coherence-application.xml Deployment Descriptor Elements, for a complete reference of the elements in the descriptor.

Packaging and Deployment Overview

Coherence applications use a specific directory structure for deployment. You can deploy a Coherence application either in an exploded directory format, or as an archived file.

A Coherence application deployed as a collection of files within a specific directory structure is known as exploded directory format. A Coherence application deployed as an archived file is called a Grid ARchive (GAR) with a .gar extension. See Packaging Coherence Applications. The directory structure is as follows:

MyCohApp/
  lib/
  META-INF/
    coherence-application.xml

A standalone GAR is deployed to all managed Coherence servers in a Coherence data tier. A GAR must also be packaged within a EAR and deployed to all managed Coherence servers that reside in an application tier. See Deploying Coherence Applications in WebLogic Server.

Main Tasks for Creating Coherence Applications

A Coherence application can be created both as a standalone GAR module and packaged as part of an enterprise application.

The steps are detailed throughout this guide. For a complete Coherence application example, see the WebLogic Server Code Examples that are available with the WebLogic Server installation.

Task One: Create a Coherence Application Directory Structure

Create a staging directory that includes two subdirectories: META-INF/ and lib/:

MyCohApp/
  lib/
  META-INF/

Task Two: Include the Coherence Application's Artifacts

Include the Coherence application artifacts in the staging directory. For details on creating Coherence applications, see Creating Coherence Applications for WebLogic Server.

Place the Coherence application class files in the root of the staging directory in the appropriate package structure. For example:
```
MyCohApp/
  com/
    myco/
      MyClass.class
      MySerializer.class
  lib/
  META-INF/
```

Place application dependency libraries in the lib/ directory.

MyCohApp/
  com/
    myco/
      MyClass.class
      MySerializer.class
  lib/
      dependency.jar
  META-INF/

Include the coherence-cache-config.xml and the pof-config.xml file in the META-INF/ directory:

MyCohApp/
  com/
    myco/
      MyClass.class
  lib/
      dependency.jar
  META-INF/
    coherence-cache-config.xml
    pof-config.xml

Create a coherence-application.xml file in the META-INF directory.

MyCohApp/
  com/
    myco/
      MyClass.class
  lib/
      dependency.jar
  META-INF/
    coherence-application.xml
    coherence-cache-config.xml
    pof-config.xml

Edit the coherence-application.xml file and include the location of the configuration files using the <cache-configuration-ref> and <pof-configuration-ref> elements, respectively:

<?xml version="1.0"?>
<coherence-application>
   xmlns="http://xmlns.oracle.com/coherence/coherence-application">
   <cache-configuration-ref>META-INF/coherence-cache-config.xml
   </cache-configuration-ref>
   <pof-configuration-ref>META-INF/pof-config.xml</pof-configuration-ref>
</coherence-application>

Task Three: Package the Coherence Application for Deployment

Package the Coherence application as a GAR file for deployment to a Coherence data tier. Then, package the GAR file within an EAR for deployment to a Coherence application tier. SeeDeploying Coherence Applications in WebLogic Server.

From the command line, change directories to the root of the staging directory.
Use the Java jar command to compress the archive with a .gar extension. For example:
```
jar cvf MyCohApp.gar *
```
Copy the GAR and package it within an enterprise application directory structure. See Developing Applications for Oracle WebLogic Server for details on developing EAR. For example:
```
MyEAR/
  META-INF/
    application.xml
    weblogic-application.xml
  MyWAR.war
  MyEJB.jar
  MyCohApp.gar
```
The weblogic-application.xml file must contain a module reference for the GAR. For example:
```
<weblogic-application>
   <module>
      <name>MyCohApp</name>
      <type>GAR</type>
      <path>MyCohApp.gar</path>
   </module>
</weblogic-application>
```