[jboss-user] [JBoss Cache] Document updated/added: "JBossCacheOptionsAPI"

[Manik Surtani]

User development,

The document "JBossCacheOptionsAPI", was updated Feb 22, 2010
by Manik Surtani.

To view the document, visit:
http://community.jboss.org/docs/DOC-10277#cf

Document:
--------------------------------------------------------------
h2.  JBossCache Options API
 
This API allows users to pass in configuration overrides on a per-invocation basis.  *Note:* Refer to the http://labs.jboss.com/portal/jbosscache/docs/index.html on the Option class for up-to-date information on the API available.
 
In *JBossCache 1.3.0 +"Wasabi"+* the following options are be supported:
 
* *cacheModeLocal* - overriding CacheMode from REPL_SYNC, REPL_ASYNC, INVALIDATION_SYNC, INVALIDATION_ASYNC to LOCAL.  Only applies to put() and remove() methods on the cache.
* *failSilently* - suppress any failures in your cache operation, including version mismatches with optimistic locking, timeouts obtaining locks, transaction rollbacks.  If this is option is set, the method invocation will *never fail or throw an exception*, although it may not succeed.  With this option enabled the call will *not* participate in any ongoing transactions even if a transaction is running.
* *dataVersion* - passing in an org.jboss.cache.optimistic.DataVersion instance when using optimistic locking will override the default behaviour of internally generated version info and allow the caller to handle data versioning.
 
Since *JBossCache 1.4.0 +"Jalapeno"+*:
 
* *suppressLocking* - Suppresses acquiring locks for the given invocation.  Used with pessimistic locking only.  Use with extreme care, may lead to a breach in data integrity!
* *forceDataGravitation* - enables data gravitation calls if a cache miss is detected when using http://community.jboss.org/docs/DOC-10256.  Enabled only for a given invocation, and only useful if autoDataGravitation is set to false.  See http://community.jboss.org/docs/DOC-10256 documentation for more details.
 
Since *JBossCache 2.0.0 +"Habanero"+*:
* *forceWriteLock* - set to force a write lock being obtained (only used with pessimistic locking) even if the call is a READ call.  Useful to emulate SELECT FOR UPDATE semantics.
 
> Note
> 
>  you only need to set the options you wish to use.  You may set one or more of the options, leave the ones you don't wish to use as unset.
 
See http://anoncvs.forge.jboss.com/viewrep/JBoss/JBossCache/src/org/jboss/cache/config/Option.java
 
h3.  Transactions
 
This new API does have specific behaviour when used in a transactional context, that users will need to be aware of:  
 
* The last method invocation before the transaction is committed or rolled back is consulted for the *cacheModeLocal* option.
* Whenever the *failSilently* option is used the method invocation does not participate in any ongoing transactions.  If a transaction is present, it is suspended, the method is invoked and then the transaction is resumed.
 
h2.  For JBossCache Interceptor authors
 
* Use Interceptor.getInvocationContext() to get a hold of an InvocationContext
* InvocationContext.getOptionOverrides() to get the Option object associated with a particular invocation.
** this may be null
 
h2.  The future
 
Future versions of JBossCache will have more override options available through this API, allowing you to configure locking, isolation levels, etc. on a more fine-grained basis. Watch this space!
 

--------------------------------------------------------------