comments - explanation of bad heuristic that has to be fixed.

git-svn-id: https://svn.lifesci.dundee.ac.uk/svn/repository/trunk@143 be28352e-c001-0410-b1a7-c7978e42abec

diff --git a/src/org/vamsas/client/object.java b/src/org/vamsas/client/object.java
index ea51068..4757589 100644 (file)
--- a/src/org/vamsas/client/object.java
+++ b/src/org/vamsas/client/object.java
@@ -26,17 +26,29 @@ public abstract class object {
   static Log log = LogFactory.getLog(object.class);
   
   /**
-   * unique id for all vamsas objects allows unambiguous referencing to any
-   * object in the vamsas document
+   * true if object was stored in a vamsas Document or has been retrieved from it
    */
   protected boolean __stored_in_document = false;
+  /**
+   * memory of the last doHash() value computed for the object 
+   * @see doHash()
+   */
+  protected long __last_hash = 0; 
+  /**
+   * set by testInstanceForIdField() if object should have a VorbaId
+   */
+  protected boolean registerable = false; 
 
-  protected long __last_hash = 0; // default is different so doHash always returns true initially.
-
-  protected boolean registerable = false;
 
+  /**
+   * unique id for all vamsas objects allows unambiguous referencing to any
+   * object in the vamsas document
+   */
   protected VorbaId vorbaId = null;
 
+  /**
+   * the source of unique VorbaIds.
+   */
   protected IVorbaIdFactory __vorba = null;
 
   /**
@@ -48,7 +60,7 @@ public abstract class object {
   }
 
   /**
-   * set the isRegisterable flag based on the presence of a 'String id' field in
+   * set the isRegisterable flag based on the presence of a 'private String _id' field in
    * the reflected class instance.
    */
   private void testInstanceForIdField() {
@@ -67,7 +79,7 @@ public abstract class object {
   }
 
   /**
-   * update the object instance's String id field, based on the contents of the
+   * update the object instance's _id field, based on the contents of the
    * VorbaId. Only call this if you mean to do it!
    */
   protected void setInstanceIdField() {
@@ -101,6 +113,7 @@ public abstract class object {
   /**
    * calculate a hash for the object with all housekeeping fields at standard
    * values. (isRegisterable is an immutable attribute property)
+   * TODO: decide if __stored_in_document should be included in the hash or not.
    * @return true if new hash different to last hash
    */
   synchronized protected boolean doHash() {
@@ -178,9 +191,10 @@ public abstract class object {
   /**
    * for use by Vorba agent to reflect state of vamsas object to client
    * application.
-   * 
-   * @param __stored_in_document
-   *          The __stored_in_document to set.
+   * Setting stored_in_document on a registerable object without a 
+   * vorbaId will mean is will *never* get a vorbaId and 
+   * horrible things will happen.
+   * @param __stored_in_document true if object has been marshalled into current document.
    */
   protected void set__stored_in_document(boolean __stored_in_document) {
     this.__stored_in_document = __stored_in_document;
@@ -198,18 +212,16 @@ public abstract class object {
   }
 
   /**
-   * @return Returns the registerable.
+   * @return true if object can have a vorbaId
    */
   public boolean isRegisterable() {
     return registerable;
   }
 
   /**
-   * Called during unmarshalling - if object has an id string, it is
-   * registerable.
-   * 
-   * @param registerable
-   *          The registerable to set.
+   * Called by __testInstanceForidField and the post-unmarshalling handler
+   * to indicate if object will have a vorbaId.
+   * @param registerable 
    */
   protected void setRegisterable(boolean registerable) {
     this.registerable = registerable;
@@ -220,6 +232,10 @@ public abstract class object {
    * calling the same method on them.
    * TODO: LATER: properly apply castors own field mechanisms to get at accessors
    * TODO: FIX CYCLIC __ensure+instance_ids
+   * Implementation note for the todo:
+   * this works like a depth-first search over all vamsas objects in an vamsasDocument. 
+   * The doHash() function is used as the 'visited' flag - 
+   * this *is not* a valid heuristic, although it will work "most of the time". 
    */
   protected void __ensure_instance_ids() {
     if (__vorba==null)