[infinispan-commits] Infinispan SVN: r2106 - in branches/4.1.x: core/src/main/java/org/infinispan/context and 1 other directory.
infinispan-commits at lists.jboss.org
infinispan-commits at lists.jboss.org
Tue Jul 27 12:07:09 EDT 2010
Author: manik.surtani at jboss.com
Date: 2010-07-27 12:07:07 -0400 (Tue, 27 Jul 2010)
New Revision: 2106
Modified:
branches/4.1.x/client/hotrod-client/src/main/java/org/infinispan/client/hotrod/Flag.java
branches/4.1.x/core/src/main/java/org/infinispan/context/Flag.java
Log:
[ISPN-547] (Improve Flag documentation either in the ref doc or in JavaDoc)
Modified: branches/4.1.x/client/hotrod-client/src/main/java/org/infinispan/client/hotrod/Flag.java
===================================================================
--- branches/4.1.x/client/hotrod-client/src/main/java/org/infinispan/client/hotrod/Flag.java 2010-07-27 15:18:23 UTC (rev 2105)
+++ branches/4.1.x/client/hotrod-client/src/main/java/org/infinispan/client/hotrod/Flag.java 2010-07-27 16:07:07 UTC (rev 2106)
@@ -1,7 +1,9 @@
package org.infinispan.client.hotrod;
+import java.util.Map;
+
/**
- * Defines all the flags available in hotrod that can influence the behavior of operations.
+ * Defines all the flags available in the Hot Rod client that can influence the behavior of operations.
*
* @author Mircea.Markus at jboss.com
* @since 4.1
@@ -9,9 +11,11 @@
public enum Flag {
/**
- * By default, previously existing values for Map operations are not returned. E.g. remoteCache.put(k,v) does not return
- * the previous value associated with k. Passing this flag overrides default behavior and previous existing values are
- * returned.
+ * By default, previously existing values for {@link Map} operations are not returned. E.g. {@link RemoteCache#put(Object, Object)}
+ * does <i>not</i> return the previous value associated with the key
+ * <p />
+ * By applying this flag, this default behavior is overridden for the scope of a single invocation, and the previous
+ * existing value is returned.
*/
FORCE_RETURN_VALUE(0x0001);
Modified: branches/4.1.x/core/src/main/java/org/infinispan/context/Flag.java
===================================================================
--- branches/4.1.x/core/src/main/java/org/infinispan/context/Flag.java 2010-07-27 15:18:23 UTC (rev 2105)
+++ branches/4.1.x/core/src/main/java/org/infinispan/context/Flag.java 2010-07-27 16:07:07 UTC (rev 2106)
@@ -1,42 +1,108 @@
package org.infinispan.context;
import org.infinispan.Cache;
+import org.infinispan.config.Configuration;
+import org.infinispan.AdvancedCache;
+import org.infinispan.lifecycle.ComponentStatus;
+import org.infinispan.loaders.CacheStore;
/**
- * Available flags, which may be set on a per-invocation basis. These are provided using the {@link
- * org.infinispan.AdvancedCache} interface, using some of the overloaded methods that allow passing in of a variable
- * number of Flags.
+ * Available flags, which may be set on a per-invocation basis. These are provided using the {@link AdvancedCache}
+ * interface, using some of the overloaded methods that allow passing in of a variable number of Flags.
* <p/>
- * <ul> <li>{@link #ZERO_LOCK_ACQUISITION_TIMEOUT} - overrides the {@link org.infinispan.config.Configuration#setLockAcquisitionTimeout(long)}
- * configuration setting by ensuring lock managers use a 0 lock acquisition timeout.</li> <li>{@link #CACHE_MODE_LOCAL}
- * - forces local mode even if the cache is configured to use a clustered mode like replication, invalidation or
- * distribution</li> <li>{@link #SKIP_LOCKING} - bypasses lock acquisition altogether</li> <li>{@link #FORCE_WRITE_LOCK}
- * - forces a write lock, even if the call is a read. Useful when reading an entry to later update it within the same
- * transaction</li> <li>{@link #SKIP_CACHE_STATUS_CHECK} - skips checking whether a cache is in a receptive state, i.e.
- * is {@link org.infinispan.lifecycle.ComponentStatus#RUNNING}. May break operation in weird ways!</li> <li>{@link
- * #FORCE_ASYNCHRONOUS} - forces asynchronous network calls where possible</li> <li>{@link #FORCE_SYNCHRONOUS} - forces
- * synchronous network calls where possible</li> <li>{@link #SKIP_CACHE_STORE} - skips storing an entry to any
- * configured {@link org.infinispan.loaders.CacheStore}s</li> <li>{@link #FAIL_SILENTLY} - swallows any exceptions,
- * logging them instead at a low log level</li> <li>{@link #SKIP_REMOTE_LOOKUP} - when used with DIST cache mode, will
- * skip retrieving a remote value either when doing a get() or exists(), or to provide an overwritten value with a put()
- * or remove(). This could render return values for some operations (such as {@link org.infinispan.Cache#put(Object,
- * Object)} or {@link org.infinispan.Cache#remove(Object)} unusable.</li> <li> {@link #PUT_FOR_EXTERNAL_READ} - flags the
- * invocation as a {@link Cache#putForExternalRead(Object, Object)} call.</li></ul>
- *
+ * <ul>
+ * <li>{@link #ZERO_LOCK_ACQUISITION_TIMEOUT} - overrides the {@link 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 <i>if and only if</i> the lock is uncontended.</li>
+ * <li>{@link #CACHE_MODE_LOCAL} - forces LOCAL mode opersation, 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.</li>
+ * <li>{@link #SKIP_LOCKING} - bypasses lock acquisition for this invocation altogether. A potentially dangerous
+ * flag, as it can lead to inconsistent data.</li>
+ * <li>{@link #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 <tt>select ... for update ... </tt> SQL statement.</li>
+ * <li>{@link #SKIP_CACHE_STATUS_CHECK} - skips checking whether a cache is in a receptive state, i.e. is
+ * {@link ComponentStatus#RUNNING}. May break operation in weird ways!</li>
+ * <li>{@link #FORCE_ASYNCHRONOUS} - forces asynchronous network calls where possible, even if otherwise configured
+ * to use synchronous network calls. Only applicable to non-local, clustered caches.</li>
+ * <li>{@link #FORCE_SYNCHRONOUS} - forces synchronous network calls where possible, even if otherwise configured
+ * to use asynchronous network calls. Only applicable to non-local, clustered caches.</li>
+ * <li>{@link #SKIP_CACHE_STORE} - skips storing an entry to any configured {@link CacheStore}s.</li>
+ * <li>{@link #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.</li>
+ * <li>{@link #SKIP_REMOTE_LOOKUP} - when used with <b>distributed</b> 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 {@link Cache#put(Object, Object)} or {@link Cache#remove(Object)}
+ * unusable, in exchange for the performance gains of reducing remote calls.</li>
+ * <li> {@link #PUT_FOR_EXTERNAL_READ} - flags the invocation as a {@link Cache#putForExternalRead(Object, Object)}
+ * call, as opposed to a regular {@link Cache#put(Object, Object)}.</li>
+ * </ul>
* @author Manik Surtani
* @author Galder Zamarreño
* @since 4.0
*/
public enum Flag {
+ /**
+ * Overrides the {@link 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
+ * <i>if and only if</i> the lock is uncontended.
+ */
ZERO_LOCK_ACQUISITION_TIMEOUT,
+ /**
+ * Forces LOCAL mode opersation, 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.
+ */
CACHE_MODE_LOCAL,
+ /**
+ * Bypasses lock acquisition for this invocation altogether. A potentially dangerous flag, as it can lead to
+ * inconsistent data.
+ */
SKIP_LOCKING,
+ /**
+ * 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 <tt>select ... for update ... </tt>
+ * SQL statement.
+ */
FORCE_WRITE_LOCK,
+ /**
+ * Skips checking whether a cache is in a receptive state, i.e. is {@link ComponentStatus#RUNNING}. May break
+ * operation in weird ways!
+ */
SKIP_CACHE_STATUS_CHECK,
+ /**
+ * Forces asynchronous network calls where possible, even if otherwise configured to use synchronous network calls.
+ * Only applicable to non-local, clustered caches.
+ */
FORCE_ASYNCHRONOUS,
+ /**
+ * Forces synchronous network calls where possible, even if otherwise configured to use asynchronous network calls.
+ * Only applicable to non-local, clustered caches.
+ */
FORCE_SYNCHRONOUS,
+ /**
+ * Skips storing an entry to any configured {@link CacheStore}s.
+ */
SKIP_CACHE_STORE,
+ /**
+ * Swallows any exceptions, logging them instead at a low log level. Will prevent a failing operation from
+ * affecting any ongoing JTA transactions as well.
+ */
FAIL_SILENTLY,
+ /**
+ * When used with <b>distributed</b> 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 {@link Cache#put(Object, Object)} or {@link Cache#remove(Object)} unusable, in
+ * exchange for the performance gains of reducing remote calls.
+ */
SKIP_REMOTE_LOOKUP,
+
+ /**
+ * Flags the invocation as a {@link Cache#putForExternalRead(Object, Object)} call, as opposed to a regular
+ * {@link Cache#put(Object, Object)}.
+ */
PUT_FOR_EXTERNAL_READ
}
More information about the infinispan-commits
mailing list