org.infinispan.context

Enum Flag

java.lang.Object

java.lang.Enum<Flag>

org.infinispan.context.Flag

All Implemented Interfaces:

Serializable, Comparable<Flag>

public enum Flag
extends Enum<Flag>

Available flags, which may be set on a per-invocation basis. These are provided using the AdvancedCache interface, using some of the overloaded methods that allow passing in of a variable number of Flags. When making modifications to these enum, do not change the order of enumerations, so always append any new enumerations after the last one. Finally, enumerations should not be removed.

Since:

4.0

Author:

Manik Surtani, Galder Zamarreño

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Flag.Externalizer

Enum Constant Summary

Enum Constants

Enum Constant and Description
CACHE_MODE_LOCAL Forces LOCAL mode operation, even if the cache is configured to use a clustered mode like replication, invalidation or distribution.
COMMAND_RETRY If a write operation encounters a retry due to a topology change this flag should be used to tell the new owner that such a thing happened.
DELTA_WRITE Signals when a particular cache write operation is writing a delta of the object, rather than the full object.
FAIL_SILENTLY Swallows any exceptions, logging them instead at a low log level.
FORCE_ASYNCHRONOUS Forces asynchronous network calls where possible, even if otherwise configured to use synchronous network calls.
FORCE_SYNCHRONOUS Forces synchronous network calls where possible, even if otherwise configured to use asynchronous network calls.
FORCE_WRITE_LOCK Forces a write lock, even if the invocation is a read operation.
GUARANTEED_DELIVERY Using a synchronous cache (whether replicated or distributed) provides the cache caller guarantees that data has been sent to other cluster nodes correctly and has been applied successfully.
IGNORE_RETURN_VALUES Signals that an operation's return value will be ignored.
OPERATION_HOTROD Flag to identify cache operations coming from the Hot Rod server.
OPERATION_MEMCACHED Flag to identify cache operations coming from the Memcached server.
PUT_FOR_EXTERNAL_READ Flags the invocation as a Cache.putForExternalRead(Object, Object) call, as opposed to a regular BasicCache.put(Object, Object).
PUT_FOR_STATE_TRANSFER Flags the invocation as a put operation done internally by the state transfer.
PUT_FOR_X_SITE_STATE_TRANSFER Flags the invocation as a put operation done internally by the cross-site state transfer.
REMOVE_DATA_ON_STOP Deprecated. No longer in use.
SKIP_CACHE_LOAD Skips loading an entry from any configured CacheLoaders.
SKIP_CACHE_STATUS_CHECK Deprecated. This flag is no longer in use.
SKIP_CACHE_STORE Skips storing an entry to any configured CacheLoaders.
SKIP_INDEX_CLEANUP Any time a new indexed entry is inserted, a delete statement is issued on the indexes to remove previous values.
SKIP_INDEXING Used by the Query module only, it will prevent the indexes to be updated as a result of the current operations.
SKIP_LISTENER_NOTIFICATION This flag skips listener notifications as a result of a cache operation.
SKIP_LOCKING Bypasses lock acquisition for this invocation altogether.
SKIP_OWNERSHIP_CHECK Used by the DistLockingInterceptor to commit the change no matter what (if the flag is set).
SKIP_REMOTE_LOOKUP When used with distributed cache mode, will prevent retrieving a remote value either when executing a get() or exists(), or to provide an overwritten return value for a put() or remove().
SKIP_SHARED_CACHE_STORE If this flag is enabled, if a cache store is shared, then storage to the store is skipped.
SKIP_STATISTICS This flag skips statistics updates as a result of a cache operation.
SKIP_XSITE_BACKUP If cross-site replication is enabled, this would skip the replication to any remote site.
ZERO_LOCK_ACQUISITION_TIMEOUT Overrides the Configuration#setLockAcquisitionTimeout(long) configuration setting by ensuring lock managers use a 0-millisecond lock acquisition timeout.

Method Summary

Methods

Modifier and Type	Method and Description
static Set<Flag>	copyWithoutRemotableFlags(Set<Flag> flags) Creates a copy of a Flag Set removing instances of FAIL_SILENTLY.
static Flag	valueOf(String name) Returns the enum constant of this type with the specified name.
static Flag[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

ZERO_LOCK_ACQUISITION_TIMEOUT

public static final Flag ZERO_LOCK_ACQUISITION_TIMEOUT

Overrides the Configuration#setLockAcquisitionTimeout(long) configuration setting by ensuring lock managers use a 0-millisecond lock acquisition timeout. Useful if you only want to acquire a lock on an entry if and only if the lock is uncontended.

CACHE_MODE_LOCAL

public static final Flag CACHE_MODE_LOCAL

Forces LOCAL mode operation, even if the cache is configured to use a clustered mode like replication, invalidation or distribution. Applying this flag will suppress any RPC messages otherwise associated with this invocation. Write operations mat not acquire the entry locks. In distributed mode, the modifications performed during an operation in a non-owner node are going to L1, if it is enabled, otherwise the operation is a no-op in that node.

SKIP_LOCKING

public static final Flag SKIP_LOCKING

Bypasses lock acquisition for this invocation altogether. A potentially dangerous flag, as it can lead to inconsistent data: a Lock is needed to make sure the same value is written to each node replica; a lock is also needed to guarantee that several writes on the same key are not applied out of order to an async CacheLoader storage engine. So this flag is useful only as an optimization when the same key is written once and never again, or as an unsafe optimisation if the period between writes on the same key is large enough to make a race condition never happen in practice. If this is unclear, avoid it.

FORCE_WRITE_LOCK

public static final Flag FORCE_WRITE_LOCK

Forces a write lock, even if the invocation is a read operation. Useful when reading an entry to later update it within the same transaction, and is analogous in behavior and use case to a select ... for update ... SQL statement.

SKIP_CACHE_STATUS_CHECK

@Deprecated
public static final Flag SKIP_CACHE_STATUS_CHECK

Deprecated. This flag is no longer in use.

Skips checking whether a cache is in a receptive state, i.e. is ComponentStatus.RUNNING. May break operation in weird ways!

FORCE_ASYNCHRONOUS

public static final Flag FORCE_ASYNCHRONOUS

Forces asynchronous network calls where possible, even if otherwise configured to use synchronous network calls. Only applicable to non-local, clustered caches.

FORCE_SYNCHRONOUS

public static final Flag FORCE_SYNCHRONOUS

Forces synchronous network calls where possible, even if otherwise configured to use asynchronous network calls. Only applicable to non-local, clustered caches.

SKIP_CACHE_STORE

public static final Flag SKIP_CACHE_STORE

Skips storing an entry to any configured CacheLoaders.

SKIP_CACHE_LOAD

public static final Flag SKIP_CACHE_LOAD

Skips loading an entry from any configured CacheLoaders. Useful for example to perform a put() operation while not interested in the return value of put() which would return the eventually existing previous value.
Note that if you want to ignore the return value of put() and you are in distributed mode you should also use the SKIP_REMOTE_LOOKUP flag.

FAIL_SILENTLY

public static final Flag FAIL_SILENTLY

Swallows any exceptions, logging them instead at a low log level. Will prevent a failing operation from affecting any ongoing JTA transactions as well.

This Flag will not be replicated to remote nodes, but it will still protect the invoker from remote exceptions.

SKIP_REMOTE_LOOKUP

public static final Flag SKIP_REMOTE_LOOKUP

When used with distributed cache mode, will prevent retrieving a remote value either when executing a get() or exists(), or to provide an overwritten return value for a put() or remove(). This would render return values for some operations (such as BasicCache.put(Object, Object) or BasicCache.remove(Object) unusable, in exchange for the performance gains of reducing remote calls.
Note that if you want to ignore the return value of put() and you have configured a cache store you should also use the SKIP_CACHE_LOAD flag.

SKIP_INDEXING

public static final Flag SKIP_INDEXING

Used by the Query module only, it will prevent the indexes to be updated as a result of the current operations.

PUT_FOR_EXTERNAL_READ

public static final Flag PUT_FOR_EXTERNAL_READ

Flags the invocation as a Cache.putForExternalRead(Object, Object) call, as opposed to a regular BasicCache.put(Object, Object). This flag was created purely for internal Infinispan usage, and should not be used by clients calling into Infinispan.

PUT_FOR_STATE_TRANSFER

public static final Flag PUT_FOR_STATE_TRANSFER

Flags the invocation as a put operation done internally by the state transfer. This flag was created purely for internal Infinispan usage, and should not be used by clients calling into Infinispan.

PUT_FOR_X_SITE_STATE_TRANSFER

public static final Flag PUT_FOR_X_SITE_STATE_TRANSFER

Flags the invocation as a put operation done internally by the cross-site state transfer. This flag was created purely for internal Infinispan usage, and should not be used by clients calling into Infinispan.

SKIP_SHARED_CACHE_STORE

public static final Flag SKIP_SHARED_CACHE_STORE

If this flag is enabled, if a cache store is shared, then storage to the store is skipped.

REMOVE_DATA_ON_STOP

@Deprecated
public static final Flag REMOVE_DATA_ON_STOP

Deprecated. No longer in use.

This flag has only effect when it's used before calling Lifecycle.stop() and its effect is that apart from stopping the cache, it removes all of its content from both memory and any backing cache store.

SKIP_OWNERSHIP_CHECK

public static final Flag SKIP_OWNERSHIP_CHECK

Used by the DistLockingInterceptor to commit the change no matter what (if the flag is set). This is used when a node A pushes state to another node B and A doesn't want B to check if the state really belongs to it

DELTA_WRITE

public static final Flag DELTA_WRITE

Signals when a particular cache write operation is writing a delta of the object, rather than the full object. This can be useful in order to make decisions such as whether the cache store needs checking to see if the previous value needs to be loaded and merged.

IGNORE_RETURN_VALUES

public static final Flag IGNORE_RETURN_VALUES

Signals that an operation's return value will be ignored. Typical operations whose return value might be ignored include Map.put(Object, Object) whose return value indicates previous value. So, a user might decide to the put something in the cache but might not be interested in the return value. This flag is ignored with the conditional remove (ConcurrentMap.remove(Object, Object)) and conditional replace (ConcurrentMap.replace(Object, Object, Object)) operations which return a boolean result: this has a minimal serialization payload and is generally relevant in order to determine whether the operation was successful or not. Not requiring return values makes the cache behave more efficiently by applying flags such as SKIP_REMOTE_LOOKUP or SKIP_CACHE_LOAD.

SKIP_XSITE_BACKUP

public static final Flag SKIP_XSITE_BACKUP

If cross-site replication is enabled, this would skip the replication to any remote site.

GUARANTEED_DELIVERY

public static final Flag GUARANTEED_DELIVERY

Using a synchronous cache (whether replicated or distributed) provides the cache caller guarantees that data has been sent to other cluster nodes correctly and has been applied successfully. At the network level, message delivery acknowledgement protocols are used to provide these guarantees. In order to increase performance and achieve better throughput, it's common to use negative acknowledgment protocols to confirm the delivery of messages. The problem with these protocols is that if the last message is lost, it can be difficult to recover it because a new message would need to be sent to find the gap. Some cache use cases might involve storing an entry in a synchronously replicated or distributed cache, and if that store operation fails, the application fails to start. One such example is the Infinispan Hot Rod server. When it starts, the first thing it does is add its endpoint information to a cache which is used to notify clients of topology changes. If this operation fails, the server cannot start because topologies won't include this node, and no more cache operations are attempted. So, in exceptional use cases such as this, a cluster wide cache update should be positively acknowledged by the other nodes, so that if the data is lost, it can be retransmitted immediately without the need to wait for an extra cluster wide operation to detect the lost message. The way to force a particular cache operation to be positively acknowledged is to send this GUARANTEED_DELIVERY flag. Note that this is flag is EXPERIMENTAL and so there is a high probability that it will be removed in future Infinispan versions.

SKIP_LISTENER_NOTIFICATION

public static final Flag SKIP_LISTENER_NOTIFICATION

This flag skips listener notifications as a result of a cache operation. For example, if this flag is passed as a result of a Map.get(Object) call, no callbacks will be made on listeners annotated with CacheEntryVisited.

SKIP_STATISTICS

public static final Flag SKIP_STATISTICS

This flag skips statistics updates as a result of a cache operation. For example, if this flag is passed as a result of a Map.get(Object) call, no cache hits or cache miss counters will be updated.

OPERATION_HOTROD

public static final Flag OPERATION_HOTROD

Flag to identify cache operations coming from the Hot Rod server.

OPERATION_MEMCACHED

public static final Flag OPERATION_MEMCACHED

Flag to identify cache operations coming from the Memcached server.

SKIP_INDEX_CLEANUP

public static final Flag SKIP_INDEX_CLEANUP

Any time a new indexed entry is inserted, a delete statement is issued on the indexes to remove previous values. This delete statement is executed even if there is no known entry having the same key. Enable this flag when you know for sure there is no existing entry in the index for improved performance. For example, this is useful for speeding up import of new data in an empty cache having an empty index.

COMMAND_RETRY

public static final Flag COMMAND_RETRY

If a write operation encounters a retry due to a topology change this flag should be used to tell the new owner that such a thing happened. This flag was created purely for internal Infinispan usage, and should not be used by clients calling into Infinispan.

Method Detail

values

public static Flag[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (Flag c : Flag.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static Flag valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

copyWithoutRemotableFlags

public static Set<Flag> copyWithoutRemotableFlags(Set<Flag> flags)

Creates a copy of a Flag Set removing instances of FAIL_SILENTLY. The copy might be the same instance if no change is required, and should be considered immutable.

Parameters:

flags -

Returns:

might return the same instance