Author: jukka
Date: Sun May  8 14:50:56 2005
New Revision: 169173

URL: http://svn.apache.org/viewcvs?rev=169173&view=rev
Log:
JCR-EXT: Added javadocs.

Modified:
    incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java
    incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java
    incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java
    incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java
    incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java

Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java Sun May  8 14:50:56 2005
@@ -106,7 +106,17 @@
         return "{" + namespaceURI + "}" + localPart;
     }
 
-    public static Name parseJCRName(Session session, String name)
+    /**
+     * Parses the given prefixed JCR name into a qualified name instance.
+     * The namespace prefix is resolved using the current session.
+     *
+     * @param session current session
+     * @param name    prefixed JCR name
+     * @return qualified name
+     * @throws NamespaceException  if the namespace prefix is not registered
+     * @throws RepositoryException if another error occurs
+     */
+    public static Name fromJCRName(Session session, String name)
             throws NamespaceException, RepositoryException {
         int p = name.indexOf(':');
         if (p != -1) {
@@ -118,6 +128,15 @@
         }
     }
 
+    /**
+     * Returns the prefixed JCR name representation of the qualified name.
+     * The namespace prefix is retrieved from the current session.
+     *
+     * @param session current session
+     * @return prefixed JCR name
+     * @throws NamespaceException  if the namespace URI is not registered
+     * @throws RepositoryException if another error occurs
+     */
     public String toJCRName(Session session)
             throws NamespaceException, RepositoryException {
         String prefix = session.getNamespacePrefix(namespaceURI);

Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java Sun May  8 14:50:56 2005
@@ -21,14 +21,43 @@
 import javax.jcr.RepositoryException;
 import javax.jcr.Session;
 
+/**
+ * Content path. Instances of this class are used to represent item paths
+ * within a JCR content repository.
+ * <p>
+ * A path instance consists of a sequence of path elements, that are
+ * resolved one by one in the specified order to reach the target item from
+ * a given context item.
+ * <p>
+ * Once created, a path instance is immutable.
+ *
+ * @see PathElement
+ * @see PathParser
+ * @see PathBuilder
+ */
 public final class Path {
 
+    /** Path elements */
     private final PathElement[] elements;
 
+    /**
+     * Creates a path instance that contains the given path elements.
+     *
+     * @param elements path elements
+     */
     Path(PathElement[] elements) {
         this.elements = elements;
     }
 
+    /**
+     * Resolves this path starting from the given context item. Returns
+     * the result of the path resolution.
+     *
+     * @param item the context item from which to resolve this path
+     * @return the resolved target item
+     * @throws PathNotFoundException if the path can not be resolved
+     * @throws RepositoryException   if another error occurs
+     */
     public Item resolve(Item item)
             throws PathNotFoundException, RepositoryException {
         for (int i = 0; i < elements.length; i++) {
@@ -37,11 +66,34 @@
         return item;
     }
 
+    /**
+     * Parses the given JCR path string. Namespace prefixes within the path
+     * are resolved using the current session.
+     *
+     * @param session current session
+     * @param path    JCR path
+     * @return path instance
+     * @throws IllegalArgumentException if the given path is invalid
+     * @throws RepositoryException      if another error occurs
+     * @see PathParser
+     */
     public static Path parse(Session session, String path)
             throws IllegalArgumentException, RepositoryException {
         return new PathParser(session).parsePath(path);
     }
 
+    /**
+     * Resolves the given JCR path from the given context item. Returns
+     * the result of the path resolution. Namespace prefixes within the path
+     * are resolved using the session associated with the context item.
+     *
+     * @param item context item
+     * @param path JCR path
+     * @return target item
+     * @throws IllegalArgumentException if the given path is invalid
+     * @throws PathNotFoundException    if the given path can not be resolved
+     * @throws RepositoryException      if another error occurs
+     */
     public static Item resolve(Item item, String path)
             throws IllegalArgumentException, PathNotFoundException,
             RepositoryException {

Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java Sun May  8 14:50:56 2005
@@ -19,18 +19,39 @@
 import java.util.List;
 import java.util.Vector;
 
+/**
+ * Content path builder. This utility class uses the Builder design
+ * pattern (GoF) to provide a simple mechanism for converting a sequence
+ * of path elements into a path instance.
+ *
+ * @see PathParser
+ */
 final class PathBuilder {
 
+    /** Path element list. Grows as more elements are added. */
     private final List elements;
 
+    /**
+     * Creates a path builder instance.
+     */
     public PathBuilder() {
         elements = new Vector();
     }
 
+    /**
+     * Adds an element to the path being built.
+     *
+     * @param element path element
+     */
     public void addElement(PathElement element) {
         elements.add(element);
     }
 
+    /**
+     * Creates a path instance from the collected sequence of path elements.
+     *
+     * @return path instance
+     */
     public Path getPath() {
         return new Path((PathElement[])
                 elements.toArray(new PathElement[elements.size()]));

Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java Sun May  8 14:50:56 2005
@@ -34,8 +34,8 @@
      * Resolves this path element within the context of the given content
      * item. Retuns the result of the path element resolution.
      *
-     * @param item the context from which to resolve this path element
-     * @return the resolved content item
+     * @param item the context item from which to resolve this path element
+     * @return the resolved target item
      * @throws PathNotFoundException if the path element could not be resolved
      * @throws RepositoryException   if another error occurred
      */

Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java Sun May  8 14:50:56 2005
@@ -23,16 +23,22 @@
 import javax.jcr.RepositoryException;
 import javax.jcr.Session;
 
-final class PathParser {
+/**
+ * JCR content path parser. Instances of this class are used to parse
+ * JCR content path strings into resolvable path instances. A path parser
+ * instance is always associated with a given session that is used to
+ * resolve namespace prefixes within the parsed paths.
+ */
+public final class PathParser {
 
     /**
-     * Pattern used to validate and parse path elements:<p>
+     * Pattern used to validate and parse path elements.
      * <ul>
-     * <li>group 1 is .
-     * <li>group 2 is ..
-     * <li>group 3 is namespace prefix excl. delimiter (colon)
-     * <li>group 4 is localName
-     * <li>group 5 is index excl. brackets
+     * <li>group 1 is . (matches the full string)
+     * <li>group 2 is .. (matches the full string)
+     * <li>group 3 is the optional namespace prefix (without the colon)
+     * <li>group 4 is the local part of the JCR name
+     * <li>group 5 is the optional index (without the brackets)
      * </ul>
      */
     private static final Pattern PATH_ELEMENT_PATTERN = Pattern.compile(
@@ -41,38 +47,60 @@
             + "([^ /:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?)"
             + "(?:\\[([1-9]\\d*)\\])?");
 
+    /** Current session. Used to resolve namespace prefixes. */
     private final Session session;
 
+    /**
+     * Creates a path parser for the given session.
+     *
+     * @param session current session
+     */
     public PathParser(Session session) {
         this.session = session;
     }
 
+    /**
+     * Parses the given JCR content path.
+     *
+     * @param path JCR content path
+     * @return path instance
+     * @throws IllegalArgumentException if the given path is invalid
+     * @throws RepositoryException      if another error occurs
+     */
     public Path parsePath(String path)
             throws IllegalArgumentException, RepositoryException {
         PathBuilder builder = new PathBuilder();
-
         int p = path.indexOf('/');
-        if (p == 0) {
+
+        if (p == 0) { // Check for an absolute path with a leading slash
             builder.addElement(new RootElement());
             path = path.substring(1);
             p = path.indexOf('/');
         }
 
         while (p != -1) {
-            if (p > 0) {
+            if (p > 0) { // Ignore empty path elements
                 builder.addElement(parsePathElement(path.substring(0, p)));
             }
             path = path.substring(p + 1);
             p = path.indexOf('/');
         }
 
-        if (path.length() > 0) {
+        if (path.length() > 0) { // Ignore empty trailing path elements
             builder.addElement(parsePathElement(path));
         }
 
         return builder.getPath();
     }
 
+    /**
+     * Parses the given path element.
+     *
+     * @param element path element
+     * @return path element instance
+     * @throws IllegalArgumentException if the given path element is invalid
+     * @throws RepositoryException      if another error occurs
+     */
     private PathElement parsePathElement(String element)
             throws IllegalArgumentException, RepositoryException {
         Matcher matcher = PATH_ELEMENT_PATTERN.matcher(element);