<commit_before>### JCache Near Cache

Cache entries in Hazelcast are stored as partitioned across the cluster. 
When you try to read a record with the key `k`, if the current node is not the owner of that key (i.e. not the owner of partition that the key belongs to), 
Hazelcast sends a remote operation to the owner node. Each remote operation means lots of network trips. 
If your cache is used for mostly read operations, it is advised to use a near cache storage in front of the cache itself to read cache records faster and consume less network traffic.
<br><br>
![image](images/NoteSmall.jpg) ***NOTE:*** *Near cache for JCache is only available for clients NOT servers.*
<br><br>

However, using near cache comes with some trade-off for some cases:

- There will be extra memory consumption for storing near cache records at local.
- If invalidation is enabled and entries are updated frequently, there will be many invalidation events across the cluster.
- Near cache does not give strong consistency but gives eventual consistency guarantees. It is possible to read stale data.

#### Invalidation

Invalidation is the process of removing an entry from the near cache since the entry is not valid anymore (its value is updated or it is removed from actual cache). Near cache invalidation happens asynchronously at the cluster level, but synchronously in real-time at the current node. This means when an entry is updated (explicitly or via entry processor) or removed (deleted explicitly or via entry processor, evicted, expired), it is invalidated from all near caches asynchronously within the whole cluster but updated/removed at/from current node synchronously. In general terms, whenever an entry state is changed in record store by updating its value in someway or removing it in someway, invalidation event is sent for that entry.

There are two types of invalidation event sending as single or batch. Batch event sending is advised if there are so many mutating operations such as put and remove on cache. This reduces network traffic and keeps event system busy less. 

Here are configurations for batch event sending:
- `hazelcast.cache.invalidation.batch.enabled`: Defines cache invalidation event batch sending is enabled or not. The default value is `true`.
- `hazelcast.cache.invalidation.batch.size`: Defines the maximum number of cache invalidation events to be drained and sent to the event listeners in a batch. The default value is `100`.
- `hazelcast.cache.invalidation.batchfrequency.seconds`: Defines cache invalidation event batch sending frequency in seconds. When event size does not reach to `hazelcast.cache.invalidation.batch.size` in the given time period, those events are gathered into a batch and sent to target. The default value is `5` seconds.

So if there are so many clients or so many mutating operation, batching should remain enabled and batch size should be configured with `hazelcast.cache.invalidation.batch.size` for a suitable value.

#### Expiration

Expiration means that evicting expired records. 
So a record is expired, 
- If it is not touched (accessed/read) during `<max-idle-seconds>`
- `<time-to-live-seconds>` passed since it is put to near-cache

Expiration are done in two cases:
- When a record is accessed, it is checked about if it is expired or not. If it is expired, it is evicted and returns `null` to caller.
- At background there is an expiration task that periodically (currently 5 seconds) scans records and evicts expired records.

#### Eviction

In the scope of near cache scope, eviction means that evicting (clearing) entries selected as specified eviction policy when specified max-size policy has been reached.
Eviction is handled with max-size policy and eviction policy configurations.

##### Max-Size Policy

Max-Size policy defines the state when near-cache is full and eviction should be triggered.
The following max-size policies are supported by near-cache eviction:
- **ENTRY_COUNT:** Decides maximum based on the count of the number of entries in the near-cache. 
Available only for `BINARY` and `OBJECT` in-memory formats.<commit_msg>Progressing the JCache Near Cache review.<commit_after>### JCache Near Cache

Cache entries in Hazelcast are stored as partitioned across the cluster. 
When you try to read a record with the key `k`, if the current node is not the owner of that key (i.e. not the owner of partition that the key belongs to), 
Hazelcast sends a remote operation to the owner node. Each remote operation means lots of network trips. 
If your cache is used for mostly read operations, it is advised to use a near cache storage in front of the cache itself to read cache records faster and consume less network traffic.
<br><br>
![image](images/NoteSmall.jpg) ***NOTE:*** *Near cache for JCache is only available for clients NOT servers.*
<br><br>

However, using near cache comes with some trade-off for some cases:

- There will be extra memory consumption for storing near cache records at local.
- If invalidation is enabled and entries are updated frequently, there will be many invalidation events across the cluster.
- Near cache does not give strong consistency but gives eventual consistency guarantees. It is possible to read stale data.

#### Invalidation

Invalidation is the process of removing an entry from the near cache since the entry is not valid anymore (its value is updated or it is removed from actual cache). Near cache invalidation happens asynchronously at the cluster level, but synchronously in real-time at the current node. This means when an entry is updated (explicitly or via entry processor) or removed (deleted explicitly or via entry processor, evicted, expired), it is invalidated from all near caches asynchronously within the whole cluster but updated/removed at/from the current node synchronously. Generally, whenever the state of an entry changes in the record store by updating its value or removing it, the invalidation event is sent for that entry.

Invalidation events can be sent either individually or in batches. If there are lots of mutating operations such as put/remove on the cache, sending the events in batches is advised. This reduces the network traffic and keeps the eventing system less busy. 

You can use the following system properties to configure the sending of invalidation events in batches:

- `hazelcast.cache.invalidation.batch.enabled`: Specifies whether the cache invalidation event batch sending is enabled or not. The default value is `true`.
- `hazelcast.cache.invalidation.batch.size`: Defines the maximum number of cache invalidation events to be drained and sent to the event listeners in a batch. The default value is `100`.
- `hazelcast.cache.invalidation.batchfrequency.seconds`: Defines cache invalidation event batch sending frequency in seconds. When event size does not reach to `hazelcast.cache.invalidation.batch.size` in the given time period, those events are gathered into a batch and sent to target. The default value is `5` seconds.

So if there are so many clients or so many mutating operation, batching should remain enabled and batch size should be configured with `hazelcast.cache.invalidation.batch.size` for a suitable value.

#### Expiration

Expiration means that evicting expired records. 
So a record is expired, 
- If it is not touched (accessed/read) during `<max-idle-seconds>`
- `<time-to-live-seconds>` passed since it is put to near-cache

Expiration are done in two cases:
- When a record is accessed, it is checked about if it is expired or not. If it is expired, it is evicted and returns `null` to caller.
- At background there is an expiration task that periodically (currently 5 seconds) scans records and evicts expired records.

#### Eviction

In the scope of near cache scope, eviction means that evicting (clearing) entries selected as specified eviction policy when specified max-size policy has been reached.
Eviction is handled with max-size policy and eviction policy configurations.

##### Max-Size Policy

Max-Size policy defines the state when near-cache is full and eviction should be triggered.
The following max-size policies are supported by near-cache eviction:
- **ENTRY_COUNT:** Decides maximum based on the count of the number of entries in the near-cache. 
Available only for `BINARY` and `OBJECT` in-memory formats.
{'fraction_non_alphanumeric': 0.05015561407708882, 'fraction_numerical': 0.0011970313622216902, 'mean_word_length': 4.588628762541806, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4618952', 'n_tokens_mistral': 2022, 'n_tokens_neox': 1967, 'n_words': 1242}