Author: manik.surtani(a)jboss.com
Date: 2008-03-27 08:56:54 -0400 (Thu, 27 Mar 2008)
New Revision: 5466
Modified:
core/trunk/src/main/java/org/jboss/cache/Cache.java
core/trunk/src/main/java/org/jboss/cache/invocation/CacheInvocationDelegate.java
Log:
JBCACHE-1313 - Cache javadoc doesn't discuss behavior of non-started cache
Modified: core/trunk/src/main/java/org/jboss/cache/Cache.java
===================================================================
--- core/trunk/src/main/java/org/jboss/cache/Cache.java 2008-03-27 12:56:20 UTC (rev
5465)
+++ core/trunk/src/main/java/org/jboss/cache/Cache.java 2008-03-27 12:56:54 UTC (rev
5466)
@@ -151,8 +151,7 @@
* @param value value to be associated with the specified key.
* @return previous value associated with specified key, or
<code>null</code> if there was no mapping for key.
* A <code>null</code> return can also indicate that the Node
previously associated <code>null</code> with the specified key, if the
implementation supports null values.
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
V put(Fqn<?> fqn, K key, V value);
@@ -164,8 +163,7 @@
* @param value value to be associated with the specified key.
* @return previous value associated with specified key, or
<code>null</code> if there was no mapping for key.
* A <code>null</code> return can also indicate that the Node
previously associated <code>null</code> with the specified key, if the
implementation supports null values.
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
V put(String fqn, K key, V value);
@@ -193,8 +191,7 @@
* @param fqn <b><i>absolute</i></b> {@link Fqn} to the
{@link Node} to be accessed.
* @param key key with which the specified value is to be associated.
* @param value value to be associated with the specified key.
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
void putForExternalRead(Fqn<?> fqn, K key, V value);
@@ -203,15 +200,14 @@
*
* @param fqn <b><i>absolute</i></b> {@link Fqn} to the
{@link Node} to copy the data to
* @param data mappings to copy
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
void put(Fqn<?> fqn, Map<K, V> data);
/**
* Convenience method that takes a string representation of an Fqn. Otherwise
identical to {@link #put(Fqn, java.util.Map)}
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ *
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
void put(String fqn, Map<K, V> data);
@@ -223,15 +219,14 @@
* @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link
Node} to be accessed.
* @param key key whose mapping is to be removed from the Node
* @return previous value associated with specified Node's key
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
V remove(Fqn<?> fqn, K key);
/**
* Convenience method that takes a string representation of an Fqn. Otherwise
identical to {@link #remove(Fqn, Object)}
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ *
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
V remove(String fqn, K key);
@@ -240,15 +235,14 @@
*
* @param fqn {@link Node} to remove
* @return true if the node was removed, false if the node was not found
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
- */
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ */
boolean removeNode(Fqn<?> fqn);
/**
* Convenience method that takes a string representation of an Fqn. Otherwise
identical to {@link #removeNode(Fqn)}
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ *
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
boolean removeNode(String fqn);
@@ -257,15 +251,14 @@
*
* @param fqn fqn of the node to retrieve
* @return a Node object, or a null if the node does not exist.
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
Node<K, V> getNode(Fqn<?> fqn);
/**
* Convenience method that takes a string representation of an Fqn. Otherwise
identical to {@link #getNode(Fqn)}
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ *
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
Node<K, V> getNode(String fqn);
@@ -276,15 +269,14 @@
* @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link
Node} to be accessed.
* @param key key under which value is to be retrieved.
* @return returns data held under specified key in {@link Node} denoted by specified
Fqn.
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
V get(Fqn<?> fqn, K key);
/**
* Convenience method that takes a string representation of an Fqn. Otherwise
identical to {@link #get(Fqn, Object)}
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ *
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
V get(String fqn, K key);
@@ -293,8 +285,7 @@
*
* @param fqn <b><i>absolute</i></b> {@link Fqn} to the
{@link Node} to be evicted.
* @param recursive evicts children as well
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
void evict(Fqn<?> fqn, boolean recursive);
@@ -302,8 +293,7 @@
* Eviction call that evicts the specified {@link Node} from memory. Not recursive.
*
* @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link
Node} to be evicted.
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
*/
void evict(Fqn<?> fqn);
@@ -369,6 +359,7 @@
/**
* @return the current invocation context for the current invocation and cache
instance.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus#STARTED}.
* @see org.jboss.cache.InvocationContext
*/
InvocationContext getInvocationContext();
@@ -377,6 +368,7 @@
* Sets the passed in {@link org.jboss.cache.InvocationContext} as current.
*
* @param ctx invocation context to use
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus#STARTED}.
*/
void setInvocationContext(InvocationContext ctx);
@@ -443,15 +435,14 @@
* @param nodeToMove the Fqn of the node to move.
* @param newParent new location under which to attach the node being moved.
* @throws NodeNotExistsException may throw one of these if the target node does not
exist or if a different thread has moved this node elsewhere already.
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus#STARTED}.
*/
void move(Fqn<?> nodeToMove, Fqn<?> newParent) throws
NodeNotExistsException;
/**
* Convenience method that takes in string representations of Fqns. Otherwise
identical to {@link #move(Fqn, Fqn)}
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ *
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus#STARTED}.
*/
void move(String nodeToMove, String newParent) throws NodeNotExistsException;
@@ -470,8 +461,7 @@
* @param fqn
* @return map of data, or an empty map
* @throws CacheException
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus#STARTED}.
*/
Map<K, V> getData(Fqn<?> fqn);
@@ -489,15 +479,14 @@
* getting keys from the node directly.
*
* @param fqn name of the node
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus#STARTED}.
*/
Set<K> getKeys(Fqn<?> fqn);
/**
- * Convenience method that takes in a String represenation of the Fqn. Otherwise
identical to {@link #removeData(Fqn)}.
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * Convenience method that takes in a String represenation of the Fqn. Otherwise
identical to {@link #clearData(Fqn)}.
+ *
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus#STARTED}.
*/
void clearData(String fqn);
@@ -508,8 +497,7 @@
* getting keys from the node directly.
*
* @param fqn name of the node
- *
- * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus.STARTED}.
+ * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link
CacheStatus#STARTED}.
*/
void clearData(Fqn<?> fqn);
Modified:
core/trunk/src/main/java/org/jboss/cache/invocation/CacheInvocationDelegate.java
===================================================================
---
core/trunk/src/main/java/org/jboss/cache/invocation/CacheInvocationDelegate.java 2008-03-27
12:56:20 UTC (rev 5465)
+++
core/trunk/src/main/java/org/jboss/cache/invocation/CacheInvocationDelegate.java 2008-03-27
12:56:54 UTC (rev 5466)
@@ -274,11 +274,14 @@
public InvocationContext getInvocationContext()
{
+ if (!getCacheStatus().allowInvocations()) throw new
IllegalStateException("Cache not in STARTED state!");
return invocationContextContainer.get();
}
public void setInvocationContext(InvocationContext ctx)
{
+ if (!getCacheStatus().allowInvocations()) throw new
IllegalStateException("Cache not in STARTED state!");
+
// assume a null ctx is meant to "un-set" the context?
if (ctx == null) invocationContextContainer.remove();
else invocationContextContainer.set(ctx);