Author: julien(a)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@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() {