uk.ac.vamsas.client
Class Vobject

java.lang.Object
  extended byuk.ac.vamsas.client.Vobject
Direct Known Subclasses:
Alignment, AnnotationElement, AppData, DataSet, DbRef, Entry, Glyph, Link, LockFile, MapList, MapType, Newick, NodeType, Param, Pos, Property, Provenance, Range, RangeType, ReferenceType, Score, Seg, SequenceType, Tree, VAMSAS, VamsasDocument

public abstract class Vobject
extends java.lang.Object

Base class for all Vamsas objects extracted from an IClientDocument. An Vobject maybe registered or unregistered.

Author:
jimp

Field Summary
protected  boolean __added_since_last_read
          true if Vobject appeared in the document after the last access by this vamsas library instance
protected  int __last_hash
          memory of the last doHash() value computed for the Vobject
protected  boolean __stored_in_document
          true if Vobject was stored in a vamsas Document or has been retrieved from it
protected  boolean __updated_since_last_read
          true if Vobject was updated since the vamsas library last read a Vobj with the same VorbaId from a document.
protected  boolean __visited
           
protected  IVorbaIdFactory __vorba
          the source of unique VorbaIds.
protected  boolean registerable
          set by testInstanceForIdField() if Vobject should have a VorbaId
protected  Vobject V_parent
          reference to containing object for this Vobject.
protected  VorbaId vorbaId
          unique id for all vamsas objects allows unambiguous referencing to any Vobject in the vamsas document
 
Constructor Summary
protected Vobject()
           
 
Method Summary
protected  int __callHash()
          calls the castor-generated hashCode() method
protected  void __ensure_instance_ids()
          ensure's internal id field corresponds to vorbaId and cascade through all fields referring to an instance of Vobject calling the same method on them.
protected  void __ensure_instance_ids(boolean visited)
           
protected  java.lang.String __getInstanceIdField()
           
protected  long __getLHash()
          get the LhashValue for this object
protected  void __setFinalHash(long checksum)
          compute the final LhashValue as a difference between checksum and the current base
protected  void __setInitHash(long checksum)
          set the base LhashValue for this object
protected  boolean doHash()
          calculate a hash for the Vobject with all housekeeping fields at standard values.
protected  void finalize()
           
 long get__last_hash()
          __last_hash is the hash value computed when the Vobject was last checked against a IClientDocument generated by the Vobject's parent IClient instance.
 Vobject getV_parent()
           
 VorbaId getVorbaId()
          Method to get fixed reference for the Vobject in the vamsas document.
 int hashCode()
          Override Object.hashCode with base value for castor generated object hashcodes.
 boolean is__stored_in_document()
           
 boolean isNewInDocument()
           
 boolean isRegisterable()
           
 boolean isRegistered()
           
 boolean isUpdated()
           
protected  boolean merge(Vobject laterCopy)
          TODO: combine two versions of the same collection Vobject to resolve asynchronous updates to the same vamsas Vobject Merges two vamsas objects, one of which is a later version of the earlier (ie they have the same vorbaId but one is a later version recently read from the vamsasDocument collection.
protected  void set__added_since_last_read(boolean __added_since_last_read)
           
protected  void set__stored_in_document(boolean __stored_in_document)
          for use by Vorba agent to reflect state of vamsas Vobject to client application.
protected  void set__updated_since_last_read(boolean __updated_since_last_read)
          Set internal flag to indicate this object was updated since the last document read
protected  void setInstanceIdField()
          update the Vobject instance's _id field, based on the contents of the VorbaId.
protected  void setRegisterable(boolean registerable)
          Called by __testInstanceForidField and the post-unmarshalling handler to indicate if Vobject will have a vorbaId.
protected  void setV_parent(Vobject V_parent)
           
protected  void setVorbaId(VorbaId newid)
          used by the IClient implementation to generate unique Id based on client applications current namespace.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

__stored_in_document

protected boolean __stored_in_document
true if Vobject was stored in a vamsas Document or has been retrieved from it


__updated_since_last_read

protected boolean __updated_since_last_read
true if Vobject was updated since the vamsas library last read a Vobj with the same VorbaId from a document.


__added_since_last_read

protected boolean __added_since_last_read
true if Vobject appeared in the document after the last access by this vamsas library instance


__last_hash

protected int __last_hash
memory of the last doHash() value computed for the Vobject

See Also:
doHash()

registerable

protected boolean registerable
set by testInstanceForIdField() if Vobject should have a VorbaId


__visited

protected boolean __visited

V_parent

protected Vobject V_parent
reference to containing object for this Vobject.


vorbaId

protected VorbaId vorbaId
unique id for all vamsas objects allows unambiguous referencing to any Vobject in the vamsas document


__vorba

protected IVorbaIdFactory __vorba
the source of unique VorbaIds.

Constructor Detail

Vobject

protected Vobject()
Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable
Throws:
java.lang.Throwable

hashCode

public int hashCode()
Override Object.hashCode with base value for castor generated object hashcodes.


setInstanceIdField

protected void setInstanceIdField()
update the Vobject instance's _id field, based on the contents of the VorbaId. Only call this if you mean to do it!


__getInstanceIdField

protected java.lang.String __getInstanceIdField()

__callHash

protected int __callHash()
calls the castor-generated hashCode() method

Returns:

doHash

protected boolean doHash()
calculate a hash for the Vobject with all housekeeping fields at standard values. (isRegisterable is an immutable attribute property) TODO: LATER: make this hash function compute a hash that truly reflects changes in Vobject attributes for benefit of update mechanism

Returns:
true if new hash different to last hash (or first time its been computed)

merge

protected boolean merge(Vobject laterCopy)
TODO: combine two versions of the same collection Vobject to resolve asynchronous updates to the same vamsas Vobject Merges two vamsas objects, one of which is a later version of the earlier (ie they have the same vorbaId but one is a later version recently read from the vamsasDocument collection.

Returns:

isRegistered

public boolean isRegistered()
Returns:
true if Vobject is registered

getVorbaId

public VorbaId getVorbaId()
Method to get fixed reference for the Vobject in the vamsas document.


setVorbaId

protected void setVorbaId(VorbaId newid)
used by the IClient implementation to generate unique Id based on client applications current namespace.


is__stored_in_document

public boolean is__stored_in_document()
Returns:
true if Vobject is present in Vamsas Document.

isUpdated

public boolean isUpdated()
Returns:
true if this object has been updated in the currently stored document since the last time a Vobject with the same ID was read from a Vamsas Document

isNewInDocument

public boolean isNewInDocument()
Returns:
true if this object was added to the document after the last time the vamsas library acessed the session document

set__updated_since_last_read

protected void set__updated_since_last_read(boolean __updated_since_last_read)
Set internal flag to indicate this object was updated since the last document read

Parameters:
__updated_since_last_read - the __updated_since_last_read to set

set__stored_in_document

protected void set__stored_in_document(boolean __stored_in_document)
for use by Vorba agent to reflect state of vamsas Vobject to client application. Setting stored_in_document on a registerable Vobject without a vorbaId will mean is will *never* get a vorbaId and horrible things will happen.

Parameters:
__stored_in_document - true if Vobject has been marshalled into current document.

set__added_since_last_read

protected void set__added_since_last_read(boolean __added_since_last_read)
Parameters:
__added_since_last_read - the __added_since_last_read to set

get__last_hash

public long get__last_hash()
__last_hash is the hash value computed when the Vobject was last checked against a IClientDocument generated by the Vobject's parent IClient instance.

Returns:
Returns the __last_hash.

isRegisterable

public boolean isRegisterable()
Returns:
true if Vobject can have a vorbaId

setRegisterable

protected void setRegisterable(boolean registerable)
Called by __testInstanceForidField and the post-unmarshalling handler to indicate if Vobject will have a vorbaId.

Parameters:
registerable -

__ensure_instance_ids

protected void __ensure_instance_ids()
ensure's internal id field corresponds to vorbaId and cascade through all fields referring to an instance of Vobject 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. __visited is the visited flag, any Vobj who's flag is of a different parity to the visited argument will be recursed on. note - the doHash() function used to be used as the 'visited' flag - this *is not* a valid heuristic, although it will work "most of the time". TODO: LATER? Add another method for setDefaultProvenanceField (in the spirit of setInstanceIdField) using the info from the __vorba.getClient/User/Session methods


__ensure_instance_ids

protected void __ensure_instance_ids(boolean visited)

getV_parent

public Vobject getV_parent()
Returns:
the __parent

setV_parent

protected void setV_parent(Vobject V_parent)

__setInitHash

protected void __setInitHash(long checksum)
set the base LhashValue for this object

Parameters:
checksum -

__setFinalHash

protected void __setFinalHash(long checksum)
compute the final LhashValue as a difference between checksum and the current base

Parameters:
checksum -

__getLHash

protected long __getLHash()
get the LhashValue for this object

Returns:
the difference in values passed to __setFinalHash less __setInitHash