2019-11-26 Hazelcast Map配置文档

===== HAZELCAST MAP CONFIGURATION =====

Configuration element's name is "map". It has the optional attribute "name" with which you

can specify the name of your map. Its default value is "default".

It has the following sub-elements:

* "in-memory-format":

Specifies in which format data will be stored in your map. Available values are as follows:

- BINARY:

Data will be stored in serialized binary format. It is the default option.

- OBJECT:

Data will be stored in deserialized form.

- NATIVE:

Data will be stored in the map that uses Hazelcast's High-Density Memory Store feature. This

option is available only in Hazelcast Enterprise HD.

* "statistics-enabled":

When you enable it, you can retrieve map entry statistics such as creation time, expiration time,

number of hits, key, value, etc. Its default value is true.

* "optimize-queries":

It is deprecated as of Hazelcast 3.6. Use the "cache-deserialized-values" element instead. When

"optimize-queries" and "cache-deserialized-values" are used at the same time, Hazelcast will do its

best to detect possible conflicts. Conflict detection is done on best-effort basis and you should not

rely on it. If true, it increases the speed of query processes in the map. It only works when

"in-memory-format" is set to BINARY and performs a pre-caching on the entries queried. Its default

value is false.

* "metadata-policy"

Metadata policy for this map. Hazelcast may process objects of supported types ahead of time to

create additional metadata about them. This metadata then is used to make querying and indexing faster.

Metadata creation may decrease put throughput.

Valid values are:

CREATE_ON_UPDATE (default): Objects of supported types are pre-processed when they are created and updated.

OFF: No metadata is created.

* "cache-deserialized-values":

Controls caching of deserialized values. Caching makes the query evaluation faster, but it costs memory.

Available values are as follows:

- NEVER: Deserialized values will never be cached.

- INDEX-ONLY: Deserialized values will be cached only when they are inserted into an index.

- ALWAYS: Deserialized values will always be cached.

* "backup-count":

Count of synchronous backups. When this count is 1, a map entry will have its backup on one other node in

the cluster. If you set it to 2, then a map entry will have its backup on two other nodes. You can set it

to 0 if you do not want your entries to be backed up. The maximum value for the backup count is 6.

Its default value is 1.

* "async-backup-count":

Number of asynchronous backups. Unlike the synchronous backup process, asynchronous backup process does not

block the map operations. Its default value is 0, meaning there will be no asynchronous backups.

* "time-to-live-seconds":

Maximum time in seconds for each entry to stay in the map. If it is not 0, entries that are older than

this time and not updated for this time are evicted automatically. Valid values are integers between 0 and

Integer.MAX VALUE. Its default value is 0, which means infinite. If it is not 0, entries are evicted regardless

of the set eviction-policy.

* "max-idle-seconds":

Maximum time in seconds for each entry to stay idle in the map. Entries that are idle for more than

this time are evicted automatically. An entry is idle if no get, put, EntryProcessor.process or

containsKey is called. Valid values are integers between 0 and Integer.MAX VALUE. Its default value

is 0, which means infinite.

* "eviction-policy":

Eviction policy configuration. Its default values is NONE. Available values are as follows:

- NONE:

No items will be evicted and the property max-size will be ignored. You still

can combine it with time-to-live-seconds and max-idle-seconds.

- LRU: Least Recently Used.

- LFU: Least Frequently Used.

* "map-eviction-policy-class-name":

Internal eviction algorithm finds the most appropriate entry to evict from the map by using this policy.

* "max-size":

Maximum size of the map depending on the given policy specified by its "policy" attribute. When maximum

size is reached, the map is evicted based on the policy defined. Valid values are integers between 0 and

Integer.MAX VALUE. Its default value is 0 and its default policy attribute is "PER_NODE". If you want

max-size to work, set the "eviction-policy" to a value other than NONE. Available max-size policies are

as follows:

- PER_NODE:

Maximum number of map entries in each cluster member. You cannot set the max-size to a value lower

than the partition count (which is 271 by default).

- PER_PARTITION:

Maximum number of map entries within each partition.

- USED_HEAP_SIZE:

Maximum used heap size in megabytes per map for each Hazelcast instance. It does not work when

"in-memory-format" is set to OBJECT.

- USED_HEAP_PERCENTAGE:

Maximum used heap size percentage per map for each Hazelcast instance. If, for example, JVM is

configured to have 1000 MB and this value is 10, then the map entries will be evicted when used heap size

exceeds 100 MB. It does not work when "in-memory-format" is set to OBJECT.

- FREE_HEAP_SIZE:

Minimum free heap size in megabytes for each Hazelcast instance.

- FREE_HEAP_PERCENTAGE:

Minimum free heap size percentage for each Hazelcast instance. If, for example, JVM is configured to

have 1000 MB and this value is 10, then the map entries will be evicted when free heap size is below 100 MB.

- USED_NATIVE_MEMORY_SIZE:

Maximum used native memory size in megabytes per map for each Hazelcast instance. It is available only in

Hazelcast Enterprise HD.

- USED_NATIVE_MEMORY_PERCENTAGE:

Maximum used native memory size percentage per map for each Hazelcast instance. It is available only in

Hazelcast Enterprise HD.

- FREE_NATIVE_MEMORY_SIZE:

Minimum free native memory size in megabytes for each Hazelcast instance. It is available only in

Hazelcast Enterprise HD.

- FREE_NATIVE_MEMORY_PERCENTAGE:

Minimum free native memory size percentage for each Hazelcast instance. It is available only in

Hazelcast Enterprise HD.

* "eviction-percentage":

When "max-size" is reached, the specified percentage of the map will be evicted. For example, if set to 25,

25% of the entries will be evicted. Valid values are integers between 0 and 100. Its default value is 25.

* "min-eviction-check-millis":

Specifies the frequency of the eviction process, i.e. minimum time in milliseconds which should elapse before

checking whether a partition of the map is evictable or not. Its default value is 100. Setting it to 0 (zero)

makes the eviction process run for every put operation.

* "merge-policy":

Policy that specifies how the map entries in the small cluster will merge with the bigger cluster after a

split-brain syndrome. Its default values is "com.hazelcast.map.merge.PutIfAbsentMapMergePolicy". Available

built-in policies are as follows:

- com.hazelcast.map.merge.PassThroughMergePolicy:

Entry will be added if there is no existing entry for the key.

- com.hazelcast.map.merge.PutIfAbsentMapMergePolicy:

Entry will be added if the merging entry does not exist in the cluster.

- com.hazelcast.map.merge.HigherHitsMapMergePolicy:

Entry with the higher number of hits wins.

- com.hazelcast.map.merge.LatestUpdateMapMergePolicy:

Entry with the latest update wins.

* "read-backup-data":

Used to enable reading from local backup map entries. Its default value is false. It can be used if there is

at least 1 sync or async backup.

* "hot-restart":

Used to enable Hazelcast's Hot Restart Persistence feature for the map. It is available only in Hazelcast

Enterprise HD. Set its "enabled" to true to enable the feature. By default, it is disabled. It has the following

sub-element.

- "fsync":

Set to true if the writing to disk should be followed by an fsync() system call. Its default value is false.

* "map-store":

Configuration options when you want to load/store the map entries from/to a persistent data store such as a

relational database. Before configuring "map-store", you need to implement Hazelcast's MapStore or MapLoader

interfaces.

It has the following attributes:

- enabled:

Set to true to enable the map store functionality for your map. Its default value is true.

- initial-mode:

Sets the initial entry loading mode. Available values are as follows:

- LAZY: The loading is asynchronous. It is the default mode.

- EAGER: The loading is blocked until all partitions are loaded.

It has the following sub-elements:

- "class-name":

The name of your class implementing MapLoader and/or MapStore interface.

- "write-delay-seconds":

Number of seconds to delay the storing of entries. If the value is 0, then it is write-through.

Otherwise, it is write-behind so updates will be stored after this period. Its default value is 0.

- "write-batch-size":

Used to create batches when writing to map store. In default mode, all map entries will try

to be written in one go. To create batches, the minimum meaningful value is 2. For values smaller than 2,

it works as in default mode. Its default value is 1.

- "write-coalescing":

It is meaningful if you are using write behind in MapStore. When it is set to true,

only the latest store operation on a key during the write-delay-seconds will be

reflected to MapStore. Its default value is true.

- "properties":

While you are implementing MapStore or MapLoader you can define specific properties to be configured.

It can be your store's URL, credentials, etc. Please see the example map configuration snippet below.

* "near-cache":

Configuration options when you want to use a Near Cache for your map.

It has the following attributes:

- name: You can give a name for your Near Cache. It is optional and its default value is "default".

It has the following sub-elements:

- "max-size":

Maximum size of the Near Cache. When this is reached, Near Cache is evicted based on the policy defined.

Any integer between 0 and Integer.MAX_VALUE. 0 means Integer.MAX_VALUE. Its default value is 0.

- "time-to-live-seconds":

Maximum number of seconds for each entry to stay in the Near Cache. Entries that are older than this

period are automatically evicted from the Near Cache. Any integer between 0 and Integer.MAX_VALUE.

0 means infinite. Its default value is 0.

- "max-idle-seconds":

Maximum number of seconds each entry can stay in the Near Cache as untouched (not read). Entries that

are not read more than this period are removed from the Near Cache. Any integer between 0 and

Integer.MAX_VALUE. 0 means Integer.MAX_VALUE. Its default value is 0.

- "eviction-policy":

Eviction policy configuration. Its default values is NONE. Available values are as follows:

- NONE:

No items will be evicted and the property max-size will be ignored. You still

can combine it with time-to-live-seconds and max-idle-seconds.

- LRU: Least Recently Used.

- LFU: Least Frequently Used.

- "invalidate-on-change":

Specifies whether the cached entries are evicted when the entries are updated or removed. Its default

value is true.

- "in-memory-format":

Specifies in which format data will be stored in your Near Cache. Note that a map's in-memory format

can be different from that of its Near Cache.

Available values are as follows:

- BINARY:

Data will be stored in serialized binary format. It is the default option.

- OBJECT:

Data will be stored in deserialized form.

- NATIVE:

Data will be stored in the Near Cache that uses Hazelcast's High-Density Memory Store feature.

This option is available only in Hazelcast Enterprise HD. Note that a map and its Near Cache

can independently use High-Density Memory Store. For example, while your map does not use

High-Density Memory Store, its Near Cache can use it.

- "cache-local-entries":

Specifies whether the local entries will be cached. It can be useful when in-memory format for

Near Cache is different from that of the map. By default, it is disabled.

- "eviction":

Configuration for the eviction when the in-memory format of the Near Cache is NATIVE. It has the

following attributes:

- size: Maximum size (entry count) of the Near Cache.

- max-size-policy: Maximum size policy for eviction of the Near Cache. Available values are as follows:

* ENTRY_COUNT: Maximum entry count per member.

* USED_NATIVE_MEMORY_SIZE: Maximum used native memory size in megabytes.

* USED_NATIVE_MEMORY_PERCENTAGE: Maximum used native memory percentage.

* FREE_NATIVE_MEMORY_SIZE: Minimum free native memory size to trigger cleanup.

* FREE_NATIVE_MEMORY_PERCENTAGE: Minimum free native memory percentage to trigger cleanup.

- eviction-policy: See the "eviction-policy" element above.

- comparator-class-name: The comparator to be used while comparing entries to be evicted.

* "wan-replication-ref":

Configuration of the WAN replication for your map.

It has the following attributes:

- name:

Name of the WAN replication configuration specified in the "name" attribute of the

"wan-replication" element. See the "wan-replication" element above.

It has the following sub-elements:

- "filters":

Filters to intercept WAN replication events before they are placed to WAN event replication

queues by providing a filtering API. Just implement Hazelcast's MapWanEventFilter interface

to create your filters. You can define multiple filters and add to the configuration using the

"filter" sub-elements within the "filters" element.

- "republishing-enabled":

When enabled, an incoming event to a member is forwarded to target cluster of that member. Its

default value is true.

- "merge-policy":

Resolve conflicts that occurred when target cluster already has the replicated

entry key.

4 merge policy implementations for IMap and 2 merge policy implementations for

ICache are provided out-of-the-box.

IMap has the following merge policies:

com.hazelcast.map.merge.PutIfAbsentMapMergePolicy: Incoming entry merges from the

source map to the target map if it does not exist in the target map.

com.hazelcast.map.merge.HigherHitsMapMergePolicy: Incoming entry merges from the

source map to the target map if the source entry has more hits than the target one.

com.hazelcast.map.merge.PassThroughMergePolicy: Incoming entry merges from the

source map to the target map unless the incoming entry is not null.

com.hazelcast.map.merge.LatestUpdateMapMergePolicy: Incoming entry merges from the

source map to the target map if the source entry has been updated more recently

than the target entry. Please note that this merge policy can only be used when the

clusters' clocks are in sync.

ICache has the following merge policies:

com.hazelcast.cache.merge.HigherHitsCacheMergePolicy: Incoming entry merges from

the source cache to the target cache if the source entry has more hits than the

target one.

com.hazelcast.cache.merge.PassThroughCacheMergePolicy: Incoming entry merges from

the source cache to the target cache unless the incoming entry is not null.

* "indexes":

You can define indexes for your map using this element's "index" sub-elements. Each "index" has

only the boolean "ordered" attribute. For example, if you will have a ranged query for a field of a map

entry, then this attribute should be set to true. But if the field has a boolean value, then it should

be set to false. Its default value is false.

* "attributes":

You can define attributes that may be referenced in predicates, queries and indexes using this element's

"attribute" sub-elements. Each "attribute" has only the "extractor" attribute which you should define beforehand

by implementing Hazelcast's ValueExtractor class.

* "entry-listeners":

Adds listeners (listener classes) for the map entries using the "entry-listener" sub-elements. You can also set its

attribute "include-value" to true if you want the entry event to contain the item values, and you can set its attribute

"local" to true if you want to listen to the entries on the local member.

* "partition-lost-listeners":

Adds the partition lost listeners that you created by implementing Hazelcast's PartitionLostListener interface.

* "quorum-ref":

Adds the quorum for this map which you configure using the "quorum" element. You should set the "quorum-ref"'s value

as the "quorum"'s name.

map: default: in-memory-format: BINARY metadata-policy: CREATE_ON_UPDATE statistics-enabled: true optimize-queries: true cache-deserialized-values: ALWAYS backup-count: 1 async-backup-count: 0 time-to-live-seconds: 0 max-idle-seconds: 0 eviction-policy: NONE max-size: policy: PER_NODE max-size: 0 eviction-percentage: 25 min-eviction-check-millis: 100 merge-policy: batch-size: 100 class-name: PutIfAbsentMergePolicy read-backup-data: false hot-restart: enabled: false fsync: false map-store: enabled: true initial-mode: LAZY class-name: com.hazelcast.examples.DummyStore write-delay-seconds: 60 write-batch-size: 1000 write-coalescing: true properties: jdbc_url: my.jdbc.com near-cache: max-size: 5000 time-to-live-seconds: 0 max-idle-seconds: 60 eviction-policy: LRU invalidate-on-change: true in-memory-format: BINARY cache-local-entries: false eviction: size: 1000 max-size-policy: ENTRY_COUNT eviction-policy: LFU wan-replication-ref: my-wan-cluster-batch: merge-policy: com.hazelcast.map.merge.PassThroughMergePolicy filters: - com.example.SampleFilter - com.example.SampleFilter2 republishing-enabled: false indexes: name: ordered: false age: ordered: true attributes: currency: extractor: com.bank.CurrencyExtractor entry-listeners: - class-name: com.your-package.MyEntryListener include-value: false local: false partition-lost-listeners: - com.your-package.YourPartitionLostListener quorum-ref: quorumRuleWithThreeNodes