1/68

Contents

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documents
• Conventions

Part I Getting Started

1 Introduction

• Basic Concepts
  • Clustered Data Management
  • A single API for the logical layer, XML configuration for the physical layer
  • Caching Strategies
  • Data Storage Options
  • Serialization Options
  • Configurability and Extensibility
  • Namespace Hierarchy
• Read/Write Caching
  • NamedCache
  • Requirements for Cached Objects
  • NamedCache Usage Patterns
• Querying the Cache
• Transactions
• HTTP Session Management
• Invocation Service
• Events
• Object-Relational Mapping Integration
• C++/.NET Integration
• Management and Monitoring

2 Installing Oracle Coherence for Java

• System Requirements
• Extracting the Distribution
• Setting Environment Variables
• Running Coherence for the First Time
  • Create a Basic Cluster
  • Create a Cache

3 Understanding Configuration

• Overview of the Default Configuration Files
• Specifying an Operational Configuration File
  • Using the Default Operational Override File
  • Specifying an Operational Override File
  • Defining Override Files for Specific Operational Elements
  • Viewing Which Operational Override Files are Loaded
• Specifying a Cache Configuration File
  • Using a Default Cache Configuration File
  • Overriding the Default Cache Configuration File
  • Using the Cache Configuration File System Property
  • Viewing Which Cache Configuration File is Loaded
• Specifying a POF Configuration File
  • Using the POF Configuration File System Property
  • Combining Multiple POF Configuration Files
  • Viewing Which POF Configuration Files are Loaded
• Specifying Management Configuration Files
  • Specifying a Custom Report Group Configuration File
    • Overriding the Default Report Group Configuration File
    • Using the Report Group Configuration File System Property
  • Specifying an MBean Configuration File
    • Using the Default MBean Configuration Override File
    • Using the MBean Configuration File System Property
  • Viewing Which Management Configuration Files are Loaded
• Understanding the XML Override Feature
  • Using the Predefined Override Files
  • Defining Custom Override Files
  • Defining Multiple Override Files for the Same Element
• Changing Configuration Using System Properties
  • Using Preconfigured System Properties
  • Creating Custom System Properties

4 Building Your First Coherence Application

• Step 1: Define the Example Cache
• Step 2: Configure and Start the Example Cluster
• Step 3: Create an Run a Basic Coherence Standalone Application
  • Create the Sample Standalone Application
  • Run the Sample Standalone Application
  • Verify the Example Cache
• Step 4: Create and Run a Basic Coherence JavaEE Web Application
  • Create the Sample Web Application
  • Deploy and Run the Sample Web Application
  • Verify the Example Cache
• Using JDeveloper for Coherence Development
  • Running Coherence in JDeveloper
  • Viewing Thread Dumps in JDeveloper
  • Creating Configuration Files in JDeveloper

Part II Using Data Clusters

5 Cluster Services Overview

6 Understanding TCMP

• Overview
• Protocol Reliability
• Protocol Resource Utilization
• Protocol Tunability
• Multicast Scope
• Disabling Multicast

7 Setting Single Server Mode

• Setting Single Server Mode in the Operation Configuration Descriptor
• Setting Single Server Mode on the Command Line

8 Dynamically Managing Cluster Membership

• Cluster and Service Objects
• Member object
• Listening to Member Events

9 Using Network Filters

• Compression Filters
• Encryption Filters
  • Symmetric Encryption Filter
    • Symmetric Encryption Filter Parameters
  • PKCS Encryption Filter
    • PKCS Encryption Filter Parameters
• Configuring Filters
• Creating a Custom Filter

Part III Using Caches

10 Introduction to Caches

• Distributed Cache
• Replicated Cache
• Optimistic Cache
• Near Cache
• Local Cache
• Remote Cache
• Summary of Cache Types

11 Configuring Caches

• Overview
• Defining Cache Mappings
  • Using One-to-One Cache Mappings
  • Using Cache Name Pattern Mappings
  • Specifying Initialization Parameters in a Mapping
• Defining Cache Schemes
  • Defining Distributed Cache Schemes
  • Defining Replicated Cache Schemes
  • Defining Optimistic Cache Schemes
  • Defining Local Cache Schemes
    • Controlling the Growth of a Local Cache
  • Defining Near Cache Schemes
    • Near Cache Invalidation Strategies
• Using Scheme Inheritance
• Using Cache Scheme Properties
• Using Parameter Macros

12 Implementing Storage and Backing Maps

• Cache Layers
• Local Storage
• Operations
• Capacity Planning
• Partitioned Backing Maps

13 Read-Through, Write-Through, Write-Behind, and Refresh-Ahead Caching

• Pluggable Cache Store
• Read-Through Caching
• Write-Through Caching
• Write-Behind Caching
• Write-Behind Requirements
• Refresh-Ahead Caching
• Selecting a Cache Strategy
  • Read-Through/Write-Through versus Cache-Aside
  • Refresh-Ahead versus Read-Through
  • Write-Behind versus Write-Through
• Creating a CacheStore Implementation
• Plugging in a CacheStore Implementation
• Sample CacheStore
• Sample Controllable CacheStore
• Implementation Considerations
  • Idempotency
  • Write-Through Limitations
  • Cache Queries
  • Re-entrant Calls
  • Cache Server Classpath
  • CacheStore Collection Operations
  • Connection Pools

14 Serialization Paged Cache

• Understanding Serialization Paged Cache
• Configuring Serialization Paged Cache
• Optimizing a Partitioned Cache Service
• Configuring for High Availability
• Configuring Load Balancing and Failover
• Supporting Huge Caches

15 Cache Configurations by Example

• Local Caches (accessible from a single JVM)
  • In-memory Cache
  • NIO In-memory Cache
  • Size Limited In-memory Cache
  • In-memory Cache with Expiring Entries
  • Cache on Disk
  • Size Limited Cache on Disk
  • Persistent Cache on Disk
  • In-memory Cache with Disk Based Overflow
  • Cache of a Database
• Clustered Caches (accessible from multiple JVMs)
  • Replicated Cache
  • Replicated Cache with Overflow
  • Partitioned Cache
  • Partitioned Cache with Overflow
  • Partitioned Cache of a Database
  • Partitioned Cache with a Serializer
  • Local Cache of a Partitioned Cache (Near cache)

Part IV Using the Programming API

16 Serializing Objects

17 Using Portable Object Format

• Overview
• Working with POF
  • Implementing the PortableObject interface
  • Implementing the PofSerializer interface:
  • Assigning POF indexes
  • Using the ConfigurablePofContext Class
  • Configuring Coherence to Use the ConfigurablePofContext Class
    • Configure the ConfigurablePofContext Class Per Service
    • Configure the ConfigurablePofContext Class for All Services
    • Configure the ConfigurablePofContext Class For the JVM
• Using POF Extractors and POF Updaters
  • Navigating a POF object
  • Using PofExtractors
  • Using PofUpdaters

18 Pre-Loading the Cache

• Performing Bulk Loading and Processing
  • Bulk Writing to a Cache
  • Efficient processing of filter results
  • A Bulk Loading and Processing Example
• Performing Distributed Bulk Loading
  • A Distributed Bulk Loading Example

19 Using Cache Events

• Listener Interface and Event Object
• Caches and Classes that Support Events
• Signing Up for All Events
• Using an Inner Class as a MapListener
• Configuring a MapListener for a Cache
• Signing up for Events on specific identities
• Filtering Events
• "Lite" Events
• Advanced: Listening to Queries
  • Filtering Events Versus Filtering Cached Data
• Advanced: Synthetic Events
• Advanced: Backing Map Events
  • Producing Readable Backing MapListener Events from Distributed Caches
• Advanced: Synchronous Event Listeners

20 Querying Data In a Cache

• Query Overview
  • Query Concepts
• Performing Simple Queries
• Using Query Indexes
  • Creating an Index
  • Creating User-Defined Indexes
    • Implementing the MapIndex Interface
    • Implementing the IndexAwareExtractor Interface
    • Using a Conditional Index
• Batching Queries and Memory Usage
• Queries Involving Multi-Value Attributes
• ChainedExtractor

21 Using Continuous Query Caching

• Uses of Continuous Query Caching
• The Coherence Continuous Query Cache
• Constructing a Continuous Query Cache
  • Cleaning up the resources associated with a ContinuousQueryCache
• Caching only keys, or caching both keys and values
  • CacheValues Property and Event Listeners
• Listening to the ContinuousQueryCache
  • Achieving a Stable Materialized View
  • Support for Synchronous and Asynchronous Listeners
• Making the ContinuousQueryCache Read-Only

22 Processing Data In a Cache

• Targeted Execution
• Parallel Execution
• Query-Based Execution
• Data-Grid-Wide Execution
• Agents for Targeted, Parallel and Query-Based Execution
• Data Grid Aggregation
• Node-Based Execution
• Work Manager
  • Oracle Coherence Work Manager: Feedback from a Major Financial Institution

23 Managing Map Operations with Triggers

• A Map Trigger Example

24 Using Coherence Query Language

• Understanding Coherence Query Language Syntax
  • Query Syntax Basics
    • Using Path-Expressions
    • Using Bind Variables
    • Using Key and Value Pseudo-Functions
    • Using Aliases
    • Using Quotes with Literal Arguments
  • Retrieving Data
    • Retrieving Data from the Cache
    • Filtering Entries in a Result Set
  • Managing the Cache Lifecycle
    • Creating a Cache
    • Writing a Serialized Representation of a Cache to a File
    • Loading Cache Contents from a File
    • Removing a Cache from the Cluster
  • Working with Cache Data
    • Aggregating Query Results
    • Changing Existing Values
    • Inserting Entries in the Cache
    • Deleting Entries in the Cache
  • Working with Indexes
    • Creating an Index on the Cache
    • Removing an Index from the Cache
  • Issuing Multiple Query Statements
    • Processing Query Statements in Batch Mode
• Using the CohQL Command-Line Tool
  • Starting the Command-line Tool
  • Using Command-Line Tool Arguments
  • A Command-Line Example
• Building Filters in Java Programs
• Additional Coherence Query Language Examples
  • Simple SELECT * FROM Statements that Highlight Filters
  • Complex Queries that Feature Projection, Aggregation, and Grouping
  • UPDATE Examples
  • Key and Value Pseudo-Function Examples

25 Performing Transactions

• Overview of Transactions
• Using Explicit Locking for Data Concurrency
• Using Entry Processors for Data Concurrency
• Using the Transaction Framework API
  • Defining Transactional Caches
  • Performing Cache Operations within a Transaction
    • Using the NamedCache API
    • Using the Connection API
  • Creating Transactional Connections
  • Using Transactional Connections
    • Using Auto-Commit Mode
    • Setting Isolation Levels
    • Using Eager Mode
    • Setting Transaction Timeout
  • Using the OptimisticNamedCache Interface
  • Configuring POF When Performing Transactions
  • Configuring Transactional Storage Capacity
  • Performing Transactions from Java Extend Clients
    • Create an Entry Processor for Transactions
    • Configure the Cluster-Side Transaction Caches
    • Configure the Client-Side Remote Cache
    • Use the Transactional Entry Processor from a Java Client
  • Viewing Transaction Management Information
    • CacheMBeans for Transactional Caches
    • TransactionManagerBean
• Using the Coherence Resource Adapter
  • Performing Cache Operations within a Transaction
    • Creating a Coherence Connection
    • Getting a Named Cache
    • Demarcating Transaction Boundaries
  • Packaging the Application
    • Configure the Connection Factory Resource Reference
    • Configure the Resource Adapter Module Reference
    • Include the Required Libraries
  • Using the Coherence Cache Adapter for Transactions

26 Data Affinity

• Specifying Affinity
• Specifying Data Affinity with a KeyAssociation
• Specifying Data Affinity with a KeyAssociator
• Example of Using Affinity

27 Priority Tasks

• Priority Tasks — Timeouts
  • Configuring Execution Timeouts
  • Command Line Options
• Priority Task Execution — Custom Objects
  • APIs for Creating Priority Task Objects
  • Errors Thrown by Task Timeouts

28 Specifying a Custom Eviction Policy

29 Constraints on Re-entrant Calls

• Re-entrancy, Services, and Service Threads
  • Parent-Child Object Relationships
  • Avoiding Deadlock
• Re-entrancy and Listeners

30 Securing Coherence

• Using the Access Controller
  • Overview of the Access Controller
  • Proof of Identity
  • Proof of Trustworthiness
  • Enabling the Default Access Controller Implementation
• Working in Applications with Installed Security Manager
• Using SSL in Coherence
  • Overview of SSL
  • Configuring SSL for TCMP
    • Defining a SSL Socket Provider
    • Using the Pre-Defined SSL Socket Provider

Part V Deploying Coherence Applications

31 Deploying Coherence

• Deploying Coherence with a Standalone Application
• Deploying Coherence to an Application Server
  • Deploying Coherence as an Application Server Library
  • Deploying Coherence in a Java EE Module
    • Deploying Coherence Within an EAR
    • Deploying Coherence Within a WAR

32 Platform-Specific Deployment Considerations

• Deploying to AIX
  • Socket Buffers sizes and JVMs
  • Multicast and IPv6
  • Unique Multicast Addresses and Ports
• Deploying to Oracle JRockit JVMs
  • JRockit and the Native Posix Thread Library (NPTL)
  • OutOfMemoryError
• Deploying to Cisco Switches
  • Buffer Space and Packet Pauses
  • Multicast Connectivity on Large Networks
  • Multicast Outages
• Deploying to Foundry Switches
  • Multicast Connectivity
• Deploying to IBM BladeCenters
  • MAC Address Uniformity and Load Balancing
• Deploying to IBM JVMs
  • UDP Socket Buffer Sizes
  • OutOfMemoryError
  • Heap Sizing
• Deploying to Linux
  • Native POSIX Thread Library (NPTL)
  • TSC High Resolution Timesource
• Deploying to OS X
  • Multicast and IPv6
  • Unique Multicast Addresses and Ports
  • Socket Buffer Sizing
• Deploying to Solaris
  • Solaris 10 (x86 and SPARC)
  • Solaris 10 Networking
• Deploying to Sun JVMs
  • Heap Sizes
  • AtomicLong
  • OutOfMemoryError
• Deploying to Virtual Machines
  • Supported Deployment
  • Multicast Connectivity
  • Performance
  • Fault Tolerance
• Deploying to Windows
  • Performance Tuning
  • Personal Firewalls
  • Disconnected Network Interface
• Deploying to z OS
  • EBCDIC
  • Multicast

33 Production Checklist

• Network
• Hardware
• Operating System
• JVM
• Java Security Manager
• Application Instrumentation
• Coherence Editions and Modes
  • Ensuring that RTC nodes don't use Coherence TCMP
• Coherence Operational Configuration
• Coherence Cache Configuration
• Large Cluster Configuration
• Death Detection
• tangosol-license.xml Deprecated

Part VI Managing Coherence

34 How to Manage Coherence Using JMX

• Configuring the Coherence Management Framework
  • Enabling JMX Management
  • Filtering MBeans
  • Configuring Management Refresh
    • Setting the Management Refresh Expiry
    • Setting the Management Refresh Policy
    • Setting the Management Refresh Timeout
• Accessing Coherence MBeans
  • Viewing MBeans Using the JConsole Utility
  • Viewing MBeans Using the HTML Adapter Application
• Using Coherence MBeanConnector to Access MBeans

35 JMX Reporter

• Basic Configuration
• Administration
• Data Analysis
• Advanced Configuration
  • Creating Custom Reports
  • Running Reporter in a Distributed Configuration

36 How to Create a Custom Report

• Configuring a Report File
  • file-name Element
    • file-name Macros
    • file-name Macro Examples
• Specifying Data Columns
  • How to Include an Attribute
  • How to Include Part of the Key
  • How to Include Information from Composite Attributes
  • How to Include Information from Multiple MBeans
  • Including Multiple MBean Information Example
  • How to Use Report Macros
  • How to Include Constant Values
• Including Queries in a Report
• Using Filters to Construct Reports
• Using Functions to Construct a Report
  • Function Examples
• Using Aggregates to Construct a Report
  • Aggregate Examples
• Constructing Delta Functions
  • Delta Function Examples

37 How to Modify Report Batch

• Report Batch Deployment Descriptor
  • Document Location
  • Document Root
  • System Properties
  • Document Format
• Report Batch Element Index
  • frequency
  • location
  • init-param
  • init-params
  • output-directory
  • param-name
  • param-type
  • param-value
  • report-config
  • report-group
  • report-list

38 Analyzing Reporter Content

• Network Health Report
• Network Health Detail Report
• Memory Status Report
• Cache Size Report
• Cache Usage Report
• Service Report
• Node List Report
• Proxy Report

39 How to Run a Report on Demand

• How to Run ReportControl MBean at Node Startup
• How to Configure the ReportControl MBean

40 Configuring Custom MBeans

• Creating an MBean XML Configuration File
  • Configuring Standard MBeans
  • Configuring MXBeans
  • Configuring JMX MBeans
• Enabling a Custom MBean Configuration File
  • Setting a System Property
  • Adding a Custom MBean Configuration File to the Class Path

41 How to Manage Custom MBeans Within the Cluster

• Custom MBean Configuration
  • How to Add a Standard MBean to Coherence
  • How to Programmatically Add a Standard MBean to Coherence
    • Using Static MBean Names
  • How to Add a the Results of a JMX Query to Coherence

Part VII Tuning Coherence

42 Evaluating Performance and Scalability

• Measuring Latency and Throughput
• Demonstrating Scalability
• Tuning Your Environment
• Measurements on a Large Cluster

43 Performing a Multicast Connectivity Test

• Running the Multicast Test Utility
  • Sample Commands
• Multicast Test Example
• Troubleshooting Multicast Communications

44 Performing a Datagram Test for Network Performance

• Running the Datagram Test Utility
  • Sample Commands for a Listener and a Publisher
• Datagram Test Example
• Reporting
  • Publisher Statistics
  • Listener Statistics
    • Throttling
    • Bidirectional Testing
    • Distributed Testing

45 Performance Tuning

• Operating System Tuning
  • Socket Buffer Sizes
  • High Resolution timesource (Linux)
  • Datagram size (Microsoft Windows)
  • Thread Scheduling (Microsoft Windows)
  • Swapping
• Network Tuning
  • Network Interface Settings
  • Bus Considerations
  • Network Infrastructure Settings
  • Ethernet Flow-Control
  • Path MTU
• JVM Tuning
  • Basic Sizing Recommendation
  • Heap Size Considerations
    • General Guidelines
    • Moving the Cache Out of the Application Heap
  • GC Monitoring & Tuning
• Coherence Network Tuning
  • Validation
• Data Access Patterns
  • Data Access Distribution (hot spots)
  • Cluster-node Affinity
  • Read/Write Ratio and Data Sizes
  • Interleaving Cache Reads and Writes

46 Using the Service Guardian

• Overview
• Configuring the Service Guardian
  • Setting the Guardian Timeout
    • Setting the Guardian Timeout for All Threads
    • Setting the Guardian Timeout Per Service Type
    • Setting the Guardian Timeout Per Service Instance
  • Using the Timeout Value From the PriorityTask API
  • Setting the Guardian Service Failure Policy
    • Setting the Guardian Failure Policy for All Threads
    • Setting the Guardian Failure Policy Per Service Type
    • Setting the Guardian Failure Policy Per Service Instance
    • Enabling a Custom Guardian Failure Policy
• Issuing Manual Guardian Heartbeats

47 Using Quorum

• Overview
• Using the Cluster Quorum
  • Configuring the Cluster Quorum Policy
• Using the Partitioned Cache Quorums
  • Configuring the Partitioned Cache Quorum Policy
• Using the Proxy Quorum
  • Configuring the Proxy Quorum Policy
• Enabling Custom Action Policies

48 Scaling Out Your Data Grid Aggregations Linearly

• The Data
• Configure a Partitioned Cache
• Add an Index to the Price Property
• Code to perform a Parallel Aggregation
• The Testing Environment and Process
  • Performing a "Test Run"
  • This "Test Suite" (and Subsequent Results) Includes Data from Four "Test Runs":
  • JDK Version
• The Results
• Conclusion

A Operational Configuration Elements

• Operational Configuration Deployment Descriptors
  • Document Location
  • Document Root
  • Document Format
  • Operational Override File (tangosol-coherence-override.xml)
  • Command Line Override
• Element Index
  • access-controller
  • address-provider
  • authorized-hosts
  • cache-factory-builder-config
  • callback-handler
  • cluster-config
  • cluster-quorum-policy
  • coherence
  • configurable-cache-factory-config
  • filters
    • Compression Filter Parameters
  • flow-control
  • host-range
  • identity-asserter
  • identity-manager
  • identity-transformer
  • incoming-message-handler
  • init-param
  • init-params
  • instance
  • key-store
  • license-config
  • logging-config
  • management-config
  • mbean
  • mbeans
  • mbean-filter
  • member-identity
  • message-pool
  • multicast-listener
  • notification-queueing
  • outgoing-message-handler
  • outstanding-packets
  • packet-buffer
  • packet-bundling
  • packet-delivery
  • packet-pool
  • packet-publisher
  • packet-size
  • packet-speaker
  • pause-detection
  • provider
  • reporter
  • security-config
  • serializers
  • service-guardian
  • services
    • Initialization Parameter Settings
  • shutdown-listener
  • socket-address
  • socket-provider
  • socket-providers
  • ssl
  • tcp-ring-listener
  • traffic-jam
  • trust-manager
  • unicast-listener
  • volume-threshold
  • well-known-addresses
• Element Attributes

B Cache Configuration Elements

• Cache Configuration Deployment Descriptor
• Element Reference
  • acceptor-config
  • address-provider
  • async-store-manager
  • authorized-hosts
  • backing-map-scheme
  • backup-storage
  • bdb-store-manager
  • bundle-config
  • cache-config
  • cache-mapping
  • cache-service-proxy
  • cachestore-scheme
  • caching-scheme-mapping
  • caching-schemes
  • class-scheme
  • custom-store-manager
  • defaults
  • disk-scheme
  • distributed-scheme
  • external-scheme
  • identity-manager
  • initiator-config
  • init-param
  • init-params
  • instance
  • invocation-scheme
  • invocation-service-proxy
  • jms-acceptor
  • jms-initiator
  • key-associator
  • key-partitioning
  • key-store
  • lh-file-manager
  • listener
  • local-address
  • local-scheme
  • near-scheme
  • nio-file-manager
  • nio-memory-manager
  • operation-bundling
  • optimistic-scheme
  • outgoing-message-handler
  • overflow-scheme
  • paged-external-scheme
  • partition-listener
  • partitioned
  • partitioned-quorum-policy-scheme
  • provider
  • proxy-config
  • proxy-scheme
  • proxy-quorum-policy-scheme
  • read-write-backing-map-scheme
  • remote-addresses
  • remote-cache-scheme
  • remote-invocation-scheme
  • replicated-scheme
  • serializer
  • socket-address
  • socket-provider
  • ssl
  • tcp-acceptor
  • tcp-initiator
  • transactional-scheme
  • trust-manager
  • version-persistent-scheme
  • version-transient-scheme
  • versioned-backing-map-scheme
  • versioned-near-scheme

C Command Line Overrides

• Override Example
• Preconfigured Override Values

D POF User Type Configuration Elements

• POF User Type Deployment Descriptor
  • Document Location
  • Document Root
  • Document Format
  • Command Line Override
• Element Index
  • allow-interfaces
  • allow-subclasses
  • class-name
  • default-serializer
  • include
  • init-param
  • init-params
  • param-type
  • param-value
  • pof-config
  • serializer
  • type-id
  • user-type
  • user-type-list

E Coherence MBeans Reference

• Overview
• MBean Index
• CacheMBean
• ClusterMBean
• ClusterNodeMBean
• ConnectionManagerMBean
• ConnectionMBean
• ManagementMBean
• PointToPointMBean
• ReporterMBean
• ServiceMBean
• StorageManagerMBean
• TransactionManagerMBean

F The PIF-POF Binary Format

• Stream Format
  • Integer Values
  • Type Identifiers
• Binary Formats for Predefined Types
  • Int
    • Coercion of Integer Types
  • Decimal
  • Floating Point
  • Boolean
  • Octet
  • Octet String
  • Char
  • Char String
  • Date
  • Year-Month Interval
  • Time
  • Time Interval
  • Date-Time
    • Coercion of Date and Time Types
  • Day-Time Interval
  • Collections
  • Arrays
  • Sparse Arrays
  • Key-Value Maps (Dictionaries)
  • Identity
  • Reference
• Binary Format for User Types
  • Versioning of User Types

G Log Message Glossary

• TCMP Log Messages
• Configuration Log Messages
• Partitioned Cache Service Log Messages