From 30abd8d3c2e8fd953cfb68d0817e75c06665c15e Mon Sep 17 00:00:00 2001 From: Andrew Branson Date: Thu, 2 Oct 2014 17:17:17 +0200 Subject: Collection javadoc and cleanup --- .../com/c2kernel/collection/AggregationMember.java | 11 +--- .../c2kernel/collection/CollectionDescription.java | 21 ++++--- .../com/c2kernel/collection/CollectionMember.java | 69 ++++++++++++++++------ .../c2kernel/collection/CollectionMemberList.java | 6 ++ .../com/c2kernel/collection/DependencyMember.java | 13 ---- .../c2kernel/collection/MembershipException.java | 2 - .../java/com/c2kernel/collection/package-info.java | 2 +- 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 { + + /** + * 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 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 The CollectionMember implementation stored. + */ public class CollectionMemberList extends CastorArrayList { 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 @@ * *

Features: *

    - *
  • Typing - Collections can restrict membership of based on type + *
  • Typing - 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. * -- cgit v1.2.3