Author: manik.surtani(a)jboss.com Date: 2008-04-28 14:31:24 -0400 (Mon, 28 Apr 2008) New Revision: 5735 Modified: core/trunk/src/main/java/org/jboss/cache/DataContainer.java core/trunk/src/main/java/org/jboss/cache/LifecycleManager.java core/trunk/src/main/java/org/jboss/cache/invocation/CacheInvocationDelegate.java core/trunk/src/main/java/org/jboss/cache/marshall/CommandAwareRpcDispatcher.java core/trunk/src/main/java/org/jboss/cache/transaction/GlobalTransactionContainer.java Log: Javadoc and method naming Modified: core/trunk/src/main/java/org/jboss/cache/DataContainer.java =================================================================== --- core/trunk/src/main/java/org/jboss/cache/DataContainer.java 2008-04-28 17:27:58 UTC (rev 5734) +++ core/trunk/src/main/java/org/jboss/cache/DataContainer.java 2008-04-28 18:31:24 UTC (rev 5735) @@ -6,6 +6,7 @@ import org.jboss.cache.buddyreplication.BuddyManager; import org.jboss.cache.config.Configuration; import org.jboss.cache.factories.annotations.Inject; +import org.jboss.cache.factories.annotations.Start; import org.jboss.cache.marshall.NodeData; import org.jboss.cache.optimistic.DataVersion; import org.jboss.cache.transaction.GlobalTransaction; @@ -18,15 +19,16 @@ import java.util.Set; /** - * A container for the root node in the cache - should be used to access any nodes, walk trees, etc. + * A container for the root node in the cache, which also provides helpers for efficiently accessing nodes, walking trees, etc. * * @author Mircea.Markus(a)jboss.com * @since 2.2 */ public class DataContainer { - + // TODO: 2.2.0: Refactor and standardise method names, consolidate where possible. A lot of these can be moved into commands. private static final Log log = LogFactory.getLog(DataContainer.class); + private static boolean trace; private Configuration configuration; @@ -35,18 +37,30 @@ */ private NodeSPI root; + @Inject public void injectDependencies(Configuration configuration) { this.configuration = configuration; } + @Start + public void start() + { + trace = log.isTraceEnabled(); + } + /** * Set<Fqn> of Fqns of the topmost node of internal regions that should * not included in standard state transfers. */ private final Set<Fqn> internalFqns = new HashSet<Fqn>(); + /** + * Adds the specified Fqn to the list of Fqns to be considered "internal". + * + * @param fqn fqn to add to list + */ public void registerInternalFqn(Fqn fqn) { internalFqns.add(fqn); @@ -90,21 +104,37 @@ return findNode(fqn, version, false); } + /** + * Similar to {@link #findNode(Fqn, org.jboss.cache.optimistic.DataVersion)} except that it throws a {@link org.jboss.cache.NodeNotExistsException} + * if the node cannot be found. + * + * @param tx global transaction + * @param fqn fqn to fine + * @param includeInvalid if true, invalid nodes are considered as well. + * @return the node + */ public NodeSPI findNodeCheck(GlobalTransaction tx, Fqn fqn, boolean includeInvalid) { NodeSPI n = findNode(fqn, null, includeInvalid); if (n == null) { - String errStr = "node " + fqn + " not found (globalTransaction=" + tx + ", caller=" + Thread.currentThread() + ")"; - if (log.isTraceEnabled()) - { - log.trace(errStr); - } + StringBuilder builder = new StringBuilder(); + builder.append("Node ").append(fqn).append(" not found (gtx=").append(tx).append(")"); + String errStr = builder.toString(); + if (trace) log.trace(errStr); throw new NodeNotExistsException(errStr); } return n; } + /** + * Searches for a specific node. + * + * @param fqn Fqn to find + * @param version version of the node to find + * @param includeInvalidNodes if true, invalid nodes are considered + * @return the node, if found, or null otherwise. + */ public NodeSPI findNode(Fqn fqn, DataVersion version, boolean includeInvalidNodes) { if (fqn == null) return null; @@ -115,7 +145,7 @@ { // we need to check the version of the data node... DataVersion nodeVersion = toReturn.getVersion(); - if (log.isTraceEnabled()) + if (trace) { log.trace("looking for optimistic node [" + fqn + "] with version [" + version + "]. My version is [" + nodeVersion + "]"); } @@ -128,7 +158,14 @@ return toReturn; } - + /** + * Peeks for a specified node. + * + * @param fqn Fqn of the node to find + * @param includeDeletedNodes if true, deleted nodes are also considered + * @param includeInvalidNodes if true, invalid nodes are also considered + * @return the node, if found, or null otherwise. + */ public NodeSPI peek(Fqn<?> fqn, boolean includeDeletedNodes, boolean includeInvalidNodes) { if (fqn == null || fqn.size() == 0) return getRoot(); @@ -154,7 +191,13 @@ return n; } - + /** + * Prepares a list of {@link NodeData} objects for a specified node and all its children. + * + * @param list List of NodeData objects, which will be added to. + * @param node node to recursively add to the list + * @return the same list passed in + */ public List<NodeData> getNodeData(List<NodeData> list, NodeSPI node) { NodeData data = new NodeData(BuddyFqnTransformer.getActualFqn(node.getFqn()), node.getDataDirect()); @@ -166,14 +209,23 @@ return list; } - + /** + * Same as calling <tt>peek(fqn, includeDeletedNodes, false)</tt>. + * + * @param fqn Fqn to find + * @param includeDeletedNodes if true, deleted nodes are considered + * @return the node, if found, or null otherwise. + */ public NodeSPI peek(Fqn<?> fqn, boolean includeDeletedNodes) { return peek(fqn, includeDeletedNodes, false); } /** - * Returns true if the FQN exists and the node has children. + * Returns true if the Fqn exists and the node has children. + * + * @param fqn the fqn to test + * @return true if the Fqn exists and the node has children. */ public boolean hasChild(Fqn fqn) { @@ -183,16 +235,26 @@ return n != null && n.hasChildrenDirect(); } - + /** + * @return the root node + */ public NodeSPI getRoot() { return root; } - public List<Fqn> getNodesForEviction(Fqn parent, boolean recursive) + /** + * Generates a list of nodes for eviction. This filters out nodes that cannot be evicted, such as those which are + * marked as resident. See {@link NodeSPI#setResident(boolean)}. + * + * @param fqn the node to consider for eviction + * @param recursive if recursive, child nodes are also considered + * @return a list of Fqns that can be considered for eviction + */ + public List<Fqn> getNodesForEviction(Fqn fqn, boolean recursive) { List<Fqn> result = new ArrayList<Fqn>(); - NodeSPI node = peek(parent, false); + NodeSPI node = peek(fqn, false); if (recursive) { recursiveAddEvictionNodes(node, result); @@ -201,7 +263,7 @@ { if (node == null) { - result.add(parent); + result.add(fqn); return result; } buildNodesForEviction(node, result); @@ -244,6 +306,12 @@ return toString(false); } + /** + * Tests if an Fqn exists and is valid and not deleted. + * + * @param fqn the fqn representing the node to test + * @return true if the node exists, false otherwise. + */ public boolean exists(Fqn fqn) { return peek(fqn, false, false) != null; @@ -401,10 +469,11 @@ } /** - * Internal method; not to be used externally. - * Returns true if the node was found, false if not. + * Removes the actual node from the tree data structure. * - * @param f + * @param f the Fqn of the node to remove + * @param skipMarkerCheck if true, skips checking the boolean {@link org.jboss.cache.NodeSPI#isDeleted()} flag and deletes the node anyway. + * @return Returns true if the node was found and removed, false if not. */ public boolean realRemove(Fqn f, boolean skipMarkerCheck) { @@ -415,7 +484,7 @@ } - if (log.isTraceEnabled()) log.trace("Performing a real remove for node " + f + ", marked for removal."); + if (trace) log.trace("Performing a real remove for node " + f + ", marked for removal."); if (skipMarkerCheck || n.isDeleted()) { if (n.getFqn().isRoot()) @@ -457,21 +526,21 @@ /** * @return true if the FQN is leaf and was removed; false if is an intermediate FQN and only contained data - * is droped. + * is droped. */ public boolean evict(Fqn fqn) { if (peek(fqn, false, true) == null) return true; if (hasChild(fqn)) { - if (log.isTraceEnabled()) + if (trace) log.trace("removing DATA as node has children: evict(" + fqn + ")"); removeData(fqn); return false; } else { - if (log.isTraceEnabled()) + if (trace) log.trace("removing NODE as it is a leaf: evict(" + fqn + ")"); removeNode(fqn); return true; @@ -555,7 +624,7 @@ NodeSPI childNode = n.addChildDirect(Fqn.fromElements(childName)); if (childNode == null) { - if (log.isTraceEnabled()) + if (trace) { log.trace("failed to find or create child " + childName + " of node " + n.getFqn()); } Modified: core/trunk/src/main/java/org/jboss/cache/LifecycleManager.java =================================================================== --- core/trunk/src/main/java/org/jboss/cache/LifecycleManager.java 2008-04-28 17:27:58 UTC (rev 5734) +++ core/trunk/src/main/java/org/jboss/cache/LifecycleManager.java 2008-04-28 18:31:24 UTC (rev 5735) @@ -18,6 +18,15 @@ import java.util.ArrayList; /** + * Added in 2.2.0 to handle the lifecycle of the cache. I.e., to control the starting and stopping process, as defined + * by the {@link org.jboss.cache.Cache#start()} and {@link org.jboss.cache.Cache#stop()} API methods. + * <p/> + * This class also acts as a container for the {@link ComponentRegistry}, which it constructs in its constructor + * as a place to hold all components of a given cache instance. + * <p/> + * It also holds the status of the cache, which can be queried. + * <p/> + * * @author Mircea.Markus(a)jboss.com * @since 2.2 */ @@ -63,6 +72,12 @@ */ private boolean invokedFromShutdownHook; + /** + * Constructs a new instance, also constructs a {@link org.jboss.cache.factories.ComponentRegistry} instance which can + * then be retrieved using {@link #getComponentRegistry()}. When constructed, the cache status is set to {@link org.jboss.cache.CacheStatus#INSTANTIATED}. + * + * @param configuration with which to create this class. + */ public LifecycleManager(Configuration configuration) { this.configuration = configuration; @@ -71,9 +86,10 @@ } /** - * Lifecycle method. This is like initialize. + * Creates the components needed by a cache instance and sets the cache status to {@link org.jboss.cache.CacheStatus#CREATED} + * when it is done. * - * @throws Exception + * @throws CacheException if there is a problem with construction. */ public void create() throws CacheException { @@ -95,9 +111,14 @@ } /** - * Lifecyle method. + * Starts the components needed by a cache instance, and then starts the cache instance itself. Sets the cache status to + * {@link org.jboss.cache.CacheStatus#STARTED} once it is done. + * <p/> + * If the cache status is not {@link org.jboss.cache.CacheStatus#CREATED} when this is called, it will first call {@link #create()} + * to create the cache. + * <p/> * - * @throws CacheException + * @throws CacheException if there is a problem with starting the cache. */ public void start() throws CacheException { @@ -124,7 +145,10 @@ } /** - * Lifecycle method. + * Destroys the cache and frees up any resources. Sets the cache status to {@link CacheStatus#DESTROYED} when it is done. + * <p/> + * If the cache is in {@link org.jboss.cache.CacheStatus#STARTED} when this method is called, it will first call {@link #stop()} + * to stop the cache. */ public void destroy() { @@ -158,7 +182,8 @@ } /** - * Lifecycle method. + * Stops the cache and sets the cache status to {@link org.jboss.cache.CacheStatus#STOPPED} once it is done. If the cache is not in + * the {@link org.jboss.cache.CacheStatus#STARTED} state, this is a no-op. */ public void stop() { @@ -412,7 +437,7 @@ log = LogFactory.getLog(category.toString()); } - public void startManualComponents() + private void startManualComponents() { // these 2 components need to be started manually since they can only be started after ALL other components have started. // i.e., rpcManager's start() method may do state transfers. State transfers will rely on the interceptor chain being started. @@ -430,19 +455,22 @@ } /** - * For local calls, if chache is not in STARTED mode will throw an IllegalStateException. - * For remote cache, if cache is STRTED returns true. If cache is STARTING waits for the cache to wait - * for {@link org.jboss.cache.config.Configuration#getStateRetrievalTimeout()} milliseconds, if cache starts - * returns true, otherwise returns false. + * Asserts whether invocations are allowed on the cache or not. Returns <tt>true</tt> if invocations are to be allowed, + * <tt>false</tt> otherwise. If the origin of the call is remote and the cache status is {@link org.jboss.cache.CacheStatus#STARTING}, + * this method will block for up to {@link org.jboss.cache.config.Configuration#getStateRetrievalTimeout()} millis, checking + * for a valid state. + * + * @param originLocal true if the call originates locally (i.e., from the {@link org.jboss.cache.invocation.CacheInvocationDelegate} or false if it originates remotely, i.e., from the {@link org.jboss.cache.marshall.CommandAwareRpcDispatcher}. + * @return true if invocations are allowed, false otherwise. */ - public boolean allowsInvocation(boolean originLocal) + public boolean invocationsAllowed(boolean originLocal) { if (getCacheStatus().allowInvocations()) return true; - // only throw an exception if this is a locally originating call - JBCACHE-1179 - if (originLocal) - { - throw new IllegalStateException("Cache not in STARTED state!"); - } + + // if this is a locally originating call and the cache is not in a valid state, return false. + if (originLocal) return false; + + // else if this is a remote call and the status is STARTING, wait until the cache starts. if (getCacheStatus() == CacheStatus.STARTING) { try @@ -487,7 +515,6 @@ throw new IllegalStateException("Cache not in STARTED state, even after waiting " + configuration.getStateRetrievalTimeout() + " millis."); } - public CacheStatus getCacheStatus() { return cacheStatus; Modified: core/trunk/src/main/java/org/jboss/cache/invocation/CacheInvocationDelegate.java =================================================================== --- core/trunk/src/main/java/org/jboss/cache/invocation/CacheInvocationDelegate.java 2008-04-28 17:27:58 UTC (rev 5734) +++ core/trunk/src/main/java/org/jboss/cache/invocation/CacheInvocationDelegate.java 2008-04-28 18:31:24 UTC (rev 5735) @@ -585,7 +585,10 @@ assertIsConstructed(); if (!ctx.getOptionOverrides().isSkipCacheStatusCheck()) { - lifecycleManager.allowsInvocation(true); + if (!lifecycleManager.invocationsAllowed(true)) + { + throw new IllegalStateException("Cache not in STARTED state!"); + } } } } Modified: core/trunk/src/main/java/org/jboss/cache/marshall/CommandAwareRpcDispatcher.java =================================================================== --- core/trunk/src/main/java/org/jboss/cache/marshall/CommandAwareRpcDispatcher.java 2008-04-28 17:27:58 UTC (rev 5734) +++ core/trunk/src/main/java/org/jboss/cache/marshall/CommandAwareRpcDispatcher.java 2008-04-28 18:31:24 UTC (rev 5735) @@ -129,7 +129,7 @@ { InvocationContext ctx = invocationContextContainer.get(); ctx.setOriginLocal(false); - if (!lifecycleManager.allowsInvocation(false)) + if (!lifecycleManager.invocationsAllowed(false)) { return null; } @@ -143,7 +143,7 @@ if (!(cmd instanceof AnnounceBuddyPoolNameCommand || cmd instanceof AssignToBuddyGroupCommand || cmd instanceof RemoveFromBuddyGroupCommand) - && !lifecycleManager.allowsInvocation(false)) + && !lifecycleManager.invocationsAllowed(false)) { return null; } Modified: core/trunk/src/main/java/org/jboss/cache/transaction/GlobalTransactionContainer.java =================================================================== --- core/trunk/src/main/java/org/jboss/cache/transaction/GlobalTransactionContainer.java 2008-04-28 17:27:58 UTC (rev 5734) +++ core/trunk/src/main/java/org/jboss/cache/transaction/GlobalTransactionContainer.java 2008-04-28 18:31:24 UTC (rev 5735) @@ -15,12 +15,14 @@ import javax.transaction.TransactionManager; /** + * A container class that holds, retrieves or creates {@link GlobalTransaction} objects and associates them with {@link Transaction} objects. + * * @author Mircea.Markus(a)jboss.com * @since 2.2 */ public class GlobalTransactionContainer { - + // TODO: 2.2.0: Can this be combined with TransactionTable? private static final Log log = LogFactory.getLog(GlobalTransactionContainer.class); /**