From d154dc861ab2423cff4189f7504bd6a963d4e729 Mon Sep 17 00:00:00 2001 From: Andrew Branson Date: Mon, 6 Oct 2014 12:09:46 +0200 Subject: Collection doc --- .../java/com/c2kernel/collection/Aggregation.java | 6 +- .../java/com/c2kernel/collection/Collection.java | 111 ++++++++++++++------- 2 files changed, 78 insertions(+), 39 deletions(-) (limited to 'src/main/java/com') 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 @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 implements C2KLocal public static final short EMPTY = -1; private int mCounter = -1; // Contains next available Member ID protected CollectionMemberList mMembers = new CollectionMemberList(); - 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 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 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 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 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 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 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 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; - }*/ - - } -- cgit v1.2.3