Skip Headers
Oracle® Coherence Developer's Guide
Release 3.7
Part Number E18677-01
Home
Book List
Contact Us
Next
View PDF
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
1.1
Basic Concepts
1.1.1
Clustered Data Management
1.1.2
A single API for the logical layer, XML configuration for the physical layer
1.1.3
Caching Strategies
1.1.4
Data Storage Options
1.1.5
Serialization Options
1.1.6
Configurability and Extensibility
1.1.7
Namespace Hierarchy
1.2
Read/Write Caching
1.2.1
NamedCache
1.2.2
Requirements for Cached Objects
1.2.3
NamedCache Usage Patterns
1.3
Querying the Cache
1.4
Transactions
1.5
HTTP Session Management
1.6
Invocation Service
1.7
Events
1.8
Object-Relational Mapping Integration
1.9
C++/.NET Integration
1.10
Management and Monitoring
2
Installing Oracle Coherence for Java
2.1
System Requirements
2.2
Extracting the Distribution
2.3
Setting Environment Variables
2.4
Running Coherence for the First Time
2.4.1
Create a Basic Cluster
2.4.2
Create a Cache
3
Understanding Configuration
3.1
Overview of the Default Configuration Files
3.2
Specifying an Operational Configuration File
3.2.1
Using the Default Operational Override File
3.2.2
Specifying an Operational Override File
3.2.3
Defining Override Files for Specific Operational Elements
3.2.4
Viewing Which Operational Override Files are Loaded
3.3
Specifying a Cache Configuration File
3.3.1
Using a Default Cache Configuration File
3.3.2
Overriding the Default Cache Configuration File
3.3.3
Using the Cache Configuration File System Property
3.3.4
Viewing Which Cache Configuration File is Loaded
3.4
Specifying a POF Configuration File
3.4.1
Using the POF Configuration File System Property
3.4.2
Combining Multiple POF Configuration Files
3.4.3
Viewing Which POF Configuration Files are Loaded
3.5
Specifying Management Configuration Files
3.5.1
Specifying a Custom Report Group Configuration File
3.5.1.1
Overriding the Default Report Group Configuration File
3.5.1.2
Using the Report Group Configuration File System Property
3.5.2
Specifying an MBean Configuration File
3.5.2.1
Using the Default MBean Configuration Override File
3.5.2.2
Using the MBean Configuration File System Property
3.5.3
Viewing Which Management Configuration Files are Loaded
3.6
Disabling Schema Validation
3.7
Understanding the XML Override Feature
3.7.1
Using the Predefined Override Files
3.7.2
Defining Custom Override Files
3.7.3
Defining Multiple Override Files for the Same Element
3.8
Changing Configuration Using System Properties
3.8.1
Using Preconfigured System Properties
3.8.2
Creating Custom System Properties
4
Building Your First Coherence Application
4.1
Step 1: Define the Example Cache
4.2
Step 2: Configure and Start the Example Cluster
4.3
Step 3: Create an Run a Basic Coherence Standalone Application
4.3.1
Create the Sample Standalone Application
4.3.2
Run the Sample Standalone Application
4.3.3
Verify the Example Cache
4.4
Step 4: Create and Run a Basic Coherence JavaEE Web Application
4.4.1
Create the Sample Web Application
4.4.2
Deploy and Run the Sample Web Application
4.4.3
Verify the Example Cache
4.5
Using JDeveloper for Coherence Development
4.5.1
Running Coherence in JDeveloper
4.5.2
Viewing Thread Dumps in JDeveloper
4.5.3
Creating Configuration Files in JDeveloper
Part II Using Data Clusters
5
Introduction to Coherence Clusters
5.1
Cluster Overview
5.2
Understanding TCMP
5.3
Understanding Cluster Services
6
Setting Up a Cluster
6.1
Overview of Setting Up Clusters
6.2
Specifying a Cluster's Name
6.3
Specifying a Cluster Member's Identity
6.4
Configuring Multicast Communication
6.4.1
Specifying a Cluster's Multicast Address
6.4.1.1
Changing the Multicast Socket Interface
6.4.2
Disabling Multicast Communication
6.4.3
Specifying the Multicast Time-to-Live
6.4.4
Specifying the Multicast Join Timeout
6.4.5
Changing the Multicast Threshold
6.5
Specifying a Cluster Member's Unicast Address
6.6
Using Well Known Addresses
6.6.1
Specifying WKA Member Addresses
6.6.2
Specifying a WKA Address Provider
6.7
Enabling Single-Server Mode
6.8
Configuring Death Detection
6.8.1
Changing TCP-Ring Settings
6.8.2
Changing the Heartbeat Interval
6.8.3
Disabling Death Detection
6.9
Specifying Cluster Priorities
6.9.1
Specifying a Cluster Member's Priority
6.9.2
Specifying Thread Priority
7
Starting and Stopping Cluster Members
7.1
Starting Cache Servers
7.1.1
Starting Cache Servers From the Command Line
7.1.2
Starting Cache Servers Programmatically
7.2
Starting Cache Clients
7.2.1
Disabling Local Storage
7.2.2
Using the CacheFactory Class to Start a Cache Client
7.3
Stopping Cluster Members
7.3.1
Stopping Cluster Members From the Command Line
7.3.2
Stopping Cache Servers Programmatically
8
Dynamically Managing Cluster Membership
8.1
Using the Cluster and Service Objects
8.2
Using the Member Object
8.3
Listening to Member Events
9
Tuning TCMP Behavior
9.1
Overview of TCMP Data Transmission
9.2
Throttling Data Transmission
9.2.1
Adjusting Packet Flow Control Behavior
9.2.2
Disabling Packet Flow Control
9.2.3
Adjusting Packet Traffic Jam Behavior
9.3
Bundling Packets to Reduce Load
9.4
Changing Packet Retransmission Behavior
9.4.1
Changing the Packet Resend Interval
9.4.2
Changing the Packet Resend Timeout
9.4.3
Configuring Packet Acknowledgment Delays
9.5
Configuring the Transmission Packet Pool Size
9.6
Configuring the Size of the Packet Buffers
9.6.1
Understanding Packet Buffer Sizing
9.6.2
Configuring the Outbound Packet Buffer Size
9.6.3
Configuring the Inbound Packet Buffer Size
9.7
Adjusting the Maximum Size of a Packet
9.8
Changing the Packet Speaker Volume Threshold
9.9
Changing Message Handler Behavior
9.9.1
Configuring the Incoming Message Handler
9.9.1.1
Changing the Time Variance
9.9.1.2
Disabling Negative Acknowledgments
9.9.1.3
Configuring the Incoming Handler's Packet Pool
9.9.2
Configuring the Outgoing Message Handler
9.9.2.1
Configuring the Outgoing Handler's Message Pool
9.10
Changing the TCMP Socket Provider Implementation
9.10.1
Using the TCP Socket Provider
9.10.2
Using the SSL Socket Provider
9.10.3
Enabling a Custom Socket Provider
10
Using Network Filters
10.1
Overview of Network Filters
10.2
Using the Compression Filter
10.2.1
Enabling the Compression Filter for Specific Services
10.2.2
Enabling the Compression Filter for All Services
10.2.3
Configuring the Compression Filter
10.3
Using the Encryption Filters
10.3.1
Enabling the Symmetric Encryption Filter
10.3.1.1
Symmetric Encryption Filter Parameters
10.3.2
Enabling the PKCS Encryption Filter
10.3.2.1
PKCS Encryption Filter Parameters
10.4
Using Custom Network Filters
10.4.1
Declaring a Custom Filter
10.4.2
Enabling a Custom Filter for Specific Services
10.4.3
Enabling a Custom Filter for All Services
Part III Using Caches
11
Introduction to Caches
11.1
Distributed Cache
11.2
Replicated Cache
11.3
Optimistic Cache
11.4
Near Cache
11.5
Local Cache
11.6
Remote Cache
11.7
Summary of Cache Types
12
Configuring Caches
12.1
Overview
12.2
Defining Cache Mappings
12.2.1
Using One-to-One Cache Mappings
12.2.2
Using Cache Name Pattern Mappings
12.2.3
Specifying Initialization Parameters in a Mapping
12.3
Defining Cache Schemes
12.3.1
Defining Distributed Cache Schemes
12.3.2
Defining Replicated Cache Schemes
12.3.3
Defining Optimistic Cache Schemes
12.3.4
Defining Local Cache Schemes
12.3.4.1
Controlling the Growth of a Local Cache
12.3.5
Defining Near Cache Schemes
12.3.5.1
Near Cache Invalidation Strategies
12.4
Using Scheme Inheritance
12.5
Using Cache Scheme Properties
12.6
Using Parameter Macros
13
Implementing Storage and Backing Maps
13.1
Cache Layers
13.2
Local Storage
13.3
Operations
13.4
Capacity Planning
13.5
Using Partitioned Backing Maps
13.6
Using the Elastic Data Feature to Store Data
13.6.1
Journaling Overview
13.6.2
Defining Journal Schemes
13.6.2.1
Configuring a RAM Journal Backing Map
13.6.2.2
Configuring a Flash Journal Backing Map
13.6.2.3
Referencing a Journal Scheme
13.6.2.4
Using a Journal Scheme for Backup Storage
13.6.2.5
Enabling a Custom Map Implementation for a Journal Scheme
13.6.3
Changing Journaling Behavior
13.6.3.1
Configuring the RAM Journal Resource Manager
13.6.3.2
Configuring the Flash Journal Resource Manager
14
Caching Data Sources
14.1
Overview of Caching Data Sources
14.1.1
Pluggable Cache Store
14.1.2
Read-Through Caching
14.1.3
Write-Through Caching
14.1.4
Write-Behind Caching
14.1.4.1
Write-Behind Requirements
14.1.5
Refresh-Ahead Caching
14.2
Selecting a Cache Strategy
14.2.1
Read-Through/Write-Through versus Cache-Aside
14.2.2
Refresh-Ahead versus Read-Through
14.2.3
Write-Behind versus Write-Through
14.3
Creating a CacheStore Implementation
14.4
Plugging in a CacheStore Implementation
14.5
Sample CacheStore
14.6
Sample Controllable CacheStore
14.7
Implementation Considerations
14.7.1
Idempotency
14.7.2
Write-Through Limitations
14.7.3
Cache Queries
14.7.4
Re-entrant Calls
14.7.5
Cache Server Classpath
14.7.6
CacheStore Collection Operations
14.7.7
Connection Pools
15
Serialization Paged Cache
15.1
Understanding Serialization Paged Cache
15.2
Configuring Serialization Paged Cache
15.3
Optimizing a Partitioned Cache Service
15.4
Configuring for High Availability
15.5
Configuring Load Balancing and Failover
15.6
Supporting Huge Caches
16
Using Quorum
16.1
Overview
16.2
Using the Cluster Quorum
16.2.1
Configuring the Cluster Quorum Policy
16.3
Using the Partitioned Cache Quorums
16.3.1
Configuring the Partitioned Cache Quorum Policy
16.4
Using the Proxy Quorum
16.4.1
Configuring the Proxy Quorum Policy
16.5
Enabling Custom Action Policies
17
Cache Configurations by Example
17.1
Local Caches (accessible from a single JVM)
17.1.1
In-memory Cache
17.1.2
NIO In-memory Cache
17.1.3
Size Limited In-memory Cache
17.1.4
In-memory Cache with Expiring Entries
17.1.5
Cache on Disk
17.1.6
Size Limited Cache on Disk
17.1.7
Persistent Cache on Disk
17.1.8
In-memory Cache with Disk Based Overflow
17.1.9
Cache of a Database
17.2
Clustered Caches (accessible from multiple JVMs)
17.2.1
Replicated Cache
17.2.2
Replicated Cache with Overflow
17.2.3
Partitioned Cache
17.2.4
Partitioned Cache with Overflow
17.2.5
Partitioned Cache of a Database
17.2.6
Partitioned Cache with a Serializer
17.2.7
Near Cache
Part IV Using the Programming API
18
Serializing Objects
19
Using Portable Object Format
19.1
Overview
19.2
Working with POF
19.2.1
Implementing the PortableObject interface
19.2.2
Implementing the PofSerializer interface:
19.2.3
Assigning POF Indexes
19.2.4
Using the ConfigurablePofContext Class
19.2.5
Configuring Coherence to Use the ConfigurablePofContext Class
19.2.5.1
Configure the ConfigurablePofContext Class Per Service
19.2.5.2
Configure the ConfigurablePofContext Class for All Services
19.2.5.3
Configure the ConfigurablePofContext Class For the JVM
19.3
Using POF Extractors and POF Updaters
19.3.1
Navigating a POF object
19.3.2
Using PofExtractors
19.3.3
Using PofUpdaters
20
Pre-Loading a Cache
20.1
Performing Bulk Loading and Processing
20.1.1
Bulk Writing to a Cache
20.1.2
Efficient processing of filter results
20.1.3
A Bulk Loading and Processing Example
20.2
Performing Distributed Bulk Loading
20.2.1
A Distributed Bulk Loading Example
21
Using Cache Events
21.1
Listener Interface and Event Object
21.2
Caches and Classes that Support Events
21.3
Signing Up for All Events
21.4
Using an Inner Class as a MapListener
21.5
Configuring a MapListener for a Cache
21.6
Signing up for Events on specific identities
21.7
Filtering Events
21.8
"Lite" Events
21.9
Advanced: Listening to Queries
21.9.1
Filtering Events Versus Filtering Cached Data
21.10
Advanced: Synthetic Events
21.11
Advanced: Backing Map Events
21.11.1
Producing Readable Backing MapListener Events from Distributed Caches
21.12
Advanced: Synchronous Event Listeners
22
Querying Data In a Cache
22.1
Query Overview
22.1.1
Query Concepts
22.2
Performing Simple Queries
22.3
Using Query Indexes
22.3.1
Creating an Index
22.3.2
Creating User-Defined Indexes
22.3.2.1
Implementing the MapIndex Interface
22.3.2.2
Implementing the IndexAwareExtractor Interface
22.3.2.3
Using a Conditional Index
22.4
Batching Queries and Memory Usage
22.5
Queries Involving Multi-Value Attributes
22.6
ChainedExtractor
23
Using Continuous Query Caching
23.1
Uses of Continuous Query Caching
23.2
The Coherence Continuous Query Cache
23.3
Constructing a Continuous Query Cache
23.3.1
Cleaning up the resources associated with a ContinuousQueryCache
23.4
Caching only keys, or caching both keys and values
23.4.1
CacheValues Property and Event Listeners
23.5
Listening to the ContinuousQueryCache
23.5.1
Achieving a Stable Materialized View
23.5.2
Support for Synchronous and Asynchronous Listeners
23.6
Making the ContinuousQueryCache Read-Only
24
Processing Data In a Cache
24.1
Targeted Execution
24.2
Parallel Execution
24.3
Query-Based Execution
24.4
Data-Grid-Wide Execution
24.5
Agents for Targeted, Parallel and Query-Based Execution
24.6
Data Grid Aggregation
24.7
Node-Based Execution
24.8
Work Manager
25
Managing Map Operations with Triggers
25.1
A Map Trigger Example
26
Using Coherence Query Language
26.1
Understanding Coherence Query Language Syntax
26.1.1
Query Syntax Basics
26.1.1.1
Using Path-Expressions
26.1.1.2
Using Bind Variables
26.1.1.3
Using Key and Value Pseudo-Functions
26.1.1.4
Using Aliases
26.1.1.5
Using Quotes with Literal Arguments
26.1.2
Retrieving Data
26.1.2.1
Retrieving Data from the Cache
26.1.2.2
Filtering Entries in a Result Set
26.1.3
Managing the Cache Lifecycle
26.1.3.1
Creating a Cache
26.1.3.2
Writing a Serialized Representation of a Cache to a File
26.1.3.3
Loading Cache Contents from a File
26.1.3.4
Removing a Cache from the Cluster
26.1.4
Working with Cache Data
26.1.4.1
Aggregating Query Results
26.1.4.2
Changing Existing Values
26.1.4.3
Inserting Entries in the Cache
26.1.4.4
Deleting Entries in the Cache
26.1.5
Working with Indexes
26.1.5.1
Creating an Index on the Cache
26.1.5.2
Removing an Index from the Cache
26.1.6
Issuing Multiple Query Statements
26.1.6.1
Processing Query Statements in Batch Mode
26.2
Using the CohQL Command-Line Tool
26.2.1
Starting the Command-line Tool
26.2.2
Using Command-Line Tool Arguments
26.2.3
A Command-Line Example
26.3
Building Filters in Java Programs
26.4
Additional Coherence Query Language Examples
26.4.1
Simple SELECT * FROM Statements that Highlight Filters
26.4.2
Complex Queries that Feature Projection, Aggregation, and Grouping
26.4.3
UPDATE Examples
26.4.4
Key and Value Pseudo-Function Examples
27
Performing Transactions
27.1
Overview of Transactions
27.2
Using Explicit Locking for Data Concurrency
27.3
Using Entry Processors for Data Concurrency
27.4
Using the Transaction Framework API
27.4.1
Defining Transactional Caches
27.4.2
Performing Cache Operations within a Transaction
27.4.2.1
Using the NamedCache API
27.4.2.2
Using the Connection API
27.4.3
Creating Transactional Connections
27.4.4
Using Transactional Connections
27.4.4.1
Using Auto-Commit Mode
27.4.4.2
Setting Isolation Levels
27.4.4.3
Using Eager Mode
27.4.4.4
Setting Transaction Timeout
27.4.5
Using the OptimisticNamedCache Interface
27.4.6
Configuring POF When Performing Transactions
27.4.7
Configuring Transactional Storage Capacity
27.4.8
Performing Transactions from Java Extend Clients
27.4.8.1
Create an Entry Processor for Transactions
27.4.8.2
Configure the Cluster-Side Transaction Caches
27.4.8.3
Configure the Client-Side Remote Cache
27.4.8.4
Use the Transactional Entry Processor from a Java Client
27.4.9
Viewing Transaction Management Information
27.4.9.1
CacheMBeans for Transactional Caches
27.4.9.2
TransactionManagerBean
27.5
Using the Coherence Resource Adapter
27.5.1
Performing Cache Operations within a Transaction
27.5.1.1
Creating a Coherence Connection
27.5.1.2
Getting a Named Cache
27.5.1.3
Demarcating Transaction Boundaries
27.5.2
Packaging the Application
27.5.2.1
Configure the Connection Factory Resource Reference
27.5.2.2
Configure the Resource Adapter Module Reference
27.5.2.3
Include the Required Libraries
27.5.3
Using the Coherence Cache Adapter for Transactions
28
Data Affinity
28.1
Specifying Affinity
28.2
Specifying Data Affinity with a KeyAssociation
28.3
Specifying Data Affinity with a KeyAssociator
28.4
Example of Using Affinity
29
Priority Tasks
29.1
Priority Tasks — Timeouts
29.1.1
Configuring Execution Timeouts
29.1.2
Command Line Options
29.2
Priority Task Execution — Custom Objects
29.2.1
APIs for Creating Priority Task Objects
29.2.2
Errors Thrown by Task Timeouts
30
Using the Service Guardian
30.1
Overview
30.2
Configuring the Service Guardian
30.2.1
Setting the Guardian Timeout
30.2.1.1
Setting the Guardian Timeout for All Threads
30.2.1.2
Setting the Guardian Timeout Per Service Type
30.2.1.3
Setting the Guardian Timeout Per Service Instance
30.2.2
Using the Timeout Value From the PriorityTask API
30.2.3
Setting the Guardian Service Failure Policy
30.2.3.1
Setting the Guardian Failure Policy for All Threads
30.2.3.2
Setting the Guardian Failure Policy Per Service Type
30.2.3.3
Setting the Guardian Failure Policy Per Service Instance
30.2.3.4
Enabling a Custom Guardian Failure Policy
30.3
Issuing Manual Guardian Heartbeats
31
Specifying a Custom Eviction Policy
32
Constraints on Re-entrant Calls
32.1
Re-entrancy, Services, and Service Threads
32.1.1
Parent-Child Object Relationships
32.1.2
Avoiding Deadlock
32.2
Re-entrancy and Listeners
A
Operational Configuration Elements
A.1
Operational Deployment Descriptor
A.2
Operational Override File
Element Reference
access-controller
address-provider
authorized-hosts
cache-factory-builder-config
callback-handler
cluster-config
cluster-quorum-policy
coherence
configurable-cache-factory-config
filter
filters
flashjournal-manager
flow-control
host-range
identity-asserter
identity-manager
identity-transformer
incoming-message-handler
init-param
init-params
instance
journaling-config
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
ramjournal-manager
reporter
security-config
serializer
serializers
service
Initialization Parameter Settings
service-guardian
services
shutdown-listener
socket-address
socket-provider
socket-providers
ssl
tcp-ring-listener
traffic-jam
trust-manager
unicast-listener
volume-threshold
well-known-addresses
Attribute Reference
B
Cache Configuration Elements
B.1
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
distributed-scheme
external-scheme
flashjournal-scheme
identity-manager
initiator-config
init-param
init-params
instance
invocation-scheme
invocation-service-proxy
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
ramjournal-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
Attribute Reference
C
Command Line Overrides
C.1
Override Example
C.2
Preconfigured Override Values
D
POF User Type Configuration Elements
D.1
POF Configuration Deployment Descriptor
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
The PIF-POF Binary Format
E.1
Stream Format
E.1.1
Integer Values
E.1.2
Type Identifiers
E.2
Binary Formats for Predefined Types
E.2.1
Int
E.2.1.1
Coercion of Integer Types
E.2.2
Decimal
E.2.3
Floating Point
E.2.4
Boolean
E.2.5
Octet
E.2.6
Octet String
E.2.7
Char
E.2.8
Char String
E.2.9
Date
E.2.10
Year-Month Interval
E.2.11
Time
E.2.12
Time Interval
E.2.13
Date-Time
E.2.13.1
Coercion of Date and Time Types
E.2.14
Day-Time Interval
E.2.15
Collections
E.2.16
Arrays
E.2.17
Sparse Arrays
E.2.18
Key-Value Maps (Dictionaries)
E.2.19
Identity
E.2.20
Reference
E.3
Binary Format for User Types
E.3.1
Versioning of User Types