[jbosscache-commits] JBoss Cache SVN: r5735 - in core/trunk/src/main/java/org/jboss/cache: invocation and 2 other directories.
jbosscache-commits at lists.jboss.org
jbosscache-commits at lists.jboss.org
Mon Apr 28 14:31:24 EDT 2008
Author: manik.surtani at 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 at 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 at 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 at 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);
/**
More information about the jbosscache-commits
mailing list