svn commit: r439214 - /jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/ItemId.java

[mr...@apache.org]

Author: mreutegg
Date: Thu Aug 31 23:58:36 2006
New Revision: 439214

URL: http://svn.apache.org/viewvc?rev=439214&view=rev
Log:
Add JavaDoc to ItemId.

Modified:
    jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/ItemId.java

Modified: jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/ItemId.java
URL: http://svn.apache.org/viewvc/jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/ItemId.java?rev=439214&r1=439213&r2=439214&view=diff
==============================================================================
--- jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/ItemId.java (original)
+++ jackrabbit/trunk/contrib/spi/spi/src/main/java/org/apache/jackrabbit/spi/ItemId.java Thu Aug 31 23:58:36 2006
@@ -19,13 +19,53 @@
 import org.apache.jackrabbit.name.Path;
 
 /**
- * <code>ItemId</code>...
+ * An <code>ItemId</code> identifies an item using a combination of UUID and
+ * relative path. There are three basic forms of an ItemId. The following
+ * table shows each of the allowed combinations where an <b>X</b> in
+ * the column indicates that a value is set and a <b>-</b> indicates
+ * that the value is <code>null</code>:
+ * <table>
+ * <tr><th>UUID</th><th>relative Path</th><th>Usage</th></tr>
+ * <tr><td align="center"><b>X</b></td><td align="center"><b>-</b></td>
+ *   <td>The item can be identified with a UUID. In most cases such an item
+ *   is also mix:referenceable but there is no restriction in that respect. An
+ *   SPI implementation may also use a UUID to identify non-referenceable nodes.
+ *   Whether a node is referenceable is purely governed by its node type or
+ *   the assigned mixin types.</td></tr>
+ * <tr><td align="center"><b>-</b></td><td align="center"><b>X</b></td>
+ *   <td>The item can not be identified with a UUID and none of its ancestors
+ *   can be identified with a UUID. The item is identified by a relative path
+ *   starting from the root node of the workspace as if calling
+ *   {@link javax.jcr.Session#getRootNode() Session.getRootNode()}{@link
+ *   javax.jcr.Node#getNode(String) .getNode(relPath)}.
+ *   </td></tr>
+ * <tr><td align="center"><b>X</b></td><td align="center"><b>X</b></td>
+ *   <td>The item can not be identified with a UUID but one of its ancestors
+ *   can. {@link #getUUID} returns the UUID of the nearest ancestor, which
+ *   can be identified with a UUID. The relative path provides a navigation
+ *   path from the above mentioned ancestor to the item identified by the
+ *   <code>ItemId</code>.
+ *   </td></tr>
+ * </table>
  */
 public interface ItemId {
 
+    /**
+     * @return <code>true</code> if this <code>ItemId</code> identifies a node;
+     *         otherwise <code>false</code>.
+     */
     public boolean denotesNode();
 
+    /**
+     * @return the UUID part of this item id or <code>null</code> if the
+     *         identified item nor any of its ancestors can be identified with a
+     *         UUID.
+     */
     public String getUUID();
 
+    /**
+     * @return the relative path part of this item id. Returns <code>null</code>
+     *         if this item can be identified solely with a UUID.
+     */
     public Path getRelativePath();
 }