[jbosscache-commits] JBoss Cache SVN: r5457 - core/trunk/src/main/java/org/jboss/cache.

Author: bstansberry(a)jboss.com Date: 2008-03-22 23:07:30 -0400 (Sat, 22 Mar 2008) New Revision: 5457 Modified: core/trunk/src/main/java/org/jboss/cache/Cache.java Log: [JBCACHE-1313] Document the ISEs that get thrown when cache isn't started. Modified: core/trunk/src/main/java/org/jboss/cache/Cache.java =================================================================== --- core/trunk/src/main/java/org/jboss/cache/Cache.java 2008-03-23 01:22:15 UTC (rev 5456) +++ core/trunk/src/main/java/org/jboss/cache/Cache.java 2008-03-23 03:07:30 UTC (rev 5457) @@ -151,6 +151,8 @@ * @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}. */ V put(Fqn<?> fqn, K key, V value); @@ -162,6 +164,8 @@ * @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}. */ V put(String fqn, K key, V value); @@ -189,6 +193,8 @@ * @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}. */ void putForExternalRead(Fqn<?> fqn, K key, V value); @@ -197,11 +203,15 @@ * * @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}. */ 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}. */ void put(String fqn, Map<K, V> data); @@ -213,11 +223,15 @@ * @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}. */ 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}. */ V remove(String fqn, K key); @@ -226,11 +240,15 @@ * * @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}. + */ 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}. */ boolean removeNode(String fqn); @@ -239,11 +257,15 @@ * * @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}. */ 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}. */ Node<K, V> getNode(String fqn); @@ -254,11 +276,15 @@ * @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}. */ 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}. */ V get(String fqn, K key); @@ -267,6 +293,8 @@ * * @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}. */ void evict(Fqn<?> fqn, boolean recursive); @@ -274,6 +302,8 @@ * 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}. */ void evict(Fqn<?> fqn); @@ -413,11 +443,15 @@ * @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}. */ 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}. */ void move(String nodeToMove, String newParent) throws NodeNotExistsException; @@ -436,6 +470,8 @@ * @param fqn * @return map of data, or an empty map * @throws CacheException + * + * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link CacheStatus.STARTED}. */ Map<K, V> getData(Fqn<?> fqn); @@ -453,11 +489,15 @@ * getting keys from the node directly. * * @param fqn name of the node + * + * @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}. */ void clearData(String fqn); @@ -468,6 +508,8 @@ * getting keys from the node directly. * * @param fqn name of the node + * + * @throws IllegalStateException if {@link #getCacheStatus()} would not return {@link CacheStatus.STARTED}. */ void clearData(Fqn<?> fqn);