jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject svn commit: r1298338 - /jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/mk/model/Id.java
Date Thu, 08 Mar 2012 10:15:54 GMT
Author: stefan
Date: Thu Mar  8 10:15:54 2012
New Revision: 1298338

URL: http://svn.apache.org/viewvc?rev=1298338&view=rev
Log:
javadoc, clarifying the contract of the Id

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/mk/model/Id.java

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/mk/model/Id.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/mk/model/Id.java?rev=1298338&r1=1298337&r2=1298338&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/mk/model/Id.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/mk/model/Id.java Thu
Mar  8 10:15:54 2012
@@ -21,13 +21,33 @@ import org.apache.jackrabbit.mk.util.Str
 import java.util.Arrays;
 
 /**
- *
+ * Represents an internal identifier, uniquely identifying 
+ * a {@link Node} or a {@link Commit}.
+ * <p/>
+ * This implementation aims at minimizing the in-memory footprint
+ * of an identifier instance. therefore it doesn't cash e.g. the hashCode
+ * or the string representation.
+ * <p/>
+ * <b>Important Note:</b><p/>
+ * An {@link Id} is considered immutable. The <code>byte[]</code> 
+ * passed to {@link Id#Id(byte[])} must not be reused or modified, the same
+ * applies for the <code>byte[]</code> returned by {@link Id#getBytes()}.
  */
 public class Id {
 
+    // the raw bytes making up this identifier
     private final byte[] raw;
 
+    /**
+     * Creates a new instance based on the passed <code>byte[]</code>.
+     * <p/>
+     * The passed <code>byte[]</code> mus not be reused, it's assumed
+     * to be owned by the new <code>Id</code> instance.
+     *
+     * @param raw the byte representation
+     */
     public Id(byte[] raw) {
+        // don't copy the buffer for efficiency reasons
         this.raw = raw;
     }
 
@@ -50,6 +70,7 @@ public class Id {
 
     @Override
     public int hashCode() {
+        // the hashCode is intentionally not stored
         return Arrays.hashCode(raw);
     }
 
@@ -64,10 +85,19 @@ public class Id {
 
     @Override
     public String toString() {
+        // the string representation is intentionally not stored
         return StringUtils.convertBytesToHex(raw);
     }
 
+    /**
+     * Returns the raw byte representation of this identifier.
+     * <p/>
+     * The returned <code>byte[]</code> <i>MUST NOT</i> be modified!
+     *
+     * @return the raw byte representation
+     */
     public byte[] getBytes() {
+        // don't copy the buffer for efficiency reasons
         return raw;
     }
 }



Mime
View raw message