Developing Remote Clients for Oracle Coherence
Total Page:16
File Type:pdf, Size:1020Kb
Oracle® Fusion Middleware Developing Remote Clients for Oracle Coherence 12c (12.2.1.4.0) E90863-04 April 2021 Oracle Fusion Middleware Developing Remote Clients for Oracle Coherence, 12c (12.2.1.4.0) E90863-04 Copyright © 2008, 2021, Oracle and/or its affiliates. Primary Author: Oracle Corporation 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 is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs) and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end users are "commercial computer software" or "commercial computer software documentation" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the license contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloud services are defined by the applicable contract for such services. No other rights are granted to the U.S. Government. This software or hardware 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 that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. This software or hardware and documentation may provide access to or information about 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 unless otherwise set forth in an applicable agreement between you and Oracle. 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, except as set forth in an applicable agreement between you and Oracle. Contents Preface Audience xv Documentation Accessibility xv Related Documents xvi Conventions xvi What's New in This Guide New and Changed Features xvii Other Significant Changes in This Document xviii Part I Getting Started 1 Introduction to Coherence*Extend Overview of Coherence*Extend 1-1 Extend Clients 1-2 Extend Client APIs 1-2 POF Serialization 1-3 Understanding Extend Client Configuration Files 1-3 Non-Native Client Support 1-4 REST Client Support 1-4 Memcached Client Support 1-4 2 Building Your First Extend Application Overview of the Extend Example 2-1 Step 1: Configure the Cluster Side 2-1 Step 2: Configure the Client Side 2-2 Step 3: Create the Sample Client 2-3 Step 4: Start the Cache Server Process 2-5 iii Step 5: Run the Application 2-5 3 Configuring Extend Proxies Overview of Configuring Extend Proxies 3-1 Defining Extend Proxy Services 3-1 Defining a Single Proxy Service Instance 3-2 Defining Multiple Proxy Service Instances 3-2 Defining Multiple Proxy Services 3-3 Explicitly Configuring Proxy Addresses 3-3 Disabling Cluster Service Proxies 3-4 Specifying Read-Only NamedCache Access 3-5 Defining Caches for Use By Extend Clients 3-5 Disabling Storage on a Proxy Server 3-8 Starting a Proxy Server 3-9 4 Configuring Extend Clients Overview of Configuring Extend Clients 4-1 Defining a Remote Cache 4-1 Using a Remote Cache as a Back Cache 4-3 Defining Remote Invocation Schemes 4-4 Connecting to Specific Proxy Addresses 4-5 Detecting Connection Errors 4-6 Disabling TCMP Communication 4-7 5 Advanced Extend Configuration Using Address Provider References for TCP Addresses 5-1 Using a Custom Address Provider for TCP Addresses 5-2 Load Balancing Connections 5-3 Using Proxy-Based Load Balancing 5-3 Understanding the Proxy-Based Load Balancing Default Algorithm 5-4 Implementing a Custom Proxy-Based Load Balancing Strategy 5-5 Using Client-Based Load Balancing 5-6 6 Best Practices for Coherence*Extend Do Not Run a Near Cache on a Proxy Server 6-1 Configure Heap NIO Space to be Equal to the Max Heap Size 6-1 Configure Proxy Service Thread Pooling 6-1 Understanding Proxy Service Threading 6-2 iv Setting Proxy Service Thread Pooling Thresholds 6-2 Setting an Exact Number of Threads 6-3 Be Careful When Making InvocationService Calls 6-3 Be Careful When Placing Collection Classes in the Cache 6-4 Configure POF Serializers for Cache Servers 6-4 Configuring Firewalls for Extend Clients 6-5 Part II Creating Java Extend Clients Part III Creating C++ Extend Clients 7 Introduction to Coherence C++ Clients Overview of Coherence for C++ 7-1 Setting Up C++ Application Builds 7-1 Setting up the Compiler for Coherence-Based Applications 7-2 Including Coherence Header Files 7-2 Linking the Coherence Library 7-2 Setting the run-time Library and Search Path 7-3 Deploying Coherence for C++ 7-4 8 Configuration and Usage for C++ Clients General Instructions 8-1 Implement the C++ Application 8-1 Compile and Link the Application 8-2 Configure Paths 8-3 Obtaining a Cache Reference with C++ 8-3 Cleaning up Resources Associated with a Cache 8-3 Configuring and Using the Coherence for C++ Client Library 8-3 Setting the Configuration File Location with an Environment Variable 8-3 Setting the Configuration File Location Programmatically 8-4 Operational Configuration File (tangosol-coherence-override.xml) 8-4 Configuring a Logger 8-6 9 Using the Coherence C++ Object Model Using the Object Model 9-1 Coherence Namespaces 9-1 Understanding the Base Object 9-2 v Automatically Managed Memory 9-2 Referencing Managed Objects 9-2 Using handles 9-3 Managed Object Instantiation 9-3 Managed Strings 9-4 String Instantiation 9-4 Auto-Boxed Strings 9-4 Type Safe Casting 9-4 Down Casting 9-5 Managed Arrays 9-5 Collection Classes 9-6 Managed Exceptions 9-7 Object Immutability 9-7 Integrating Existing Classes into the Object Model 9-8 Writing New Managed Classes 9-8 Specification-Based Managed Class Definition 9-9 Equality, Hashing, Cloning, Immutability, and Serialization 9-12 Threading 9-12 Weak References 9-13 Virtual Constructors 9-15 Advanced Handle Types 9-15 Thread Safety 9-16 Synchronization and Notification 9-16 Thread Safe Handles 9-17 Escape Analysis 9-19 Thread-Local Allocator 9-21 Diagnostics and Troubleshooting 9-21 Thread-Local Allocator Logs 9-21 Thread Dumps 9-22 Memory Leak Detection 9-22 Memory Corruption Detection 9-23 Application Launcher - Sanka 9-23 Command line syntax 9-24 Built-in Executables 9-24 Sample Custom Executable Class 9-24 10 Using the Coherence for C++ Client API CacheFactory 10-1 NamedCache 10-1 QueryMap 10-2 vi ObservableMap 10-2 InvocableMap 10-3 Filter 10-3 Value Extractors 10-4 Entry Processors 10-5 Entry Aggregators 10-5 11 Building Integration Objects (C++) Overview of Building Integration Objects (C++) 11-1 POF Intrinsics 11-1 Serialization Options 11-2 Overview of Serialization Options 11-2 Managed<T> (Free-Function Serialization) 11-3 PortableObject (Self-Serialization) 11-5 PofSerializer (External Serialization) 11-7 Using POF Object References 11-9 Enabling POF Object References 11-10 Registering POF Object Identities for Circular and Nested Objects 11-10 Registering Custom C++ Types 11-12 Implementing a Java Version of a C++ Object 11-13 Understanding Serialization Performance 11-14 Using POF Annotations to Serialize Objects 11-14 Annotating Objects for POF Serialization 11-14 Registering POF Annotated Objects 11-15 Enabling Automatic Indexing 11-16 Providing a Custom Codec 11-16 12 Querying a Cache (C++) Overview