Coherence developer's guide

1. Oracle® Coherence
Developer’s Guide
Release 3.7
E18677-01
April 2011
Provides contextual information, instructions, and examples
that are designed to teach Developers and Architects how to
use Coherence and develop Coherence-based applications.

2. Oracle Coherence Developer's Guide, Release 3.7
E18677-01
Copyright © 2008, 2011, Oracle and/or its affiliates. All rights reserved.
Primary Author: Joseph Ruzzi
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify,
license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means.
Reverse engineering, disassembly, or decompilation of this software, unless required by law for
interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data
delivered to U.S. Government customers are "commercial computer software" or "commercial technical
data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental
regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the
restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable
by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial
Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA
94065.
This software is developed for general use in a variety of information management applications. It is not
developed or intended for use in any inherently dangerous applications, including applications which may
create a risk of personal injury. If you use this software in dangerous applications, then you shall be
responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use
of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of
this software in dangerous applications.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks
of their respective owners.
This software and documentation may provide access to or information on content, products, and services
from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all
warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and
its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services.

3. Contents
Preface ............................................................................................................................................................ xxvii
Audience.................................................................................................................................................. xxvii
Documentation Accessibility ................................................................................................................ xxvii
Related Documents ............................................................................................................................... xxviii
Conventions ........................................................................................................................................... xxviii
Part I Getting Started
1 Introduction
Basic Concepts .......................................................................................................................................... 1-1
Clustered Data Management............................................................................................................ 1-1
A single API for the logical layer, XML configuration for the physical layer........................... 1-2
Caching Strategies.............................................................................................................................. 1-2
Data Storage Options......................................................................................................................... 1-2
Serialization Options ......................................................................................................................... 1-3
Configurability and Extensibility .................................................................................................... 1-3
Namespace Hierarchy ....................................................................................................................... 1-3
Read/Write Caching ................................................................................................................................. 1-4
NamedCache....................................................................................................................................... 1-4
Requirements for Cached Objects.................................................................................................... 1-4
NamedCache Usage Patterns ........................................................................................................... 1-5
Querying the Cache ................................................................................................................................. 1-6
Transactions ............................................................................................................................................... 1-6
HTTP Session Management................................................................................................................... 1-6
Invocation Service .................................................................................................................................... 1-7
Events.......................................................................................................................................................... 1-7
Object-Relational Mapping Integration .............................................................................................. 1-7
C++/.NET Integration .............................................................................................................................. 1-7
Management and Monitoring................................................................................................................ 1-8
2 Installing Oracle Coherence for Java
System Requirements.............................................................................................................................. 2-1
Extracting the Distribution..................................................................................................................... 2-1
Setting Environment Variables.............................................................................................................. 2-2
Running Coherence for the First Time................................................................................................. 2-2
iii

4. Create a Basic Cluster ........................................................................................................................ 2-2
Create a Cache .................................................................................................................................... 2-3
3 Understanding Configuration
Overview of the Default Configuration Files..................................................................................... 3-1
Specifying an Operational Configuration File................................................................................... 3-2
Using the Default Operational Override File................................................................................. 3-3
Specifying an Operational Override File ........................................................................................ 3-4
Defining Override Files for Specific Operational Elements......................................................... 3-4
Viewing Which Operational Override Files are Loaded.............................................................. 3-6
Specifying a Cache Configuration File ................................................................................................ 3-6
Using a Default Cache Configuration File...................................................................................... 3-7
Overriding the Default Cache Configuration File......................................................................... 3-7
Using the Cache Configuration File System Property.................................................................. 3-8
Viewing Which Cache Configuration File is Loaded ................................................................... 3-8
Specifying a POF Configuration File ................................................................................................... 3-9
Using the POF Configuration File System Property ..................................................................... 3-9
Combining Multiple POF Configuration Files ........................................................................... 3-10
Viewing Which POF Configuration Files are Loaded ............................................................... 3-11
Specifying Management Configuration Files ................................................................................. 3-11
Specifying a Custom Report Group Configuration File............................................................ 3-12
Overriding the Default Report Group Configuration File................................................. 3-12
Using the Report Group Configuration File System Property.......................................... 3-13
Specifying an MBean Configuration File..................................................................................... 3-13
Using the Default MBean Configuration Override File ..................................................... 3-13
Using the MBean Configuration File System Property ...................................................... 3-14
Viewing Which Management Configuration Files are Loaded................................................ 3-14
Disabling Schema Validation ............................................................................................................. 3-15
Understanding the XML Override Feature ...................................................................................... 3-15
Using the Predefined Override Files ............................................................................................ 3-16
Defining Custom Override Files ................................................................................................... 3-17
Defining Multiple Override Files for the Same Element........................................................... 3-19
Changing Configuration Using System Properties ........................................................................ 3-19
Using Preconfigured System Properties ...................................................................................... 3-20
Creating Custom System Properties ............................................................................................ 3-20
4 Building Your First Coherence Application
Step 1: Define the Example Cache ........................................................................................................ 4-1
Step 2: Configure and Start the Example Cluster............................................................................... 4-2
Step 3: Create an Run a Basic Coherence Standalone Application ................................................ 4-3
Create the Sample Standalone Application.................................................................................... 4-3
Run the Sample Standalone Application........................................................................................ 4-4
Verify the Example Cache................................................................................................................. 4-4
Step 4: Create and Run a Basic Coherence JavaEE Web Application............................................. 4-5
Create the Sample Web Application ............................................................................................... 4-5
Deploy and Run the Sample Web Application.............................................................................. 4-6
Verify the Example Cache................................................................................................................. 4-6
iv

5. Using JDeveloper for Coherence Development................................................................................. 4-7
Running Coherence in JDeveloper .................................................................................................. 4-7
Viewing Thread Dumps in JDeveloper........................................................................................ 4-10
Creating Configuration Files in JDeveloper................................................................................ 4-10
Part II Using Data Clusters
5 Introduction to Coherence Clusters
Cluster Overview...................................................................................................................................... 5-1
Understanding TCMP ............................................................................................................................. 5-1
Understanding Cluster Services ............................................................................................................ 5-2
6 Setting Up a Cluster
Overview of Setting Up Clusters .......................................................................................................... 6-1
Specifying a Cluster’s Name .................................................................................................................. 6-2
Specifying a Cluster Member’s Identity.............................................................................................. 6-2
Configuring Multicast Communication .............................................................................................. 6-3
Specifying a Cluster’s Multicast Address....................................................................................... 6-4
Changing the Multicast Socket Interface................................................................................. 6-5
Disabling Multicast Communication .............................................................................................. 6-5
Specifying the Multicast Time-to-Live............................................................................................ 6-5
Specifying the Multicast Join Timeout ............................................................................................ 6-6
Changing the Multicast Threshold .................................................................................................. 6-7
Specifying a Cluster Member’s Unicast Address .............................................................................. 6-7
Using Well Known Addresses ............................................................................................................... 6-9
Specifying WKA Member Addresses.............................................................................................. 6-9
Specifying a WKA Address Provider........................................................................................... 6-11
Enabling Single-Server Mode............................................................................................................. 6-12
Configuring Death Detection ............................................................................................................. 6-13
Changing TCP-Ring Settings......................................................................................................... 6-13
Changing the Heartbeat Interval .................................................................................................. 6-14
Disabling Death Detection ............................................................................................................. 6-14
Specifying Cluster Priorities............................................................................................................... 6-15
Specifying a Cluster Member’s Priority....................................................................................... 6-15
Specifying Thread Priority............................................................................................................. 6-16
7 Starting and Stopping Cluster Members
Starting Cache Servers............................................................................................................................. 7-1
Starting Cache Servers From the Command Line ......................................................................... 7-1
Starting Cache Servers Programmatically ...................................................................................... 7-2
Starting Cache Clients ............................................................................................................................. 7-2
Disabling Local Storage..................................................................................................................... 7-3
Using the CacheFactory Class to Start a Cache Client.................................................................. 7-3
Stopping Cluster Members .................................................................................................................... 7-3
Stopping Cluster Members From the Command Line ................................................................. 7-3
Stopping Cache Servers Programmatically ................................................................................... 7-4
v

6. 8 Dynamically Managing Cluster Membership
Using the Cluster and Service Objects................................................................................................. 8-1
Using the Member Object ...................................................................................................................... 8-2
Listening to Member Events .................................................................................................................. 8-2
9 Tuning TCMP Behavior
Overview of TCMP Data Transmission ............................................................................................... 9-1
Throttling Data Transmission................................................................................................................ 9-2
Adjusting Packet Flow Control Behavior ....................................................................................... 9-2
Disabling Packet Flow Control......................................................................................................... 9-3
Adjusting Packet Traffic Jam Behavior ........................................................................................... 9-3
Bundling Packets to Reduce Load......................................................................................................... 9-4
Changing Packet Retransmission Behavior ........................................................................................ 9-5
Changing the Packet Resend Interval ............................................................................................. 9-5
Changing the Packet Resend Timeout ............................................................................................ 9-6
Configuring Packet Acknowledgment Delays .............................................................................. 9-6
Configuring the Transmission Packet Pool Size ................................................................................ 9-7
Configuring the Size of the Packet Buffers......................................................................................... 9-8
Understanding Packet Buffer Sizing ............................................................................................... 9-8
Configuring the Outbound Packet Buffer Size .............................................................................. 9-8
Configuring the Inbound Packet Buffer Size ................................................................................. 9-9
Adjusting the Maximum Size of a Packet ........................................................................................ 9-10
Changing the Packet Speaker Volume Threshold .......................................................................... 9-11
Changing Message Handler Behavior............................................................................................... 9-11
Configuring the Incoming Message Handler ............................................................................. 9-12
Changing the Time Variance.................................................................................................. 9-12
Disabling Negative Acknowledgments................................................................................ 9-12
Configuring the Incoming Handler’s Packet Pool .............................................................. 9-13
Configuring the Outgoing Message Handler ............................................................................. 9-13
Configuring the Outgoing Handler’s Message Pool .......................................................... 9-14
Changing the TCMP Socket Provider Implementation................................................................. 9-14
Using the TCP Socket Provider..................................................................................................... 9-15
Using the SSL Socket Provider ...................................................................................................... 9-15
Enabling a Custom Socket Provider............................................................................................. 9-16
10 Using Network Filters
Overview of Network Filters .............................................................................................................. 10-1
Using the Compression Filter ............................................................................................................. 10-2
Enabling the Compression Filter for Specific Services .............................................................. 10-2
Enabling the Compression Filter for All Services ...................................................................... 10-2
Configuring the Compression Filter ............................................................................................ 10-3
Using the Encryption Filters ............................................................................................................... 10-4
Enabling the Symmetric Encryption Filter .................................................................................. 10-4
Symmetric Encryption Filter Parameters ............................................................................. 10-5
Enabling the PKCS Encryption Filter ........................................................................................... 10-5
PKCS Encryption Filter Parameters ...................................................................................... 10-6
vi

7. Using Custom Network Filters ........................................................................................................... 10-7
Declaring a Custom Filter .............................................................................................................. 10-7
Enabling a Custom Filter for Specific Services ........................................................................... 10-8
Enabling a Custom Filter for All Services.................................................................................... 10-8
Part III Using Caches
11 Introduction to Caches
Distributed Cache ................................................................................................................................. 11-1
Replicated Cache ................................................................................................................................... 11-5
Optimistic Cache ................................................................................................................................... 11-7
Near Cache.............................................................................................................................................. 11-7
Local Cache ............................................................................................................................................. 11-9
Remote Cache....................................................................................................................................... 11-10
Summary of Cache Types .................................................................................................................. 11-10
12 Configuring Caches
Overview................................................................................................................................................. 12-1
Defining Cache Mappings .................................................................................................................. 12-2
Using One-to-One Cache Mappings ............................................................................................ 12-2
Using Cache Name Pattern Mappings......................................................................................... 12-2
Specifying Initialization Parameters in a Mapping.................................................................... 12-3
Defining Cache Schemes ..................................................................................................................... 12-4
Defining Distributed Cache Schemes........................................................................................... 12-5
Defining Replicated Cache Schemes ............................................................................................ 12-5
Defining Optimistic Cache Schemes ............................................................................................ 12-6
Defining Local Cache Schemes ..................................................................................................... 12-7
Controlling the Growth of a Local Cache............................................................................. 12-7
Defining Near Cache Schemes ...................................................................................................... 12-8
Near Cache Invalidation Strategies ....................................................................................... 12-9
Using Scheme Inheritance................................................................................................................... 12-9
Using Cache Scheme Properties ....................................................................................................... 12-11
Using Parameter Macros .................................................................................................................... 12-12
13 Implementing Storage and Backing Maps
Cache Layers........................................................................................................................................... 13-1
Local Storage .......................................................................................................................................... 13-2
Operations .............................................................................................................................................. 13-3
Capacity Planning ................................................................................................................................. 13-4
Using Partitioned Backing Maps ....................................................................................................... 13-5
Using the Elastic Data Feature to Store Data ................................................................................... 13-7
Journaling Overview ...................................................................................................................... 13-7
Defining Journal Schemes.............................................................................................................. 13-8
Configuring a RAM Journal Backing Map........................................................................... 13-8
Configuring a Flash Journal Backing Map ........................................................................... 13-8
Referencing a Journal Scheme................................................................................................ 13-9
vii

8. Using a Journal Scheme for Backup Storage........................................................................ 13-9
Enabling a Custom Map Implementation for a Journal Scheme .................................... 13-10
Changing Journaling Behavior.................................................................................................... 13-10
Configuring the RAM Journal Resource Manager............................................................ 13-10
Configuring the Flash Journal Resource Manager............................................................ 13-11
14 Caching Data Sources
Overview of Caching Data Sources ................................................................................................... 14-1
Pluggable Cache Store .................................................................................................................... 14-2
Read-Through Caching ................................................................................................................. 14-2
Write-Through Caching ................................................................................................................ 14-2
Write-Behind Caching ................................................................................................................... 14-3
Write-Behind Requirements................................................................................................... 14-4
Refresh-Ahead Caching ................................................................................................................ 14-5
Selecting a Cache Strategy................................................................................................................... 14-6
Read-Through/Write-Through versus Cache-Aside ................................................................ 14-6
Refresh-Ahead versus Read-Through.......................................................................................... 14-6
Write-Behind versus Write-Through ........................................................................................... 14-6
Creating a CacheStore Implementation ........................................................................................... 14-6
Plugging in a CacheStore Implementation ...................................................................................... 14-7
Sample CacheStore ............................................................................................................................... 14-8
Sample Controllable CacheStore ..................................................................................................... 14-13
Implementation Considerations....................................................................................................... 14-17
Idempotency .................................................................................................................................. 14-17
Write-Through Limitations.......................................................................................................... 14-18
Cache Queries ................................................................................................................................ 14-18
Re-entrant Calls ............................................................................................................................. 14-18
Cache Server Classpath ................................................................................................................ 14-18
CacheStore Collection Operations .............................................................................................. 14-18
Connection Pools........................................................................................................................... 14-18
15 Serialization Paged Cache
Understanding Serialization Paged Cache....................................................................................... 15-1
Configuring Serialization Paged Cache............................................................................................ 15-2
Optimizing a Partitioned Cache Service........................................................................................... 15-2
Configuring for High Availability..................................................................................................... 15-2
Configuring Load Balancing and Failover ....................................................................................... 15-2
Supporting Huge Caches ..................................................................................................................... 15-3
16 Using Quorum
Overview................................................................................................................................................. 16-1
Using the Cluster Quorum .................................................................................................................. 16-1
Configuring the Cluster Quorum Policy ..................................................................................... 16-2
Using the Partitioned Cache Quorums ............................................................................................. 16-2
Configuring the Partitioned Cache Quorum Policy................................................................... 16-3
Using the Proxy Quorum ..................................................................................................................... 16-4
viii

9. Configuring the Proxy Quorum Policy........................................................................................ 16-4
Enabling Custom Action Policies....................................................................................................... 16-5
17 Cache Configurations by Example
Local Caches (accessible from a single JVM) .................................................................................. 17-1
In-memory Cache............................................................................................................................ 17-2
NIO In-memory Cache ................................................................................................................... 17-2
Size Limited In-memory Cache..................................................................................................... 17-2
In-memory Cache with Expiring Entries ..................................................................................... 17-2
Cache on Disk .................................................................................................................................. 17-3
Size Limited Cache on Disk ........................................................................................................... 17-3
Persistent Cache on Disk................................................................................................................ 17-3
In-memory Cache with Disk Based Overflow ............................................................................ 17-4
Cache of a Database ........................................................................................................................ 17-4
Clustered Caches (accessible from multiple JVMs) ...................................................................... 17-5
Replicated Cache ............................................................................................................................. 17-5
Replicated Cache with Overflow .................................................................................................. 17-5
Partitioned Cache ............................................................................................................................ 17-6
Partitioned Cache with Overflow ................................................................................................. 17-6
Partitioned Cache of a Database ................................................................................................... 17-7
Partitioned Cache with a Serializer .............................................................................................. 17-7
Near Cache ....................................................................................................................................... 17-8
Part IV Using the Programming API
18 Serializing Objects
19 Using Portable Object Format
Overview................................................................................................................................................. 19-1
Working with POF................................................................................................................................. 19-2
Implementing the PortableObject interface................................................................................. 19-2
Implementing the PofSerializer interface: ................................................................................... 19-2
Assigning POF Indexes .................................................................................................................. 19-3
Using the ConfigurablePofContext Class .................................................................................... 19-3
Configuring Coherence to Use the ConfigurablePofContext Class......................................... 19-4
Configure the ConfigurablePofContext Class Per Service................................................. 19-5
Configure the ConfigurablePofContext Class for All Services ......................................... 19-5
Configure the ConfigurablePofContext Class For the JVM............................................... 19-6
Using POF Extractors and POF Updaters ......................................................................................... 19-6
Navigating a POF object................................................................................................................. 19-7
Using PofExtractors ........................................................................................................................ 19-8
Using PofUpdaters.......................................................................................................................... 19-9
20 Pre-Loading a Cache
Performing Bulk Loading and Processing........................................................................................ 20-1
ix

10. Bulk Writing to a Cache ................................................................................................................ 20-1
Efficient processing of filter results .............................................................................................. 20-2
A Bulk Loading and Processing Example ................................................................................... 20-4
Performing Distributed Bulk Loading.............................................................................................. 20-9
A Distributed Bulk Loading Example........................................................................................ 20-10
21 Using Cache Events
Listener Interface and Event Object .............................................................................................. 21-1
Caches and Classes that Support Events .......................................................................................... 21-3
Signing Up for All Events.................................................................................................................... 21-4
Using an Inner Class as a MapListener............................................................................................. 21-5
Configuring a MapListener for a Cache ........................................................................................... 21-6
Signing up for Events on specific identities .................................................................................... 21-6
Filtering Events ...................................................................................................................................... 21-6
"Lite" Events ........................................................................................................................................... 21-7
Advanced: Listening to Queries ......................................................................................................... 21-8
Filtering Events Versus Filtering Cached Data........................................................................... 21-9
Advanced: Synthetic Events ................................................................................................................ 21-9
Advanced: Backing Map Events....................................................................................................... 21-10
Producing Readable Backing MapListener Events from Distributed Caches...................... 21-11
Advanced: Synchronous Event Listeners ....................................................................................... 21-13
22 Querying Data In a Cache
Query Overview .................................................................................................................................... 22-1
Query Concepts ............................................................................................................................... 22-2
Performing Simple Queries ................................................................................................................ 22-3
Using Query Indexes ............................................................................................................................ 22-3
Creating an Index ............................................................................................................................ 22-3
Creating User-Defined Indexes..................................................................................................... 22-4
Implementing the MapIndex Interface ................................................................................. 22-4
Implementing the IndexAwareExtractor Interface ............................................................. 22-5
Using a Conditional Index...................................................................................................... 22-6
Batching Queries and Memory Usage............................................................................................... 22-6
Queries Involving Multi-Value Attributes....................................................................................... 22-8
ChainedExtractor ................................................................................................................................... 22-8
23 Using Continuous Query Caching
Uses of Continuous Query Caching .................................................................................................. 23-1
The Coherence Continuous Query Cache ........................................................................................ 23-2
Constructing a Continuous Query Cache......................................................................................... 23-2
Cleaning up the resources associated with a ContinuousQueryCache .................................. 23-3
Caching only keys, or caching both keys and values..................................................................... 23-3
CacheValues Property and Event Listeners ................................................................................ 23-3
Listening to the ContinuousQueryCache ......................................................................................... 23-4
Achieving a Stable Materialized View ......................................................................................... 23-4
Support for Synchronous and Asynchronous Listeners ........................................................... 23-5
x

11. Making the ContinuousQueryCache Read-Only ........................................................................... 23-5
24 Processing Data In a Cache
Targeted Execution ................................................................................................................................ 24-1
Parallel Execution.................................................................................................................................. 24-2
Query-Based Execution ........................................................................................................................ 24-2
Data-Grid-Wide Execution .................................................................................................................. 24-2
Agents for Targeted, Parallel and Query-Based Execution ........................................................... 24-3
Data Grid Aggregation......................................................................................................................... 24-6
Node-Based Execution.......................................................................................................................... 24-8
Work Manager...................................................................................................................................... 24-10
25 Managing Map Operations with Triggers
A Map Trigger Example ....................................................................................................................... 25-2
26 Using Coherence Query Language
Understanding Coherence Query Language Syntax ...................................................................... 26-1
Query Syntax Basics........................................................................................................................ 26-2
Using Path-Expressions .......................................................................................................... 26-2
Using Bind Variables ............................................................................................................... 26-3
Using Key and Value Pseudo-Functions .............................................................................. 26-3
Using Aliases ............................................................................................................................ 26-3
Using Quotes with Literal Arguments ................................................................................. 26-3
Retrieving Data................................................................................................................................ 26-4
Retrieving Data from the Cache............................................................................................. 26-4
Filtering Entries in a Result Set .............................................................................................. 26-4
Managing the Cache Lifecycle....................................................................................................... 26-5
Creating a Cache ...................................................................................................................... 26-5
Writing a Serialized Representation of a Cache to a File .................................................. 26-6
Loading Cache Contents from a File..................................................................................... 26-6
Removing a Cache from the Cluster ..................................................................................... 26-7
Working with Cache Data.............................................................................................................. 26-7
Aggregating Query Results .................................................................................................... 26-7
Changing Existing Values....................................................................................................... 26-7
Inserting Entries in the Cache ................................................................................................ 26-8
Deleting Entries in the Cache ................................................................................................. 26-8
Working with Indexes .................................................................................................................... 26-8
Creating an Index on the Cache............................................................................................. 26-8
Removing an Index from the Cache...................................................................................... 26-9
Issuing Multiple Query Statements.............................................................................................. 26-9
Processing Query Statements in Batch Mode ...................................................................... 26-9
Using the CohQL Command-Line Tool .......................................................................................... 26-10
Starting the Command-line Tool ................................................................................................ 26-10
Using Command-Line Tool Arguments .................................................................................... 26-11
A Command-Line Example ......................................................................................................... 26-12
Building Filters in Java Programs .................................................................................................... 26-14
xi

12. Additional Coherence Query Language Examples....................................................................... 26-15
Simple SELECT * FROM Statements that Highlight Filters.................................................... 26-16
Complex Queries that Feature Projection, Aggregation, and Grouping .............................. 26-17
UPDATE Examples....................................................................................................................... 26-17
Key and Value Pseudo-Function Examples .............................................................................. 26-17
27 Performing Transactions
Overview of Transactions .................................................................................................................... 27-1
Using Explicit Locking for Data Concurrency................................................................................. 27-2
Using Entry Processors for Data Concurrency................................................................................. 27-3
Using the Transaction Framework API ............................................................................................. 27-5
Defining Transactional Caches...................................................................................................... 27-6
Performing Cache Operations within a Transaction ................................................................. 27-8
Using the NamedCache API .................................................................................................. 27-8
Using the Connection API ...................................................................................................... 27-9
Creating Transactional Connections .......................................................................................... 27-10
Using Transactional Connections ............................................................................................... 27-11
Using Auto-Commit Mode................................................................................................... 27-11
Setting Isolation Levels ......................................................................................................... 27-12
Using Eager Mode ................................................................................................................. 27-13
Setting Transaction Timeout ................................................................................................ 27-13
Using the OptimisticNamedCache Interface ............................................................................ 27-14
Configuring POF When Performing Transactions................................................................... 27-14
Configuring Transactional Storage Capacity ............................................................................ 27-15
Performing Transactions from Java Extend Clients................................................................. 27-16
Create an Entry Processor for Transactions ....................................................................... 27-16
Configure the Cluster-Side Transaction Caches................................................................ 27-17
Configure the Client-Side Remote Cache........................................................................... 27-18
Use the Transactional Entry Processor from a Java Client .............................................. 27-19
Viewing Transaction Management Information ...................................................................... 27-19
CacheMBeans for Transactional Caches............................................................................. 27-19
TransactionManagerBean ..................................................................................................... 27-20
Using the Coherence Resource Adapter ......................................................................................... 27-21
Performing Cache Operations within a Transaction ............................................................... 27-22
Creating a Coherence Connection ....................................................................................... 27-23
Getting a Named Cache ........................................................................................................ 27-24
Demarcating Transaction Boundaries................................................................................. 27-25
Packaging the Application........................................................................................................... 27-25
Configure the Connection Factory Resource Reference................................................... 27-26
Configure the Resource Adapter Module Reference........................................................ 27-26
Include the Required Libraries ............................................................................................ 27-27
Using the Coherence Cache Adapter for Transactions............................................................ 27-27
28 Data Affinity
Specifying Affinity ............................................................................................................................... 28-1
Specifying Data Affinity with a KeyAssociation............................................................................ 28-2
Specifying Data Affinity with a KeyAssociator.............................................................................. 28-2
xii

13. Example of Using Affinity................................................................................................................... 28-3
29 Priority Tasks
Priority Tasks — Timeouts................................................................................................................... 29-1
Configuring Execution Timeouts.................................................................................................. 29-1
Command Line Options................................................................................................................. 29-3
Priority Task Execution — Custom Objects ..................................................................................... 29-3
APIs for Creating Priority Task Objects....................................................................................... 29-4
Errors Thrown by Task Timeouts ................................................................................................. 29-5
30 Using the Service Guardian
Overview................................................................................................................................................. 30-1
Configuring the Service Guardian..................................................................................................... 30-2
Setting the Guardian Timeout....................................................................................................... 30-2
Setting the Guardian Timeout for All Threads.................................................................... 30-3
Setting the Guardian Timeout Per Service Type ................................................................. 30-3
Setting the Guardian Timeout Per Service Instance ........................................................... 30-4
Using the Timeout Value From the PriorityTask API ............................................................... 30-4
Setting the Guardian Service Failure Policy................................................................................ 30-5
Setting the Guardian Failure Policy for All Threads .......................................................... 30-5
Setting the Guardian Failure Policy Per Service Type........................................................ 30-6
Setting the Guardian Failure Policy Per Service Instance.................................................. 30-6
Enabling a Custom Guardian Failure Policy ....................................................................... 30-6
Issuing Manual Guardian Heartbeats............................................................................................... 30-8
31 Specifying a Custom Eviction Policy
32 Constraints on Re-entrant Calls
Re-entrancy, Services, and Service Threads ..................................................................................... 32-1
Parent-Child Object Relationships................................................................................................ 32-1
Avoiding Deadlock ......................................................................................................................... 32-2
Re-entrancy and Listeners ................................................................................................................... 32-3
A Operational Configuration Elements
Operational Deployment Descriptor................................................................................................... A-1
Operational Override File...................................................................................................................... A-2
Element Reference................................................................................................................................... A-3
access-controller ................................................................................................................................ A-5
address-provider ............................................................................................................................... A-6
authorized-hosts................................................................................................................................ A-7
cache-factory-builder-config............................................................................................................ A-8
callback-handler ................................................................................................................................ A-9
cluster-config ................................................................................................................................... A-10
cluster-quorum-policy .................................................................................................................... A-11
coherence .......................................................................................................................................... A-12
xiii

14. configurable-cache-factory-config ................................................................................................ A-13
filter ................................................................................................................................................... A-15
filters.................................................................................................................................................. A-16
flashjournal-manager...................................................................................................................... A-17
flow-control...................................................................................................................................... A-18
host-range......................................................................................................................................... A-19
identity-asserter............................................................................................................................... A-20
identity-manager ............................................................................................................................. A-21
identity-transformer ....................................................................................................................... A-22
incoming-message-handler............................................................................................................ A-23
init-param......................................................................................................................................... A-24
init-params ....................................................................................................................................... A-25
instance ............................................................................................................................................. A-26
journaling-config ............................................................................................................................. A-27
key-store ........................................................................................................................................... A-28
license-config ................................................................................................................................... A-29
logging-config.................................................................................................................................. A-30
management-config ........................................................................................................................ A-32
mbean................................................................................................................................................ A-34
mbeans .............................................................................................................................................. A-36
mbean-filter...................................................................................................................................... A-37
member-identity.............................................................................................................................. A-38
message-pool ................................................................................................................................... A-40
multicast-listener ............................................................................................................................. A-41
notification-queueing...................................................................................................................... A-43
outgoing-message-handler ............................................................................................................ A-44
outstanding-packets........................................................................................................................ A-45
packet-buffer .................................................................................................................................... A-46
packet-bundling .............................................................................................................................. A-47
packet-delivery ................................................................................................................................ A-48
packet-pool....................................................................................................................................... A-49
packet-publisher.............................................................................................................................. A-50
packet-size ........................................................................................................................................ A-51
packet-speaker ................................................................................................................................. A-52
pause-detection................................................................................................................................ A-53
provider ............................................................................................................................................ A-54
ramjournal-manager ....................................................................................................................... A-55
reporter ............................................................................................................................................. A-56
security-config ................................................................................................................................. A-57
serializer ........................................................................................................................................... A-58
serializers.......................................................................................................................................... A-59
service ............................................................................................................................................... A-60
Initialization Parameter Settings............................................................................................ A-61
DistributedCache Service Parameters ........................................................................... A-62
ReplicatedCache Service Parameters ............................................................................. A-66
InvocationService Parameters......................................................................................... A-67
ProxyService Parameters ................................................................................................. A-68
xiv

15. service-guardian.............................................................................................................................. A-70
services.............................................................................................................................................. A-71
shutdown-listener ........................................................................................................................... A-72
socket-address ................................................................................................................................. A-73
socket-provider................................................................................................................................ A-74
socket-providers .............................................................................................................................. A-76
ssl ....................................................................................................................................................... A-77
tcp-ring-listener ............................................................................................................................... A-78
traffic-jam ......................................................................................................................................... A-79
trust-manager .................................................................................................................................. A-80
unicast-listener................................................................................................................................. A-81
volume-threshold ............................................................................................................................ A-83
well-known-addresses.................................................................................................................... A-84
Attribute Reference............................................................................................................................... A-86
B Cache Configuration Elements
Cache Configuration Deployment Descriptor................................................................................... B-1
Element Reference................................................................................................................................... B-3
acceptor-config .................................................................................................................................. B-6
address-provider ............................................................................................................................... B-7
async-store-manager......................................................................................................................... B-8
authorized-hosts.............................................................................................................................. B-10
backing-map-scheme ...................................................................................................................... B-11
backup-storage ................................................................................................................................ B-12
bdb-store-manager.......................................................................................................................... B-14
bundle-config................................................................................................................................... B-16
cache-config...................................................................................................................................... B-17
cache-mapping ................................................................................................................................ B-18
cache-service-proxy ........................................................................................................................ B-19
cachestore-scheme........................................................................................................................... B-20
caching-scheme-mapping .............................................................................................................. B-21
caching-schemes.............................................................................................................................. B-22
class-scheme..................................................................................................................................... B-24
custom-store-manager.................................................................................................................... B-25
defaults ............................................................................................................................................. B-26
distributed-scheme.......................................................................................................................... B-27
external-scheme ............................................................................................................................... B-34
flashjournal-scheme ........................................................................................................................ B-38
identity-manager ............................................................................................................................. B-39
initiator-config ................................................................................................................................. B-40
init-param......................................................................................................................................... B-41
init-params ....................................................................................................................................... B-42
instance ............................................................................................................................................. B-43
invocation-scheme .......................................................................................................................... B-44
invocation-service-proxy................................................................................................................ B-47
key-associator .................................................................................................................................. B-48
key-partitioning............................................................................................................................... B-49
xv

16. key-store ........................................................................................................................................... B-50
lh-file-manager ................................................................................................................................ B-51
listener............................................................................................................................................... B-52
local-address .................................................................................................................................... B-53
local-scheme..................................................................................................................................... B-54
near-scheme ..................................................................................................................................... B-57
nio-file-manager .............................................................................................................................. B-60
nio-memory-manager..................................................................................................................... B-61
operation-bundling ......................................................................................................................... B-63
optimistic-scheme ........................................................................................................................... B-64
outgoing-message-handler ............................................................................................................ B-67
overflow-scheme ............................................................................................................................. B-69
paged-external-scheme................................................................................................................... B-72
partition-listener.............................................................................................................................. B-75
partitioned........................................................................................................................................ B-76
partitioned-quorum-policy-scheme ............................................................................................. B-77
provider ............................................................................................................................................ B-78
proxy-config..................................................................................................................................... B-79
proxy-scheme................................................................................................................................... B-80
proxy-quorum-policy-scheme....................................................................................................... B-83
ramjournal-scheme ......................................................................................................................... B-84
read-write-backing-map-scheme .................................................................................................. B-85
remote-addresses............................................................................................................................. B-90
remote-cache-scheme...................................................................................................................... B-91
remote-invocation-scheme............................................................................................................. B-92
replicated-scheme............................................................................................................................ B-93
serializer ........................................................................................................................................... B-97
socket-address ................................................................................................................................. B-98
socket-provider................................................................................................................................ B-99
ssl ..................................................................................................................................................... B-100
tcp-acceptor .................................................................................................................................... B-101
tcp-initiator..................................................................................................................................... B-105
transactional-scheme .................................................................................................................... B-107
trust-manager ................................................................................................................................ B-112
Attribute Reference............................................................................................................................. B-113
C Command Line Overrides
Override Example.................................................................................................................................... C-1
Preconfigured Override Values ............................................................................................................ C-1
D POF User Type Configuration Elements
POF Configuration Deployment Descriptor...................................................................................... D-1
Element Index .......................................................................................................................................... D-3
allow-interfaces ................................................................................................................................. D-4
allow-subclasses ................................................................................................................................ D-5
class-name .......................................................................................................................................... D-6
default-serializer................................................................................................................................ D-7
xvi