Collection javadoc and cleanup

7 files changed, 73 insertions, 51 deletions

diff --git a/src/main/java/com/c2kernel/collection/AggregationMember.java b/src/main/java/com/c2kernel/collection/AggregationMember.java
index ac4fc4d..067bb46 100644
--- a/src/main/java/com/c2kernel/collection/AggregationMember.java
+++ b/src/main/java/com/c2kernel/collection/AggregationMember.java
@@ -59,18 +59,11 @@ public class AggregationMember extends GraphableVertex implements CollectionMemb
         super();

     }

 

-    @Override

-	public void setItemPath(ItemPath itemPath) {

-    	mItemPath = itemPath;

-    	mItemName = null;

-    }

-

     public void setCollection(Aggregation aggregation)

     {

         mCollection = aggregation;

     }

 

-    @Override

 	public void setClassProps(String props)

     {

         mClassProps = props;

@@ -162,9 +155,9 @@ public class AggregationMember extends GraphableVertex implements CollectionMemb
     	return mItemName;

     }

 

-	@Override

 	public void setChildUUID(String uuid) throws MembershipException, InvalidItemPathException {

-		setItemPath(new ItemPath(uuid));

+		mItemPath = new ItemPath(uuid);

+		mItemName = null;

 	}

 

 

diff --git a/src/main/java/com/c2kernel/collection/CollectionDescription.java b/src/main/java/com/c2kernel/collection/CollectionDescription.java
index f4d9f15..4b49ccd 100644
--- a/src/main/java/com/c2kernel/collection/CollectionDescription.java
+++ b/src/main/java/com/c2kernel/collection/CollectionDescription.java
@@ -22,15 +22,18 @@ package com.c2kernel.collection;
 

 import com.c2kernel.common.ObjectNotFoundException;

 

-/**************************************************************************

- *

- * $Revision: 1.1 $

- * $Date: 2003/03/11 11:09:07 $

- *

- * Copyright (C) 2003 CERN - European Organization for Nuclear Research

- * All rights reserved.

- **************************************************************************/

-

+/**

+ * A collection that can be instantiated. Collection descriptions link Item 

+ * descriptions together, which constrains membership of their instance. 

+ * 

+ */

 public interface CollectionDescription<E extends CollectionMember> {

+	

+	/**

+	 * Create a new instance of this collection.

+	 * @return a new collection instance

+	 * @throws ObjectNotFoundException When an essential piece of description 

+	 * data, such as a child Item PropertyDescription outcome, doesn't exist.

+	 */

 	public Collection<E> newInstance() throws ObjectNotFoundException;

 }

diff --git a/src/main/java/com/c2kernel/collection/CollectionMember.java b/src/main/java/com/c2kernel/collection/CollectionMember.java
index 4315d84..74d4671 100644
--- a/src/main/java/com/c2kernel/collection/CollectionMember.java
+++ b/src/main/java/com/c2kernel/collection/CollectionMember.java
@@ -22,40 +22,75 @@ package com.c2kernel.collection;
 

 import com.c2kernel.common.ObjectNotFoundException;

 import com.c2kernel.entity.proxy.ItemProxy;

-import com.c2kernel.lookup.InvalidItemPathException;

 import com.c2kernel.lookup.ItemPath;

 import com.c2kernel.utils.CastorHashMap;

 

-/**************************************************************************

- * CollectionMember interface is the superclass of all members

- * This should be temporary - if we manage to rip GraphableVertex from Vertex,

- * then that should be the superclass.

- *

- * $Revision: 1.19 $

- * $Date: 2004/01/22 11:24:44 $

+/**

+ * CollectionMembers are pointers to individual Items in a collection. Under 

+ * certain circumstances they may be empty, or they can be created and destroyed

+ * as required. They can hold properties containing annotations about the link,

+ * including information on the typing of the Item they should point to. 

+ * Properties that dictate type information are specified in the ClassProps, and

+ * assignment of an Item will fail if those member properties do not match the

+ * Property values of the Item attempting to be assigned, throwing a

+ * {@link MembershipException} detailing the mismatches. 

  *

- * Copyright (C) 2003 CERN - European Organization for Nuclear Research

- * All rights reserved.

- **************************************************************************/

+ */

 

 public interface CollectionMember {

-

-	public void setItemPath(ItemPath itemPath) throws MembershipException;

+	

+	/**

+	 * Returns the current assigned ItemPath

+	 * @return the ItemPath, null if empty

+	 */

 	public ItemPath getItemPath();

 	

-	public void setChildUUID(String uuid) throws MembershipException, InvalidItemPathException;

+	/**

+	 * Returns the UUID of the currently assigned Item

+	 * @return

+	 */

 	public String getChildUUID();

 

+	/**

+	 * Assign the given item to the slot, if it fits

+	 * 

+	 * @param itemPath The item to assign

+	 * @throws MembershipException When the Item Properties don't match the

+	 * typing specification in ClassProps and Properties

+	 */

     public void assignItem(ItemPath itemPath) throws MembershipException;

+    

+    /**

+     * De-assign the slot, leaving it empty.

+     */

     public void clearItem();

+    

+    /**

+     * Resolve the Item currently assigned

+     * @return the ItemProxy of the assigned Item

+     * @throws ObjectNotFoundException When empty

+     */

     public ItemProxy resolveItem() throws ObjectNotFoundException;

 

-	public void setID(int Id);

+	/**

+	 * Get the integer slot ID, as generated by the parent Collection

+	 * @return ID

+	 */

 	public int getID();

 

-	public void setProperties(CastorHashMap props);

+	/**

+	 * Gets the member properties.

+	 * @return CastorHashMap

+	 */

 	public CastorHashMap getProperties();

 

-	public void setClassProps(String classProps);

+	/**

+	 * Gets the class properties, which specify type information in child Items.

+	 * On instantiation from a CollectionDescription, the ClassProps are 

+	 * generated from the PropertyDescriptions which have the isClassIdentifier 

+	 * boolean set to true.

+	 * 

+	 * @return Comma-separated list of property names that relate to Item type

+	 */

 	public String getClassProps();

 }

diff --git a/src/main/java/com/c2kernel/collection/CollectionMemberList.java b/src/main/java/com/c2kernel/collection/CollectionMemberList.java
index 0a9200e..49096e0 100644
--- a/src/main/java/com/c2kernel/collection/CollectionMemberList.java
+++ b/src/main/java/com/c2kernel/collection/CollectionMemberList.java
@@ -22,6 +22,12 @@ package com.c2kernel.collection;
 

 import com.c2kernel.utils.CastorArrayList;

 

+/**

+ * A list of CollectionMembers, used internally in the Collection for XML 

+ * marshalling convenience.

+ *  *

+ * @param <E> The CollectionMember implementation stored.

+ */

 public class CollectionMemberList<E extends CollectionMember> extends CastorArrayList<E>

 {

 

diff --git a/src/main/java/com/c2kernel/collection/DependencyMember.java b/src/main/java/com/c2kernel/collection/DependencyMember.java
index ddd2ff2..6f86ecd 100644
--- a/src/main/java/com/c2kernel/collection/DependencyMember.java
+++ b/src/main/java/com/c2kernel/collection/DependencyMember.java
@@ -58,21 +58,12 @@ public class DependencyMember implements CollectionMember
         mProperties = new CastorHashMap();

     }

 

-

-    @Override

-	public void setItemPath(ItemPath itemPath)

-    {

-        mItemPath = itemPath;

-        mItem = null;

-    }

-

     @Override

 	public ItemPath getItemPath()

     {

         return mItemPath;

     }

 

-	@Override

 	public void setProperties(CastorHashMap props)

 	{

 		mProperties = props;

@@ -98,12 +89,10 @@ public class DependencyMember implements CollectionMember
 		return mId;

 	}

 

-	@Override

 	public void setID(int id) {

 		mId = id;

 	}

 

-    @Override

 	public void setClassProps(String props)

     {

         mClassProps = props;

@@ -160,8 +149,6 @@ public class DependencyMember implements CollectionMember
         return mItem;

     }

 

-

-	@Override

 	public void setChildUUID(String uuid) throws MembershipException, InvalidItemPathException {

 		mItemPath = new ItemPath(uuid);

 	}

diff --git a/src/main/java/com/c2kernel/collection/MembershipException.java b/src/main/java/com/c2kernel/collection/MembershipException.java
index a69e46a..3e2ce8c 100644
--- a/src/main/java/com/c2kernel/collection/MembershipException.java
+++ b/src/main/java/com/c2kernel/collection/MembershipException.java
@@ -25,8 +25,6 @@ package com.c2kernel.collection;
  * $Revision: 1.1 $

  * $Date: 2003/05/09 14:23:01 $

  *

- * Copyright (C) 2003 CERN - European Organization for Nuclear Research

- * All rights reserved.

  **************************************************************************/

 

 public class MembershipException extends Exception {

diff --git a/src/main/java/com/c2kernel/collection/package-info.java b/src/main/java/com/c2kernel/collection/package-info.java
index fd67244..1c77816 100644
--- a/src/main/java/com/c2kernel/collection/package-info.java
+++ b/src/main/java/com/c2kernel/collection/package-info.java
@@ -29,7 +29,7 @@
  * 

  * <p>Features:

  * <ul>

- * <li><b>Typing<b> - Collections can restrict membership of based on type 

+ * <li><b>Typing</b> - Collections can restrict membership of based on type 

  * information derived from Item, Property and Collection descriptions. This

  * restriction may be per-slot or apply to the whole Collection.

  *