Oracle CoherenceDevelopers Guide

Release 3.5

E14509-01

June 2009

Oracle Coherence Developer's Guide, Release 3.5

E14509-01

Copyright 2008, 2009, Oracle and/or its affiliates. All rights reserved.

Primary Author: Joseph Ruzzi

Contributing Author: Noah Arliss, Jason Howes, Mark Falco, Alex Gleyzer, Gene Gleyzer, David Leibs, Andy Nguyen, Brian Oliver, Patrick Peralta, Cameron Purdy, Jonathan Purdy, Everet Williams, Tom Beerbower, John Speidel, Thomas Pfaeffle

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.

iii

Contents

Preface .............................................................................................................................................................. xviiAudience.................................................................................................................................................... xviiDocumentation Accessibility .................................................................................................................. xviiRelated Documents ................................................................................................................................. xviiiConventions ............................................................................................................................................. xviii

Part I Coherence Features

1 Create and Use Coherence Caches Creating a Cache in Your Application .................................................................................................. 1-1Configuring the Caches........................................................................................................................... 1-2Cache Configuration Descriptor Location........................................................................................... 1-5Putting It all Together: Your First Coherence Cache Example......................................................... 1-5Setting Up Your Test Environment ....................................................................................................... 1-5Modifying the Cache Configuration .................................................................................................... 1-9

2 Implement Transactions, Locks, and ConcurrencyConcurrency Options............................................................................................................................... 2-1Explicit Locking ........................................................................................................................................ 2-1Transactions ............................................................................................................................................... 2-2Container Integration .............................................................................................................................. 2-4

JCA ....................................................................................................................................................... 2-4XA......................................................................................................................................................... 2-6

Entry Processors........................................................................................................................................ 2-6Data Source Integration .......................................................................................................................... 2-8

3 Perform Continuous QueryUses of Continuous Query Caching ..................................................................................................... 3-1The Coherence Continuous Query Cache ........................................................................................... 3-2Constructing a Continuous Query Cache ............................................................................................ 3-2

Cleaning up the resources associated with a ContinuousQueryCache ..................................... 3-3Caching only keys, or caching both keys and values........................................................................ 3-3

CacheValues Property and Event Listeners ................................................................................... 3-3Listening to the ContinuousQueryCache ............................................................................................ 3-3

iv

Achieving a Stable Materialized View............................................................................................ 3-4Support for Synchronous and Asynchronous Listeners .............................................................. 3-5

Making the ContinuousQueryCache Read-Only .............................................................................. 3-5

4 Managing Map Operations with TriggersA Map Trigger Example .......................................................................................................................... 4-2

5 Data AffinitySpecifying Affinity .................................................................................................................................. 5-1Specifying Data Affinity with a KeyAssociation............................................................................... 5-2Specifying Data Affinity with a KeyAssociator................................................................................. 5-2Example of Using Affinity...................................................................................................................... 5-3

6 Query the CacheQuery Functionality ................................................................................................................................. 6-1Simple Queries ......................................................................................................................................... 6-1

Querying Partitioned Caches ........................................................................................................... 6-3Querying Near Caches ...................................................................................................................... 6-3

Query Concepts ........................................................................................................................................ 6-3Queries Involving Multi-Value Attributes.......................................................................................... 6-4ChainedExtractor ...................................................................................................................................... 6-5

7 Security FrameworkTransport Layer Security ......................................................................................................................... 7-1Access Controller...................................................................................................................................... 7-1Proof of Identity ....................................................................................................................................... 7-2Proof of Trustworthiness......................................................................................................................... 7-3Default Access Controller implementation ........................................................................................ 7-3Working in applications with installed security manager .............................................................. 7-5

8 Network FiltersCompression Filters ................................................................................................................................. 8-1Encryption Filters ..................................................................................................................................... 8-1

Symmetric Encryption Filter ............................................................................................................ 8-1Symmetric Encryption Filter Parameters........................................................................................ 8-2PKCS Encryption Filter ..................................................................................................................... 8-2PKCS Encryption Filter Parameters ................................................................................................ 8-3

Configuring Filters................................................................................................................................... 8-4Creating a Custom Filter ......................................................................................................................... 8-5

9 Priority TasksPriority Tasks Timeouts...................................................................................................................... 9-1

Configuring Execution Timeouts..................................................................................................... 9-1Execution Timeout Parameters ........................................................................................................ 9-1Command Line Options.................................................................................................................... 9-3

vPriority Task Execution Custom Objects ........................................................................................ 9-3APIs for Creating Priority Task Objects.......................................................................................... 9-3Errors Thrown by Task Timeouts .................................................................................................... 9-4

10 Specifying a Custom Eviction Policy

11 Serialization Paged CacheUnderstanding Serialization Paged Cache....................................................................................... 11-1Configuring Serialization Paged Cache............................................................................................ 11-1Optimizing a Partitioned Cache Service........................................................................................... 11-2Configuring for High Availability ..................................................................................................... 11-2Configuring Load Balancing and Failover ....................................................................................... 11-2Supporting Huge Caches ..................................................................................................................... 11-2

12 Pre-Loading the CachePerforming Bulk Loading and Processing........................................................................................ 12-1

Bulk Writing to a Cache ................................................................................................................ 12-1Efficient processing of filter results .............................................................................................. 12-2A Bulk Loading and Processing Example ................................................................................... 12-4

Performing Distributed Bulk Loading.............................................................................................. 12-9A Distributed Bulk Loading Example.......................................................................................... 12-9Running a Distributed Bulk Loading Example ........................................................................ 12-11

Building the Sample Application ........................................................................................ 12-11Running the Sample Application ........................................................................................ 12-11

13 Constraints on Re-entrant CallsRe-entrancy, Services, and Service Threads ..................................................................................... 13-1

Parent-Child Object Relationships................................................................................................ 13-1Avoiding Deadlock ......................................................................................................................... 13-2

Re-entrancy and Listeners ................................................................................................................... 13-2

Part II Testing and Tuning

14 Evaluating Performance and ScalabilityMeasuring Latency and Throughput................................................................................................. 14-1Demonstrating Scalability................................................................................................................... 14-1Tuning Your Environment ................................................................................................................... 14-2Measurements on a Large Cluster...................................................................................................... 14-2

15 Performing a Multicast Connectivity TestRunning the Multicast Test Utility .................................................................................................... 15-1

Sample Commands ......................................................................................................................... 15-1Multicast Test Example ........................................................................................................................ 15-2Troubleshooting Multicast Communications .................................................................................. 15-3

vi

16 Performing a Datagram Test for Network PerformanceRunning the Datagram Test Utility.................................................................................................... 16-1

Sample Commands for a Listener and a Publisher .................................................................... 16-2Datagram Test Example........................................................................................................................ 16-2Reporting ................................................................................................................................................ 16-3

Publisher Statistics .......................................................................................................................... 16-3Listener Statistics............................................................................................................................. 16-4

Throttling .................................................................................................................................. 16-5Bidirectional Testing................................................................................................................ 16-5Distributed Testing .................................................................................................................. 16-5

17 Configuring and Using Coherence*Extend General Instructions ............................................................................................................................. 17-1Configuring and Using Coherence*Extend-TCP ............................................................................ 17-2

Client-side Cache Configuration Descriptor............................................................................... 17-2Cluster-side Cache (a.k.a Coherence Extend Proxy) Configuration Descriptor .................... 17-4Launching an Extend-TCP DefaultCacheServer Process .......................................................... 17-5Launching an Extend-TCP Client Application ........................................................................... 17-5

Sample Coherence*Extend Client Application ............................................................................... 17-5Coherence*Extend InvocationService .......................................................................................... 17-6

Advanced Configuration ..................................................................................................................... 17-6Network Filters................................................................................................................................ 17-6Connection Error Detection and Failover.................................................................................... 17-8Read-only NamedCache Access ................................................................................................... 17-9Client-side NamedCache Locking ................................................................................................ 17-9Disabling Proxied Services .......................................................................................................... 17-10

18 High Resolution Timesource (Linux)

19 Performance TuningOperating System Tuning .................................................................................................................... 19-1

Socket Buffer Sizes .......................................................................................................................... 19-1High Resolution timesource (Linux) ............................................................................................ 19-2Datagram size (Microsoft Windows) ........................................................................................... 19-3Thread Scheduling (Microsoft Windows) ................................................................................... 19-3Swapping.......................................................................................................................................... 19-4

Network Tuning..................................................................................................................................... 19-4Network Interface Settings ............................................................................................................ 19-4Bus Considerations ......................................................................................................................... 19-5Network Infrastructure Settings ................................................................................................... 19-5Ethernet Flow-Control.................................................................................................................... 19-5Path MTU ......................................................................................................................................... 19-6

JVM Tuning ............................................................................................................................................ 19-6Server Mode ..................................................................................................................................... 19-6Sizing the Heap................................................................................................................................ 19-6GC Monitoring & Tuning............................................................................................................... 19-7

vii

Coherence Network Tuning ................................................................................................................ 19-7Validation ......................................................................................................................................... 19-7

20 Setting Single Server ModeSetting Single Server Mode in the Operation Configuration Descriptor .................................. 20-1Setting Single Server Mode on the Command Line....................................................................... 20-2

Part III Managing and Monitoring Oracle Coherence

21 How to Manage Coherence Using JMXAdd JMX libraries to the Coherence classpath ............................................................................... 21-1Configure the Coherence Management Framework ..................................................................... 21-2Access Coherence MBeans ................................................................................................................. 21-3Using Coherence MBeanConnector to Access MBeans ................................................................. 21-5Configuring Management Refresh Methodology .......................................................................... 21-6

22 JMX ReporterBasic Configuration .............................................................................................................................. 22-1Administration....................................................................................................................................... 22-1Data Analysis ......................................................................................................................................... 22-3Advanced Configuration ..................................................................................................................... 22-4

Creating Custom Reports............................................................................................................... 22-4Running Reporter in a Distributed Configuration..................................................................... 22-4

23 How to Create a Custom ReportConfiguring a Report File .................................................................................................................... 23-1

file-name Element ........................................................................................................................... 23-1file-name Macros...................................................................................................................... 23-1file-name Macro Examples ..................................................................................................... 23-2

Specifying Data Columns.................................................................................................................... 23-2How to Include an Attribute ......................................................................................................... 23-2How to Include Part of the Key..................................................................................................... 23-3How to Include Information from Composite Attributes......................................................... 23-3How to Include Information from Multiple MBeans................................................................. 23-3Including Multiple MBean Information Example...................................................................... 23-3How to Use Report Macros............................................................................................................ 23-4How to Include Constant Values.................................................................................................. 23-5

Including Queries in a Report ............................................................................................................ 23-5Using Filters to Construct Reports ..................................................................................................... 23-6Using Functions to Construct a Report ............................................................................................. 23-9

Function Examples.......................................................................................................................... 23-9Using Aggregates to Construct a Report......................................................................................... 23-10

Aggregate Examples ..................................................................................................................... 23-11Constructing Delta Functions ........................................................................................................... 23-11

Delta Function Examples ............................................................................................................. 23-12

viii

24 How to Modify Report BatchReport Batch Deployment Descriptor ............................................................................................... 24-1

Document Location......................................................................................................................... 24-1Document Root................................................................................................................................ 24-1System Properties............................................................................................................................ 24-1Document Format ........................................................................................................................... 24-2

Report Batch Element Index................................................................................................................ 24-3frequency .......................................................................................................................................... 24-4location.............................................................................................................................................. 24-5init-param......................................................................................................................................... 24-6init-params ....................................................................................................................................... 24-7output-directory .............................................................................................................................. 24-8param-name ..................................................................................................................................... 24-9param-type ..................................................................................................................................... 24-10param-value ................................................................................................................................... 24-11report-config .................................................................................................................................. 24-12report-group................................................................................................................................... 24-13report-list ........................................................................................................................................ 24-14

25 Analyzing Reporter ContentNetwork Health ..................................................................................................................................... 25-1Network Health Detail ......................................................................................................................... 25-1Memory Status ....................................................................................................................................... 25-2Cache Size ............................................................................................................................................... 25-3Service Report ........................................................................................................................................ 25-4Node List ................................................................................................................................................. 25-5Proxy Report ........................................................................................................................................... 25-5

26 How to Run a Report on DemandHow to Run ReportControl MBean at Node Startup ..................................................................... 26-1How to Configure the ReportControl MBean ................................................................................. 26-2

27 Configuring Custom MBeansCreating an MBean XML Configuration File .................................................................................. 27-1

Configuring Standard MBeans ..................................................................................................... 27-1Configuring MXBeans ................................................................................................................... 27-1Configuring JMX MBeans ............................................................................................................. 27-2

Enabling a Custom MBean Configuration File .............................................................................. 27-3Setting a System Property .............................................................................................................. 27-3Adding a Custom MBean Configuration File to the Class Path............................................... 27-3

28 How to Manage Custom MBeans Within the ClusterCustom MBean Configuration............................................................................................................ 28-1

How to Add a Standard MBean to Coherence ........................................................................... 28-1How to Programatically Add a Standard MBean to Coherence .............................................. 28-1

ix

How to Add a the Results of a JMX Query to Coherence ......................................................... 28-2

A Production ChecklistNetwork..................................................................................................................................................... A-2Hardware................................................................................................................................................... A-4Operating System .................................................................................................................................... A-7JVM ............................................................................................................................................................ A-8Java Security Manager.......................................................................................................................... A-10Application Instrumentation .............................................................................................................. A-10Coherence Editions and Modes ......................................................................................................... A-10

Ensuring that RTC nodes don't use Coherence TCMP.............................................................. A-11Coherence Operational Configuration.............................................................................................. A-12Coherence Cache Configuration ........................................................................................................ A-12Large Cluster Configuration ............................................................................................................... A-14Death Detection ..................................................................................................................................... A-14tangosol-license.xml Deprecated........................................................................................................ A-15

B Types of Caches in CoherenceDistributed Cache ................................................................................................................................... B-1Replicated Cache ..................................................................................................................................... B-1Optimistic Cache ..................................................................................................................................... B-1Near Cache ................................................................................................................................................ B-1Local Cache ............................................................................................................................................... B-2Remote Cache........................................................................................................................................... B-2Summary of Cache Types ...................................................................................................................... B-2

C Cache Semantics

D Cache Configuration ElementsCache Configuration Deployment Descriptor................................................................................... D-1

Document Location........................................................................................................................... D-1Document Root.................................................................................................................................. D-1Document Format ............................................................................................................................. D-1Command Line Override ................................................................................................................. D-1Examples ............................................................................................................................................ D-2

Element Index .......................................................................................................................................... D-3acceptor-config .................................................................................................................................. D-5address-provider ............................................................................................................................... D-7async-store-manager......................................................................................................................... D-8backing-map-scheme...................................................................................................................... D-10backup-storage ................................................................................................................................ D-11bdb-store-manager.......................................................................................................................... D-13bundle-config................................................................................................................................... D-14cache-config...................................................................................................................................... D-15cache-mapping ................................................................................................................................ D-16cache-service-proxy ........................................................................................................................ D-17

xcachestore-scheme........................................................................................................................... D-18caching-scheme-mapping .............................................................................................................. D-19caching-schemes.............................................................................................................................. D-20class-scheme..................................................................................................................................... D-24custom-store-manager.................................................................................................................... D-25disk-scheme...................................................................................................................................... D-26distributed-scheme.......................................................................................................................... D-27external-scheme............................................................................................................................... D-33initiator-config ................................................................................................................................. D-37init-param......................................................................................................................................... D-38init-params ....................................................................................................................................... D-40invocation-scheme .......................................................................................................................... D-41invocation-service-proxy................................................................................................................ D-43jms-acceptor ..................................................................................................................................... D-44jms-initiator ...................................................................................................................................... D-45key-associator .................................................................................................................................. D-46key-partitioning............................................................................................................................... D-47lh-file-manager ................................................................................................................................ D-48listener............................................................................................................................................... D-49local-scheme..................................................................................................................................... D-50near-scheme ..................................................................................................................................... D-54nio-file-manager .............................................................................................................................. D-57nio-memory-manager..................................................................................................................... D-58operation-bundling ......................................................................................................................... D-60optimistic-scheme ........................................................................................................................... D-61outgoing-message-handler ............................................................................................................ D-63overflow-scheme ............................................................................................................................. D-65paged-external-scheme................................................................................................................... D-68partition-listener.............................................................................................................................. D-71partitioned........................................................................................................................................ D-72proxy-config..................................................................................................................................... D-73proxy-scheme................................................................................................................................... D-74read-write-backing-map-scheme .................................................................................................. D-76remote-cache-scheme...................................................................................................................... D-80remote-invocation-scheme............................................................................................................. D-81replicated-scheme............................................................................................................................ D-82tcp-acceptor ...................................................................................................................................... D-84tcp-initiator....................................................................................................................................... D-86version-persistent-scheme ............................................................................................................. D-89version-transient-scheme ............................................................................................................... D-90versioned-backing-map-scheme ................................................................................................... D-91versioned-near-scheme................................................................................................................... D-95

E Cache Configuration Parameter Macros

F Sample Cache ConfigurationsLocal Caches (accessible from a single JVM) .................................................................................... F-2

xi

In-memory Cache.............................................................................................................................. F-2NIO In-memory Cache ..................................................................................................................... F-2Size Limited In-memory Cache....................................................................................................... F-2In-memory Cache with Expiring Entries ....................................................................................... F-2Cache on Disk .................................................................................................................................... F-3Size Limited Cache on Disk ............................................................................................................. F-3Persistent Cache on Disk.................................................................................................................. F-3In-memory Cache with Disk Based Overflow .............................................................................. F-4Cache of a Database .......................................................................................................................... F-4

Clustered Caches (accessible from multiple JVMs) ........................................................................ F-5Replicated Cache ............................................................................................................................... F-5Replicated Cache with Overflow .................................................................................................... F-5Partitioned Cache .............................................................................................................................. F-6Partitioned Cache with Overflow................................................................................................... F-6Partitioned Cache of a Database ..................................................................................................... F-6Partitioned Cache with a Serializer ................................................................................................ F-7Local Cache of a Partitioned Cache (Near cache)......................................................................... F-7

G Sample CacheStoresSample CacheStore ................................................................................................................................. G-1Sample Controllable CacheStore ......................................................................................................... G-6

H Operational Configuration ElementsOperational Configuration Deployment Descriptors ...................................................................... H-1

Document Location........................................................................................................................... H-1Document Root.................................................................................................................................. H-1Document Format ............................................................................................................................. H-1Operational Override File (tangosol-coherence-override.xml) ................................................. H-2Command Line Override ................................................................................................................. H-2

Element Index .......................................................................................................................................... H-3access-controller ................................................................................................................................ H-5address-provider ............................................................................................................................... H-6authorized-hosts................................................................................................................................ H-7burst-mode ......................................................................................................................................... H-8callback-handler ................................................................................................................................ H-9class-name ........................................................................................................................................ H-10cluster-config ................................................................................................................................... H-11coherence .......................................................................................................................................... H-12configurable-cache-factory-config ................................................................................................ H-13filters.................................................................................................................................................. H-14flow-control...................................................................................................................................... H-15host-range......................................................................................................................................... H-16incoming-message-handler............................................................................................................ H-17init-param......................................................................................................................................... H-18init-params ....................................................................................................................................... H-19license-config ................................................................................................................................... H-20

xii

logging-config.................................................................................................................................. H-21management-config ........................................................................................................................ H-25member-identity.............................................................................................................................. H-27multicast-listener ............................................................................................................................. H-29notification-queueing...................................................................................................................... H-31outgoing-message-handler ............................................................................................................ H-32outstanding-packets........................................................................................................................ H-34packet-buffer .................................................................................................................................... H-35packet-bundling .............................................................................................................................. H-36packet-pool....................................................................................................................................... H-37packet-delivery ................................................................................................................................ H-38packet-publisher.............................................................................................................................. H-39packet-size ........................................................................................................................................ H-41packet-speaker ................................................................................................................................. H-42pause-detection................................................................................................................................ H-43security-config ................................................................................................................................. H-44service-guardian.............................................................................................................................. H-45services.............................................................................................................................................. H-46shutdown-listener ........................................................................................................................... H-48socket-address ................................................................................................................................. H-49tcp-ring-listener ............................................................................................................................... H-50traffic-jam ......................................................................................................................................... H-51unicast-listener................................................................................................................................. H-52volume-threshold............................................................................................................................ H-54well-known-addresses.................................................................................................................... H-55

Element Attributes ................................................................................................................................ H-57

I Initialization Parameter SettingsDistributedCache Service Parameters ................................................................................................... I-3ReplicatedCache Service Parameters..................................................................................................... I-7InvocationService Parameters................................................................................................................. I-8ProxyService Parameters .......................................................................................................................... I-9Compression Filter Parameters............................................................................................................. I-10

J POF User Type Configuration ElementsPOF User Type Deployment Descriptor .............................................................................................. J-1

Document Location............................................................................................................................ J-1Document Root................................................................................................................................... J-1Document Format .............................................................................................................................. J-1Command Line Override .................................................................................................................. J-2

Element Index ........................................................................................................................................... J-3allow-interfaces .................................................................................................................................. J-4allow-subclasses ................................................................................................................................. J-5class-name ........................................................................................................................................... J-6include ................................................................................................................................................. J-7init-param............................................................................................................................................ J-8init-params .......................................................................................................................................... J-9

xiii

param-type ........................................................................................................................................ J-10param-value ...................................................................................................................................... J-11pof-config .......................................................................................................................................... J-12serializer ............................................................................................................................................ J-13type-id................................................................................................................................................ J-15user-type............................................................................................................................................ J-16user-type-list ..................................................................................................................................... J-17

K MBean Configuration ElementsMBeans in the Coherence Deployment Descriptor .......................................................................... K-1

Document Root.................................................................................................................................. K-1Document Format ............................................................................................................................. K-1

MBean Configuration Element Index ................................................................................................. K-2extend-lifecycle .................................................................................................................................. K-3enabled................................................................................................................................................ K-4mbean.................................................................................................................................................. K-5mbean-accessor.................................................................................................................................. K-6mbean-class ........................................................................................................................................ K-7mbean-factory .................................................................................................................................... K-8mbean-name....................................................................................................................................... K-9mbean-query .................................................................................................................................... K-10mbeans .............................................................................................................................................. K-11

L Command Line OverridesOverride Example..................................................................................................................................... L-1Preconfigured Override Values ............................................................................................................. L-2

M Platform-Specific Deployment ConsiderationsDeploying to AIX .................................................................................................................................... M-1

Socket Buffers sizes and JVMs ........................................................................................................ M-1Multicast and IPv6 ............................................................................................................................ M-1Unique Multicast Addresses and Ports ......................................................................................... M-2

Deploying to Oracle JRockit JVMs...................................................................................................... M-2JRockit and the Native Posix Thread Library (NPTL) ................................................................. M-2AtomicLong ....................................................................................................................................... M-2OutOfMemoryError.......................................................................................................................... M-2

Deploying to Cisco Switches ................................................................................................................ M-2Buffer Space and Packet Pauses ..................................................................................................... M-2Multicast Connectivity on Large Networks .................................................................................. M-3Multicast Outages ............................................................................................................................. M-3

Deploying to Foundry Switches........................................................................................................... M-5Multicast Connectivity ..................................................................................................................... M-5

Deploying to IBM BladeCenters .......................................................................................................... M-5MAC Address Uniformity and Load Balancing........................................................................... M-5

Deploying to IBM JVMs ........................................................................................................................ M-6UDP Socket Buffer Sizes................................................................................................................... M-6

xiv

OutOfMemoryError.......................................................................................................................... M-6Heap Sizing ........................................................................................................................................ M-6

Deploying to Linux ................................................................................................................................. M-6Native POSIX Thread Library (NPTL) .......................................................................................... M-6TSC High Resolution Timesource .................................................................................................. M-7

Deploying to OS X .................................................................................................................................. M-7Multicast and IPv6 ............................................................................................................................ M-7Unique Multicast Addresses and Ports ......................................................................................... M-7Socket Buffer Sizing .......................................................................................................................... M-8

Deploying to Solaris ............................................................................................................................... M-8Solaris 10 (x86 and SPARC) ............................................................................................................. M-8Solaris 10 Networking ...................................................................................................................... M-8

Deploying to Sun JVMs ......................................................................................................................... M-8Heap Sizes .......................................................................................................................................... M-8AtomicLong ....................................................................................................................................... M-8OutOfMemoryError.......................................................................................................................... M-9

Deploying to Virtual Machines ............................................................................................................ M-9Supported Deployment.................................................................................................................... M-9Multicast Connectivity ..................................................................................................................... M-9Performance ....................................................................................................................................... M-9Fault Tolerance ............................................................................................................................... M-10

Deploying to Windows ....................................................................................................................... M-10Performance Tuning ...................................................................................................................... M-10Personal Firewalls .......................................................................................................................... M-10

Deploying to z OS ................................................................................................................................ M-10EBCDIC............................................................................................................................................ M-10Multicast .......................................................................................................................................... M-10

N Best Practices for Coherence ExtendRun Proxy Servers with Local Storage Disabled .............................................................................. N-1Do Not Run a Near Cache on a Proxy Server..................................................................................... N-2Configure Heap NIO Space to be Equal to the Max Heap Size ..................................................... N-2Set Worker Thread Pool Sizes According to the Needs of the Application................................. N-2Be Careful When Making InvocationService Calls .......................................................................... N-3Be Careful When Placing Collection Classes in the Cache ............................................................. N-3Run Multiple Proxies Instead of Increasing Thread Pool Size ...................................................... N-4Configure POF Serializers for Cache Servers .................................................................................... N-4Use Node Locking Instead of Thread Locking .................................................................................. N-5

O Scaling Out Your Data Grid Aggregations LinearlyThe Data .................................................................................................................................................... O-1Configure a Partitioned Cache.............................................................................................................. O-3Add an Index to the Price Property ...................................................................................................... O-4Code to perform a Parallel Aggregation ............................................................................................. O-4The Testing Environment and Process ................................................................................................ O-4

Performing a "Test Run"................................................................................................................... O-4This "Test Suite" (and Subsequent Results) Includes Data from Four "Test Runs": ................ O-5

xv

JDK Version........................................................................................................................................ O-5The Results ............................................................................................................................................... O-5Conclusion ................................................................................................................................................ O-7

P The PIF-POF Binary FormatStream Format .......................................................................................................................................... P-1

Integer Values .................................................................................................................................... P-2Type Identifiers ................................................................................................................................. P-3

Binary Formats for Predefined Types.................................................................................................. P-5Int......................................................................................................................................................... P-5

Coercion of Integer Types......................................................................................................... P-6Decimal ............................................................................................................................................... P-7Floating Point..................................................................................................................................... P-7Boolean ............................................................................................................................................... P-8Octet .................................................................................................................................................... P-8Octet String......................................................................................................................................... P-9Char ..................................................................................................................................................... P-9Char String ....................................................................................................................................... P-10Date ................................................................................................................................................... P-10Year-Month Interval ....................................................................................................................... P-11Time................................................................................................................................................... P-11Time Interval.................................................................................................................................... P-11Date-Time......................................................................................................................................... P-11

Coercion of Date and Time Types ......................................................................................... P-11Day-Time Interval ........................................................................................................................... P-11Collections ........................................................................................................................................ P-11Arrays ............................................................................................................................................... P-12Sparse Arrays................................................................................................................................... P-13Key-Value Maps (Dictionaries) ..................................................................................................... P-13Identity.............................................................................................................................................. P-14Reference .......................................................................................................................................... P-15

Binary Format for User Types ............................................................................................................. P-15Versioning of User Types............................................................................................................... P-16

Q Log Message GlossaryTCMP Log Messages .............................................................................................................................. Q-1Configuration Log Messages ................................................................................................................ Q-6Partitioned Cache Service Log Messages............................................................................................ Q-8

xvi

List of Figures11 Interacting with the Cache through a Browser....................................................................... 1-912 Running SimpleCacheExplorer.jsp with a Distributed Cache .......................................... 1-1213 Running SimpleCacheExplorer.jsp with an Eviction Policy ............................................. 1-15141 Coherence Throughput versus Number of Machines ........................................................ 14-2142 Coherence Latency versus Number of Machines................................................................ 14-3211 Viewing the HttpAdapter Web Application in a Browser ................................................ 21-4212 Using the JConsole Utility to Display and Manipulate Coherence MBeans................... 21-5221 Reporter Attributes in JConsole............................................................................................. 22-2222 Reporter Operations in JConsole ........................................................................................... 22-3261 Reporter Operations in JConsole ........................................................................................... 26-1271 MBean Query Displayed in the JConsole ............................................................................. 27-3281 JMX Query Run in JConsole................................................................................................... 28-2O1 Average Aggregation Time ...................................................................................................... O-6O2 Aggregation Scale-Out .............................................................................................................. O-7

xvii

Preface

Oracle Coherence is a JCache-compliant in-memory caching and data management solution for clustered J2EE applications and application servers. Coherence makes sharing and managing data in a cluster as simple as on a single server. It accomplishes this by coordinating updates to the data using clusterwide concurrency control, replicating and distributing data modifications across the cluster using the highest performing clustered protocol available, and delivering notifications of data modifications to any servers that request them. Developers can easily take advantage of Coherence features using the standard Java collections API to access and modify data, and use the standard JavaBean event model to receive data change notifications. Functionality such as HTTP Session Management is available out-of-the-box for applications deployed to WebLogic, WebSphere, Tomcat, Jetty and other Servlet 2.2, 2.3 and 2.3 compliant application servers.

AudienceThis document is targeted at software developers and architects. It provides detailed technical information on creating and using the Coherence cache and for writing and deploying Java applications that interact with it.

Documentation AccessibilityOur goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.

Accessibility of Code Examples in DocumentationScreen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

xviii

Accessibility of Links to External Web Sites in DocumentationThis documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Deaf/Hard of Hearing Access to Oracle Support ServicesTo reach Oracle Support Services, use a telecommunications relay service (TRS) to call Oracle Support at 1.800.223.1711. An Oracle Support Services engineer will handle technical issues and provide customer support according to the Oracle service request process. Information about TRS is available at http://www.fcc.gov/cgb/consumerfacts/trs.html, and a list of phone numbers is available at http://www.fcc.gov/cgb/dro/trsphonebk.html.

Related DocumentsFor more information, see the following documents that are included in the Oracle Coherence documentation set:

Oracle Coherence Client Guide

Oracle Coherence Getting Started Guide

Oracle Coherence Integration Guide for Oracle Coherence

Oracle Coherence Java API Reference

Oracle Coherence Tutorial for Oracle Coherence

Oracle Coherence User's Guide for Oracle Coherence*Web

ConventionsThe following text conventions are used in this document:

Convention Meaningboldface Boldface type indicates graphical user interface elements associated

with an action, or terms defined in text or the glossary.

italic Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

Part IPart I Coherence Features

This section contains the following chapters:

Chapter 1, "Create and Use Coherence Caches"

Chapter 2, "Implement Transactions, Locks, and Concurrency"

Chapter 3, "Perform Continuous Query"

Chapter 4, "Managing Map Operations with Triggers"

Chapter 5, "Data Affinity"

Chapter 6, "Query the Cache"

Chapter 7, "Security Framework"

Chapter 8, "Network Filters"

Chapter 9, "Priority Tasks"

Chapter 10, "Specifying a Custom Eviction Policy"

Chapter 11, "Serialization Paged Cache"

Chapter 12, "Pre-Loading the Cache"

Chapter 13, "Constraints on Re-entrant Calls"

1Create and Use Coherence Caches 1-1

1Create and Use Coherence Caches

The simplest and most flexible way to create caches in Coherence is to use the cache configuration descriptor to define attributes and names for your application's or cluster's caches, and to instantiate the caches in your application code referring to them by name that matches the names or patterns as defined in the descriptor.

This approach to configuring and using Coherence caches has several very important benefits. It separates the cache initialization and access logic for the cache in your application from its attributes and characteristics. This way your code is written in a way that is independent of the cache type that will be used in your application deployment and changing the characteristics of each cache (such as Rich Text cache type, cache eviction policy, and cache type-specific attributes, and so on) can be done without making any changes to the code whatsoever. It enables you to create multiple configurations for the same set of named caches and to instruct your application to use the appropriate configuration at deployment time by specifying the descriptor to use in the java command line when the node JVM is started.

Creating a Cache in Your ApplicationTo instantiate a cache in your application code, you need to:

1. Make sure that coherence.jar is in your classpath.2. Use CacheFactory.getCache() to access the cache in your code.Your code will look similar to the following:

import com.tangosol.net.CacheFactory;import com.tangosol.net.NamedCache;

...

NamedCache cache = CacheFactory.getCache("VirtualCache");

Now you can retrieve and store objects in the cache, using the NamedCache API, which extends the standard java.util.Map interface, adding several additional capabilities that provide concurrency control (ConcurrentMap interface), ability to listen for cache changes (ObservableMap interface) and ability to query the cache (QueryMap interface).

Example 11 illustrates typical cache operations in a Java program.

Example 11 Typical Cache Operations in a Java Program...

// simple retrieve and update cycleString key = "key";

Configuring the Caches

1-2 Oracle Coherence Developer's Guide

// retrieve the objectMyValue value = (MyValue) cache.get(key);

// Use and modify the object// ...

// put the new value backcache.put(key, value);...

Configuring the CachesThe cache attributes and settings are defined in the cache configuration descriptor. Cache attributes determine the cache type (what means and resources the cache will use for storing, distributing and synchronizing the cached data) and cache policies (what happens to the objects in the cache based on cache size, object longevity and other parameters).

The structure of the cache configuration descriptor (described in detail by the cache-config.dtd included in the coherence.jar) consists of two primary sections: caching-schemes section and caching-scheme-mapping section.

The caching-schemes section is where the attributes of a cache or a set of caches get defined. The caching schemes can be of several types, each with its own set of attributes. The caching schemes can be defined completely from scratch, or can incorporate attributes of other existing caching schemes, referring to them by their scheme-names (using a scheme-ref element) and optionally overriding some of their attributes to create new caching schemes. This flexibility enables you to create caching scheme structures that are easy to maintain, foster reuse and are very flexible.

The caching-scheme-mapping section is where the specific cache name or a naming pattern is attached to the cache scheme that defines the cache configuration to use for the cache that matches the name or the naming pattern. So if we would like to define the cache descriptor for the cache we mentioned in the previous section (VirtualCache), it may look something like the following:

Example 12 Sample Cache Configuration File

* default-replicated

default-replicated

Configuring the Caches

Create and Use Coherence Caches 1-3

ReplicatedCache default-backing-map

default-backing-map com.tangosol.util.SafeHashMap

The above cache configuration descriptor specifies that all caches will be created (including our VirtualCache cache) using the default-replicated caching scheme. It defines the default-replicated caching scheme as a replicated-scheme, using a service named ReplicatedCache and using the backing map named default-backing-map, which is defined as a class com.tangosol.util.SafeHashMap (the default backing map storage that Coherence uses when no eviction policies are required).

Then, at a later point, let's say we decide that, since the number of entries that our cache is holding is too large and updates to the objects too frequent to use a replicated cache, we want our VirtualCache cache to become a distributed cache instead (while keeping all other caches replicated). To accommodate these new circumstances, we can change the cache configuration by adding the following cache-scheme definition for the distributed cache to the caching-schemes section:

Example 13 cache-scheme Definition for a Distributed Cache

default-distributed DistributedCache default-backing-map

Then mapping the VirtualCache cache to it in the caching-schemes-mapping section:

Example 14 Mapping to a Distributed Cache

VirtualCache default-distributed

The resulting cache definition descriptor will look similar to Example 15:

Configuring the Caches

1-4 Oracle Coherence Developer's Guide

Example 15 Configuration for a Distributed Cache

* default-replicated VirtualCache default-distributed

default-replicated ReplicatedCache

default-backing-map

default-distributed DistributedCache

default-backing-map

default-backing-map

com.tangosol.util.SafeHashMap

Setting Up Your Test Environment

Create and Use Coherence Caches 1-5

When we revise and deploy the descriptor and restart the cluster, the VirtualCache cache will be a distributed cache instead of replicated, all without any changes to the code we wrote.

Cache Configuration Descriptor LocationA few words about how to instruct Coherence where to find the cache configuration descriptor. Without specifying anything in the Java command line, Coherence will attempt to use the cache configuration descriptor named coherence-cache-config.xml that it finds in the classpath. Since Coherence ships with this file packaged into the coherence.jar, unless you place anoth