[portal-commits] JBoss Portal SVN: r5768 - trunk/core/src/main/org/jboss/portal/core/model/portal

[portal-commits at lists.jboss.org]

Author: julien at jboss.com
Date: 2006-12-05 17:00:26 -0500 (Tue, 05 Dec 2006)
New Revision: 5768

Modified:
   trunk/core/src/main/org/jboss/portal/core/model/portal/PortalObjectContainer.java
   trunk/core/src/main/org/jboss/portal/core/model/portal/PortalObjectId.java
Log:
added javadoc

Modified: trunk/core/src/main/org/jboss/portal/core/model/portal/PortalObjectContainer.java
===================================================================
--- trunk/core/src/main/org/jboss/portal/core/model/portal/PortalObjectContainer.java	2006-12-05 21:52:46 UTC (rev 5767)
+++ trunk/core/src/main/org/jboss/portal/core/model/portal/PortalObjectContainer.java	2006-12-05 22:00:26 UTC (rev 5768)
@@ -35,6 +35,7 @@
    /**
     * Return a container object.
     *
+    * @param id the portal object id
     * @return the specified portal object
     * @throws IllegalArgumentException if the id is null
     */

Modified: trunk/core/src/main/org/jboss/portal/core/model/portal/PortalObjectId.java
===================================================================
--- trunk/core/src/main/org/jboss/portal/core/model/portal/PortalObjectId.java	2006-12-05 21:52:46 UTC (rev 5767)
+++ trunk/core/src/main/org/jboss/portal/core/model/portal/PortalObjectId.java	2006-12-05 22:00:26 UTC (rev 5768)
@@ -28,19 +28,27 @@
 import java.util.Iterator;
 
 /**
+ * A composite id for a portal object.
+ *
  * @author <a href="mailto:julien at jboss.org">Julien Viet</a>
  * @version $Revision: 1.1 $
  */
 public class PortalObjectId implements Comparable
 {
 
-   /** . */
+   /** The composites. */
    private final String[] names;
 
-   /** . */
+   /** The lazy computed hash code. */
    private Integer hashCode;
 
-   public PortalObjectId(PortalObjectId that)
+   /**
+    * Copy constructor.
+    *
+    * @param that the id to clone
+    * @throws IllegalArgumentException if the argument to clone is null
+    */
+   public PortalObjectId(PortalObjectId that) throws IllegalArgumentException
    {
       if (that == null)
       {
@@ -50,7 +58,13 @@
       this.hashCode = that.hashCode;
    }
 
-   public PortalObjectId(String[] names)
+   /**
+    * Build an id directly from its composing names.
+    *
+    * @param names the id names
+    * @throws IllegalArgumentException if any argument is null or not well formed
+    */
+   public PortalObjectId(String[] names) throws IllegalArgumentException
    {
       if (names == null)
       {
@@ -59,7 +73,14 @@
       this.names = names;
    }
 
-   public PortalObjectId(String value, Format format)
+   /**
+    * Build an id by parsing a string representation.
+    *
+    * @param value the string representation
+    * @param format the string format
+    * @throws IllegalArgumentException if any argument is null or not well formed
+    */
+   public PortalObjectId(String value, Format format) throws IllegalArgumentException
    {
       this.names = format.parse(value);
    }
@@ -116,16 +137,30 @@
       throw new NotYetImplemented();
    }
 
+   /**
+    * Return an iterator over the different names.
+    *
+    * @return the iterator over the names
+    */
    public Iterator names()
    {
       return Tools.iterator(names);
    }
 
+   /**
+    * Returns the canonical representation of the id.
+    */
    public String toString()
    {
       return CANONICAL_FORMAT.toString(names);
    }
 
+   /**
+    * Returns a string representation using a specified format
+    *
+    * @param format the output format
+    * @return the string value
+    */
    public String toString(Format format)
    {
       if (format == null)
@@ -137,14 +172,12 @@
 
    public static PortalObjectId parse(String value, Format format)
    {
-      if (format == null)
-      {
-         throw new IllegalArgumentException();
-      }
-      String[] names = format.parse(value);
-      return new PortalObjectId(names);
+      return new PortalObjectId(value, format);
    }
 
+   /**
+    * The format of a string representation of an id.
+    */
    public abstract static class Format
    {
       /**
@@ -152,21 +185,21 @@
        * @param value
        * @return
        */
-      public abstract String[] parse(String value);
+      public abstract String[] parse(String value) throws IllegalArgumentException;
 
       /**
        *
        * @param names
        * @return
        */
-      public abstract String toString(String[] names);
+      public abstract String toString(String[] names) throws IllegalArgumentException;
 
       /**
        * 
        * @param id
        * @return
        */
-      public final String toString(PortalObjectId id)
+      public final String toString(PortalObjectId id) throws IllegalArgumentException
       {
          if (id == null)
          {
@@ -176,6 +209,9 @@
       }
    }
 
+   /**
+    * Canonical format, smth like /a/b/c.
+    */
    public static final Format CANONICAL_FORMAT = new Format()
    {
       public String[] parse(String value)
@@ -254,6 +290,9 @@
       }
    };
 
+   /**
+    * The internal format when it is persisted, smth like a.b.c
+    */
    public static final Format LEGACY_FORMAT = new Format()
    {