From 30abd8d3c2e8fd953cfb68d0817e75c06665c15e Mon Sep 17 00:00:00 2001
From: Andrew Branson <andrew.branson@cern.ch>
Date: Thu, 2 Oct 2014 17:17:17 +0200
Subject: Collection javadoc and cleanup

---
 .../com/c2kernel/collection/CollectionMember.java  | 69 ++++++++++++++++------
 1 file changed, 52 insertions(+), 17 deletions(-)

(limited to 'src/main/java/com/c2kernel/collection/CollectionMember.java')

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();
 }
-- 
cgit v1.2.3