Red Hat Data Grid 8.2 Data Grid Developer Guide Customize, configure, and extend Data Grid Last Updated: 2021-09-21 Red Hat Data Grid 8.2 Data Grid Developer Guide Customize, configure, and extend Data Grid Legal Notice Copyright © 2021 Red Hat, Inc. The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/ . In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux ® is the registered trademark of Linus Torvalds in the United States and other countries. Java ® is a registered trademark of Oracle and/or its affiliates. XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and other countries. Node.js ® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. All other trademarks are the property of their respective owners. Abstract Learn about Data Grid APIs, how to code your applications to use Data Grid capabilities, and how to customize Data Grid. Table of Contents Table of Contents .R .E . D. H. .A . T. D. .A . T. .A . .G . R. .I D. 6. .D . A. .T .A . .G . .R . I.D . .D . O. .C . .U . M. .E . N. .T . A. .T . I.O . .N . 7. .D . A. .T .A . .G . .R . I.D . .D . O. .W . .N . .L .O . .A . D. .S . 8. .M . A. .K . I.N . .G . .O . P. .E . N. S. .O . U. .R . C. .E . .M . .O . R. .E . .I N. .C . L. .U . S. .I V. .E . 9. .C . H. .A . P. .T .E . R. 1.. .C . O. N. .F . I.G . U. R. I. N. .G . .T . H. .E . .D . A. .T . A. G. .R . I.D . .M . .A . V. .E . N. R. .E .P . O. S. .I T. O. R. .Y . 1.0 . 1.1. DOWNLOADING THE DATA GRID MAVEN REPOSITORY 10 1.2. ADDING RED HAT MAVEN REPOSITORIES 10 1.3. CONFIGURING YOUR DATA GRID POM 11 .C . H. .A . P. .T .E . R. 2. C. .A . C. .H . .E . M. A. .N . A. .G . .E .R . S. 1. 2. 2.1. OBTAINING CACHES 12 2.2. CLUSTERING INFORMATION 13 2.3. MEMBER INFORMATION 13 .C . H. .A . P. .T .E . R. 3. C. A. .C . H. .E . .I N. .T . E. R. .F . A. .C . E. 1.4 . 3.1. CACHE API 14 3.1.1. Performance Concerns of Certain Map Methods 14 3.1.2. Mortal and Immortal Data 14 3.1.3. putForExternalRead operation 14 3.2. ADVANCEDCACHE API 15 3.2.1. Flags 15 3.3. LISTENERS AND NOTIFICATIONS 15 3.3.1. Cache-level notifications 16 3.3.1.1. Cluster Listeners 16 3.3.1.2. Event filtering and conversion 17 3.3.1.3. Initial State Events 17 3.3.1.4. Duplicate Events 18 3.3.2. Cache manager-level notifications 18 3.3.3. Synchronicity of events 18 3.3.3.1. Asynchronous thread pool 19 3.4. ASYNCHRONOUS API 19 3.4.1. Why use such an API? 19 3.4.2. Which processes actually happen asynchronously? 20 .C . H. .A . P. .T .E . R. 4. .Q . U. .E . R. .Y . I.N . G. .V . A. .L .U . E. .S . .I N. C. .A . C. .H . E. .S . 2. .1 . 4.1. CONFIGURING DATA GRID TO INDEX CACHES 21 4.1.1. Enabling Cache Indexing Programmatically 22 4.1.2. Index Annotations 22 4.1.3. Index Configuration 23 4.1.3.1. Index Storage 23 4.1.3.2. Index Reader 23 4.1.3.3. Index Writer 23 4.1.4. Rebuilding Indexes 26 4.2. CREATING ICKLE QUERIES 27 4.2.1. Ickle Query Example 27 Pagination 28 Number of Hits 28 Iteration 28 Named Query Parameters 28 1 Red Hat Data Grid 8.2 Data Grid Developer Guide 4.2.2. Ickle Query Language Parser Syntax 29 Filtering operators 29 Boolean conditions 30 Nested conditions 30 Selecting attributes 31 Sorting 31 Grouping and Aggregation 31 Aggregations 31 Evaluation of queries with grouping and aggregation 32 4.2.3. Using Full-Text Search 33 Fuzzy Queries 33 Range Queries 33 Phrase Queries 33 Proximity Queries 33 Wildcard Queries 33 Regular Expression Queries 33 Boosting Queries 33 4.3. EMBEDDED QUERIES 34 4.3.1. Embedded Query Example 34 4.3.2. Mapping Entities 35 @DocumentId 36 @Transformable keys 36 Programmatic mapping 37 4.4. REMOTE QUERIES 38 4.4.1. Remote Query Example 38 4.4.2. Registering Protobuf Schemas 40 4.4.3. Analysis 41 Default Analyzers 41 Using Analyzer Definitions 42 Creating Custom Analyzer Definitions 42 4.5. CONTINUOUS QUERIES 43 4.5.1. Continuous Query Execution 43 4.5.2. Creating Continuous Queries 44 4.5.3. Removing Continuous Queries 45 4.5.4. Continuous Query Performance 46 4.6. QUERY STATISTICS 46 4.7. QUERY PERFORMANCE TUNING 46 .C . H. .A . P. .T .E . R. 5. C. .L . U. .S . T. .E .R . E. .D . .L . O. .C . K. .S . .4 .8 . 5.1. LOCK API 48 5.2. USING CLUSTERED LOCKS 48 5.3. CONFIGURING INTERNAL CACHES FOR LOCKS 50 .C . H. .A . P. .T .E . R. 6. .C . L. U. .S . T. .E . R. E. .D . .C . O. U. .N . T. .E . R. .S . .5 . 2. 6.1. INSTALLATION AND CONFIGURATION 52 6.1.1. List counter names 54 6.2. COUNTERMANAGER INTERFACE 54 6.2.1. Remove a counter via CounterManager 55 6.3. THE COUNTER 55 6.3.1. The StrongCounter interface: when the consistency or bounds matters. 56 6.3.1.1. Bounded StrongCounter 57 6.3.1.2. Uses cases 57 6.3.1.3. Usage Examples 57 2 Table of Contents 6.3.2. The WeakCounter interface: when speed is needed 59 6.3.2.1. Weak Counter Interface 59 6.3.2.2. Uses cases 60 6.3.2.3. Examples 60 6.4. NOTIFICATIONS AND EVENTS 60 .C . H. .A . P. .T .E . R. 7. U. .S . I.N . .G . .T . H..