incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From i..@apache.org
Subject svn commit: r1443887 - /sling/trunk/bundles/resourceresolver/src/main/java/org/apache/sling/resourceresolver/impl/tree/ResourceProviderEntry.java
Date Fri, 08 Feb 2013 08:47:54 GMT
Author: ieb
Date: Fri Feb  8 08:47:53 2013
New Revision: 1443887

URL: http://svn.apache.org/r1443887
Log:
Improved documentation in ResourceProviderEntry, mainly targetted at someone reading the code.
No code changes.

Modified:
    sling/trunk/bundles/resourceresolver/src/main/java/org/apache/sling/resourceresolver/impl/tree/ResourceProviderEntry.java

Modified: sling/trunk/bundles/resourceresolver/src/main/java/org/apache/sling/resourceresolver/impl/tree/ResourceProviderEntry.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/resourceresolver/src/main/java/org/apache/sling/resourceresolver/impl/tree/ResourceProviderEntry.java?rev=1443887&r1=1443886&r2=1443887&view=diff
==============================================================================
--- sling/trunk/bundles/resourceresolver/src/main/java/org/apache/sling/resourceresolver/impl/tree/ResourceProviderEntry.java
(original)
+++ sling/trunk/bundles/resourceresolver/src/main/java/org/apache/sling/resourceresolver/impl/tree/ResourceProviderEntry.java
Fri Feb  8 08:47:53 2013
@@ -41,6 +41,13 @@ import org.slf4j.LoggerFactory;
  * The <code>ResourceProviderEntry</code> class represents a node in the tree
of
  * resource providers spanned by the root paths of the provider resources.
  * <p>
+ * That means this class has a map of child ResourceProviderEntries, keyed by the child name

+ * and a list of ProviderHandlers that are mapped to the path that this ResourceProviderEntry
represents.
+ * To locate a list of potential ResourceProviders the path is split into elements and then
that list used to
+ * walk down the tree of ResourceProviders. eg: for a path /a/b/c/d the list of ProviderHandlers
would be accessed
+ * by rootProvider.get("a").get("b").get("c").get("d")  assuming the final get("d") was not
null. If it was, then the list
+ * of ProviderHanders would be rootProvider.get("a").get("b").get("c").
+ * <p>
  * This class is comparable to itself to help keep the child entries list sorted by their
prefix.
  */
 public class ResourceProviderEntry implements Comparable<ResourceProviderEntry> {
@@ -68,7 +75,7 @@ public class ResourceProviderEntry imple
     /**
      * Creates an instance of this class with the given path relative to the
      * parent resource provider entry, encapsulating the given ResourceProvider,
-     * and a number of inital child entries.
+     * and a number of initial child entries.
      *
      * @param path
      *            The relative path supported by the provider
@@ -187,27 +194,33 @@ public class ResourceProviderEntry imple
         return providers.length < before;
     }
 
-    /**
-     * Adds the given resource provider into the tree for the given prefix.
-     *
-     * @return <code>true</code> if the provider could be entered into the
-     *         subtree below this entry. Otherwise <code>false</code> is
-     *         returned.
-     */
+	/**
+	 * Adds the given resource provider into the tree for the given prefix. This
+	 * will expand the tree of ResourceProviderEntries down the supplied prefix
+	 * and add the provider to a ResourceProviderEntry that represents the last
+	 * element of the path.
+	 * 
+	 * @return <code>true</code> if the provider could be entered into the
+	 *         subtree below this entry. Otherwise <code>false</code> is
+	 *         returned.
+	 */
     protected synchronized boolean addResourceProvider(final String prefix, final ProviderHandler
provider) {
         final String[] elements = split(prefix);
         final List<ResourceProviderEntry> entries = new ArrayList<ResourceProviderEntry>();
         this.populateProviderPath(entries, elements);
 
         // add this=root to the start so if the list is empty
-        // we have a position to add to
+        // we have a position to add, this will shift other entries
+        // down the list.
         entries.add(0, this);
+        // the list may not be complete, so add blank entries from the current size to the
end of this path.
         for (int i = entries.size() - 1; i < elements.length; i++) {
             final String stubPrefix = elements[i];
             final ResourceProviderEntry rpe2 = new ResourceProviderEntry(stubPrefix, new
ProviderHandler[0]);
             entries.get(i).put(stubPrefix, rpe2);
             entries.add(rpe2);
         }
+        // finally add this provider to the last in the list. This might be a new entry,
or an existing entry.
         return entries.get(elements.length).addInternalProvider(provider);
     }
 
@@ -248,11 +261,20 @@ public class ResourceProviderEntry imple
         return providerList.toArray(new ProviderHandler[providerList.size()]);
     }
 
-    /**
-     * Get a list of resource provider entries in reverse order.
-     * @param entries List to add the entries to
-     * @param elements The path already split into segments.
-     */
+	/**
+	 * Get a list of resource provider entries navigating down the tree starting
+	 * from this provider until there are no providers left in the tree. Given a
+	 * sequence of path elements a/b/c/d this function will inspect this
+	 * ResourceProviderEntry for a child entry of "a" and if present add it to
+	 * the list, then it will inspect that child entry for a child "b", then
+	 * child "b" for child "c" etc until the list of elements is exhausted or
+	 * the child does not exist.
+	 * 
+	 * @param entries
+	 *            List to add the entries to.
+	 * @param elements
+	 *            The path already split into segments.
+	 */
     private void populateProviderPath(final List<ResourceProviderEntry> entries, final
String[] elements) {
         ResourceProviderEntry base = this;
         for (final String element : elements) {



Mime
View raw message