Collection doc

2 files changed, 78 insertions, 39 deletions

diff --git a/src/main/java/com/c2kernel/collection/Aggregation.java b/src/main/java/com/c2kernel/collection/Aggregation.java
index ea1c182..68b52cf 100644
--- a/src/main/java/com/c2kernel/collection/Aggregation.java
+++ b/src/main/java/com/c2kernel/collection/Aggregation.java
@@ -130,13 +130,15 @@ abstract public class Aggregation extends Collection<AggregationMember>
 

 

     @Override

-	public AggregationMember addMember(ItemPath itemPath, CastorHashMap props, String classProps) throws InvalidCollectionModification, ObjectAlreadyExistsException

+	public AggregationMember addMember(ItemPath itemPath, CastorHashMap props, String classProps) 

+			throws InvalidCollectionModification, ObjectAlreadyExistsException

     {

         return addMember(itemPath, props, classProps, null, -1, -1);

     }

     

 

-	public AggregationMember addMember(CastorHashMap props, String classProps, GraphPoint location, int w, int h) throws InvalidCollectionModification {

+	public AggregationMember addMember(CastorHashMap props, String classProps, GraphPoint location, int w, int h) 

+			throws InvalidCollectionModification {

 		try {

 			return addMember(null, props, classProps, location, w, h);

 		} catch (ObjectAlreadyExistsException e) { // not assigning an item so this won't happen

diff --git a/src/main/java/com/c2kernel/collection/Collection.java b/src/main/java/com/c2kernel/collection/Collection.java
index 2bedfb2..34ec93f 100644
--- a/src/main/java/com/c2kernel/collection/Collection.java
+++ b/src/main/java/com/c2kernel/collection/Collection.java
@@ -60,10 +60,15 @@ abstract public class Collection<E extends CollectionMember> implements C2KLocal
 	public static final short EMPTY = -1;

     private int mCounter = -1;      // Contains next available Member ID

     protected CollectionMemberList<E> mMembers = new CollectionMemberList<E>();

-    protected int mID = -1;

     protected String mName = "";     // Not checked for uniqueness

     protected Integer mVersion = null;

 

+    /**

+     * Fetch the current highest member ID of the collection. This is found by

+     * scanning all the current members and kept in the mCounter field, but is 

+     * not persistent.

+     * @return the current highest member ID

+     */

 	public int getCounter()

     {

         if (mCounter == -1)

@@ -74,50 +79,62 @@ abstract public class Collection<E extends CollectionMember> implements C2KLocal
         return ++mCounter;

     }

 

-	public void setCounter(int count)

-    {

-        mCounter = count;

-    }

-

-

+	/**

+	 * @return The total number of slots in this collection, including empty 

+	 * ones 

+	 */

 	public int size()

     {

         return mMembers.list.size();

     }

 

-    public void setID(int id)

-    {

-        mID = id;

-    }

-

-    public int getID()

-    {

-        return mID;

-    }

-

+	/**

+	 * Sets the collection name

+	 */

 	@Override

 	public void setName(String name)

     {

         mName = name;

     }

 

+	/**

+	 * @return The collection's name

+	 */

 	@Override

 	public String getName()

     {

         return mName;

     }

 	

+	/**

+	 * Get the collection version. Null if not set, and will be stored as 'last'

+	 * @return Integer version

+	 */

 	public Integer getVersion() {

 		return mVersion;

 	}

 

+	/**

+	 * Set a named version for this collection. Must be an integer or null.

+	 * Named versions will be stored separately to the current version ('last')

+	 * and should not change once saved.

+	 * 

+	 * @param Integer version

+	 */

 	public void setVersion(Integer mVersion) {

 		this.mVersion = mVersion;

 	}

 

+	/**

+	 * Get the version name for storage, which is 'last' unless the version 

+	 * number is set. 

+	 * 

+	 * @return 

+	 */

 	public String getVersionName() {

 		return mVersion==null?"last":String.valueOf(mVersion);

 	}

+	

 	@Override

 	public String getClusterType()

     {

@@ -137,6 +154,13 @@ abstract public class Collection<E extends CollectionMember> implements C2KLocal
         return false;

     }

     

+    /**

+     * Gets the description version referenced by the given collection member. 

+     * Assumes 'last' if version not given.

+     * 

+     * @param mem The member in question

+     * @return String version tag

+     */

     public String getDescVer(E mem) {

     	String descVer = "last";

     	Object descVerObj = mem.getProperties().get("Version");

@@ -144,6 +168,10 @@ abstract public class Collection<E extends CollectionMember> implements C2KLocal
     	return descVer;

     }

 

+    /**

+     * Check if all slots have an assigned Item

+     * @return boolean

+     */

     public boolean isFull()

     {

     	for (E element : mMembers.list) {

@@ -153,6 +181,12 @@ abstract public class Collection<E extends CollectionMember> implements C2KLocal
     	return true;

     }

 

+    /**

+     * Find collection member by integer ID

+     * @param memberId to find

+     * @return the CollectionMember with that ID

+     * @throws ObjectNotFoundException when the ID wasn't found

+     */

 	public E getMember(int memberId) throws ObjectNotFoundException {

         for (E element : mMembers.list) {

             if (element.getID() == memberId)

@@ -166,8 +200,31 @@ abstract public class Collection<E extends CollectionMember> implements C2KLocal
         return mMembers;

     }

 

+	/**

+	 * Add a member to this collection, with the given property and class properties

+	 * and optionally an Item to assign, which may be null if the collection allows 

+	 * empty slots.

+	 * 

+	 * @param itemPath the Item to assign to the new slot. Optional for collections

+	 * that allow empty slots

+	 * @param props the Properties of the new member

+	 * @param classProps the names of the properties that dictate the type of

+	 * assigned Items.

+	 * @return the new CollectionMember instance

+	 * @throws InvalidCollectionModification when the assignment was invalid because 

+	 * of collection constraints, such as global type constraints, or not allowing

+	 * empty slots.

+	 * @throws ObjectAlreadyExistsException some collections don't allow multiple 

+	 * slots assigned to the same Item, and throw this Exception if it is attempted

+	 */

 	public abstract E addMember(ItemPath itemPath, CastorHashMap props, String classProps) throws InvalidCollectionModification, ObjectAlreadyExistsException;

 	

+	/**

+	 * Removes the slot with the given ID from the collection.

+	 * 

+	 * @param memberId to remove

+	 * @throws ObjectNotFoundException when there was no slot with this ID found.

+	 */

 	public abstract void removeMember(int memberId) throws ObjectNotFoundException;

 

 	@Override

@@ -201,24 +258,4 @@ abstract public class Collection<E extends CollectionMember> implements C2KLocal
 			return false;

 		return true;

 	}

-

-	/*@Override

-    public boolean equals(Object other) {

-		if (!(other instanceof Collection<?>)) return false;

-		Collection<?> otherColl = (Collection<?>)other;

-    	boolean same = mName.equals(otherColl.getName()) && size() == otherColl.size();

-    	if (!same) return false;

-		for (Iterator<E> i = getMembers().list.iterator(); i.hasNext();) {

-			try {

-				E thisMem = i.next();

-				CollectionMember otherMem = otherColl.getMember(thisMem.getID());

-				if (!thisMem.equals(otherMem)) return false;

-			} catch (ObjectNotFoundException ex) {

-				return false;

-			}

-		}

-		return true;

-    }*/

-

-	

 }