#
# README.txt
#
# Copyright 2001-2007 by Oracle. All rights reserved.
#
# Oracle is a registered trademarks of Oracle Corporation and/or its
# affiliates.
#
# This software is the confidential and proprietary information of Oracle
# Corporation. You shall not disclose such confidential and proprietary
# information and shall use it only in accordance with the terms of the
# license agreement you entered into with Oracle.
#
# This notice may not be removed or altered.
#

README
======

Replicated-site Coherence*Extend Example

Contents
========

    * Overview
    * Prerequisites
    * Build Instructions
    * Running the Example

Overview
========

This example demonstrates how to use the features of Coherence*Extend to
replicate one or more caches from one site to another geographically
separated site. Use cases for this capability include hot/warm disaster
recovery strategies and read-only access to a locally cached replica of
remote data.

Assume that there are two sites, one in Boston and the other in London, which
are connected via a WAN. Each site is part of a separate Coherence cluster
(i.e. Coherence unicast and multicast UDP traffic cannot be sent over the
WAN). This example uses a ReadWriteBackingMap implementation in the Boston
cluster to replicate Boston caches to the London cluster via Coherence*Extend.
Once replicated, Boston data can be accessed in the London cluster at
"cluster-local" speeds. A Boston partitioned cache service uses write-behind
to decouple updates to the Boston caches from the corresponding updates to
the London replicas and to batch updates. Additionally, the Boston
partitioned cache service is configured to requeued failed updates to the
London replicas, so that if the WAN ever fails, changes to the Boston caches
will be automatically persisted to the London caches when the WAN comes back
up. Lastly, this example includes a Replicator command line utility that
allows the entire set of Boston caches to be re-replicated in case the London
cluster is restarted.

Prerequisites
=============

  To build the example, you must have the following software installed:

    * J2SE SDK 1.4 or later  (http://java.sun.com/)
    * Apache Ant             (http://ant.apache.org/)
    * Oracle Coherence 3.3   (http://www.oracle.com/technology/products/coherence/index.html)

Build Instructions
==================

  * Update bin/set-env.sh to reflect your system environment.

  * Open a shell and execute the following command in the bin directory:

      ./ant build

  * To completely remove all build artifacts from your filesystem, run:

      ./ant clean

Running the Example
===================

  * Start the London cluster by executing the following scripts:

      (1) ./start-server replica
      (2) ./start-client replica

  * Start the Boston cluster by executing the following scripts:

      (1) ./start-server master
      (2) ./start-client master

  * To access local data in the Boston cluster, run the following command:

      Map (?): cache boston-test

  * To access Boston data in the London cluster, run the following command:

      Map (?): cache boston-test

  * To force a replication of the "boston-test" cache from the Boston cluster
    to the London cluster, run the following script:

      ./start-replicator Invocation boston-test