org.concord.biologica.engine
Class EngineObject

java.lang.Object
  |
  +--org.xml.sax.HandlerBase
        |
        +--org.concord.biologica.engine.EngineObject

All Implemented Interfaces:

org.xml.sax.DocumentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

Direct Known Subclasses:

AlgorithmicNucleicAcid, Characteristic, Environment, Family, Gene, GenotypeToPhenotypeRule, NucleicAcid, Organism, OrganismAllele, OrganismAllelePair, OrganismChromosome, OrganismChromosomePair, OrganismImage, RawNucleicAcid, Species, SpeciesAllele, SpeciesChromosome, SpeciesImage, SpeciesImageColumn, SpeciesImageRow, Terrain, Trait, World

public abstract class EngineObject

extends org.xml.sax.HandlerBase

This abstract class is the base for all BioScope engine classes and defines the basic API's that all engine classes must implement.

An object of this class will generate the following property change events:

• EngineProp.ID - object's id has changed
• EngineProp.DELETED - object has been deleted
• EngineProp.LOCKED_STATE - the locked state of the object has changed

Version:

$Revision: 1.2 $ $Date: 2002/03/11 16:54:46 $

Author:

$Author: ed $

See Also:

EngineProp.ID, EngineProp.DELETED, EngineProp.LOCKED_STATE

Field Summary

static int	AUTOMATIC_LOCKED Automatic lock value.
static java.lang.String	AUTOMATIC_LOCKED_STRING
protected org.concord.biologica.engine.LocalPropertyChangeSupport	changes Utility object which manages property change events and listeners.
protected boolean	deleted Indicates if this object has been deleted and is waiting for garbage collection.
protected static java.lang.Boolean	FALSE FALSE Boolean object.
protected int	id Identifier for engine object, used when saving and restoring the object to and from a file.
protected int	lockedState Current locked state of this object - see above LOCKED statics.
static int	MANUAL_AND_AUTOMATIC_LOCKED Manual and automatic locked value.
static java.lang.String	MANUAL_AND_AUTOMATIC_LOCKED_STRING
static int	MANUAL_LOCKED Manual locked value.
static java.lang.String	MANUAL_LOCKED_STRING
static int	NULL_ID Null ID value.
protected static java.lang.Boolean	TRUE TRUE Boolean object.
static int	UNLOCKED Unlocked locked value.
static java.lang.String	UNLOCKED_STRING
protected ElementContext	xmlElementContext XML Element context used when reading an element this object from a file.

Constructor Summary

EngineObject()
Creates engine object, giving the object a proper ID.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener aListener) Add a property change listener for properties.
abstract void	delete() Deletes the object, notifying any containing objects and deleting any child objects.
int	getID() Returns the ID of this object.
int	getLockedState() Get locked state of this object.
java.lang.String	getLockedStateAsString() Get locked state of this object as a string.
abstract World	getWorld() Get the world containing this object.
boolean	isAutomaticLocked() Is the object automatic locked? Ignores other components of the locked state.
boolean	isDeleted() Get whether or not this object is deleted.
boolean	isLocked() Get locked state as a boolean.
boolean	isManualLocked() Is the object manual locked? Ignores other components of the locked state.
void	notifySelected(boolean oldSelectedState, boolean newSelectedState) Notify listeners that the selected state of this object has changed.
void	release()
void	removePropertyChangeListener(java.beans.PropertyChangeListener aListener) Remove a property change listener for properties.
void	setAutomaticLocked(boolean automaticLocked) Set or unset the automatic locked state of this object, leaving other components of the locked state untouched.
void	setID(int anID) Set the id of the object.
void	setLockedState(int aLockedState) Set the locked state of the object.
void	setLockedStateAsString(java.lang.String aLockedState) Set locked state of this object using a string.
void	setManualLocked(boolean manualLocked) Set or unset the manual locked state of this object, leaving other components of the locked state untouched.
abstract java.lang.String	toString() Return a string representation of this object, usually the object's name.
abstract void	writeToStream(java.io.PrintWriter stream) Writes this object to the given stream in XML format.

Methods inherited from class org.xml.sax.HandlerBase

characters, endDocument, endElement, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, startDocument, startElement, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NULL_ID

public static final int NULL_ID

Null ID value. Illegal value in normal cases.

UNLOCKED

public static final int UNLOCKED

Unlocked locked value. This means the object has neither a manual nor an automatic lock on it.

UNLOCKED_STRING

public static final java.lang.String UNLOCKED_STRING

MANUAL_LOCKED

public static final int MANUAL_LOCKED

Manual locked value. This type of lock occurs when the user explicitly, manually locks an object.

MANUAL_LOCKED_STRING

public static final java.lang.String MANUAL_LOCKED_STRING

AUTOMATIC_LOCKED

public static final int AUTOMATIC_LOCKED

Automatic lock value. This type of lock occurs when BioLogica automatically locks an object due to some heuristic (e.g. species are automatically locked when an organism of that species is created, organisms are automatically locked when they are in a family with children (as either the parent or child)).

AUTOMATIC_LOCKED_STRING

public static final java.lang.String AUTOMATIC_LOCKED_STRING

MANUAL_AND_AUTOMATIC_LOCKED

public static final int MANUAL_AND_AUTOMATIC_LOCKED

Manual and automatic locked value. A convenience.

MANUAL_AND_AUTOMATIC_LOCKED_STRING

public static final java.lang.String MANUAL_AND_AUTOMATIC_LOCKED_STRING

TRUE

protected static final java.lang.Boolean TRUE

TRUE Boolean object.

FALSE

protected static final java.lang.Boolean FALSE

FALSE Boolean object.

id

protected int id

Identifier for engine object, used when saving and restoring the object to and from a file. IDs are not reused and range from 1 to Integer.MAX_VALUE. Zero and all negative integers are illegal id values.

When this property is changed, a property change event is generated for the property named EngineProp.ID.

deleted

protected boolean deleted

Indicates if this object has been deleted and is waiting for garbage collection.

When this property is changed, a property change event is generated for the property named EngineProp.DELETED. It is up to the derived class to fire this event.

lockedState

protected int lockedState

Current locked state of this object - see above LOCKED statics.

xmlElementContext

protected transient ElementContext xmlElementContext

XML Element context used when reading an element this object from a file.

changes

protected transient org.concord.biologica.engine.LocalPropertyChangeSupport changes

Utility object which manages property change events and listeners.

Constructor Detail

EngineObject

public EngineObject()

Creates engine object, giving the object a proper ID.

Method Detail

getID

public final int getID()

Returns the ID of this object.

Returns:

int - id of this object

setID

public void setID(int anID)

Set the id of the object. This method should be called with great care, as giving multiple objects the same ID can be disastrous. In general, this method should only be called during serialization.

When this property is changed, a property change event is fired for the property named EngineProp.ID.

Parameters:

anID - int - new ID for object.

isDeleted

public final boolean isDeleted()

Get whether or not this object is deleted.

Returns:

boolean - is object deleted?

setAutomaticLocked

public void setAutomaticLocked(boolean automaticLocked)

Set or unset the automatic locked state of this object, leaving other components of the locked state untouched. When this property is changed, a property change event is fired for the property named EngineProp.LOCKED_STATE.

It's expected that most derived classes will override this method and recursively lock their children.

Parameters:

automaticLocked - boolean - object should be automatic locked (true) or not (false)

setManualLocked

public void setManualLocked(boolean manualLocked)

Set or unset the manual locked state of this object, leaving other components of the locked state untouched. When this property is changed, a property change event is fired for the property named EngineProp.LOCKED_STATE.

It's expected that most derived classes will override this method and recursively lock their children.

Parameters:

manualLocked - boolean - object should be manually locked (true) or not (false)

setLockedState

public void setLockedState(int aLockedState)

Set the locked state of the object. This sets the whole state, clearing out any existing locked state entirely. In general, it's better to use one of the other set methods for locked state - setManualLockedState, etc. - as they operate on a specific bit of the locked state, not the whole locked state int.

When this property is changed, a property change event is fired for the property named EngineProp.LOCKED_STATE.

It's expected that most derived classes will override this method and recursively lock their children.

Parameters:

aLockedState - int - new locked state of this object

Throws:

java.lang.IllegalArgumentException - - new locked state invalid

setLockedStateAsString

public final void setLockedStateAsString(java.lang.String aLockedState)

Set locked state of this object using a string.

Parameters:

aLockedState - String - locked state as a string

Throws:

java.lang.IllegalArgumentException - - new locked state invalid

isLocked

public final boolean isLocked()

Get locked state as a boolean. Will return true if the object is locked for any reason, false if it is not locked for any reason.

Returns:

boolean - object is locked (true) or not locked (false)

isAutomaticLocked

public final boolean isAutomaticLocked()

Is the object automatic locked? Ignores other components of the locked state.

Returns:

boolean - object is automatic locked (true) or not locked (false)

isManualLocked

public final boolean isManualLocked()

Is the object manual locked? Ignores other components of the locked state.

Returns:

boolean - object is manual locked (true) or not locked (false)

getLockedState

public final int getLockedState()

Get locked state of this object.

Returns:

int - locked state of this object

getLockedStateAsString

public final java.lang.String getLockedStateAsString()

Get locked state of this object as a string.

Returns:

String - locked state as a string

notifySelected

public final void notifySelected(boolean oldSelectedState,
                                 boolean newSelectedState)

Notify listeners that the selected state of this object has changed. The object DOES NOT maintain its selected state! This method is just provided as a convenience function to notify listeners. This was initially created for notifying nodes in the TreeView that the selection state of a node has changed, as there was no other reasonable way to do it.

Parameters:

oldSelectedState - boolean - old selected state

newSelectedState - boolean - new selected state

getWorld

public abstract World getWorld()

Get the world containing this object.

Returns:

World - the world containing this object, never null.

delete

public abstract void delete()

Deletes the object, notifying any containing objects and deleting any child objects.

A default method could be supplied, but every derived class must implement this method, so we chose not to implement one to force the compiler to complain if the derived class doesn't implement this method.

A derived class's implementation of this method should at least have:

		id = NULL_ID;
		deleted = true;
 

When this method is called, the implementing class must fire a property change event for the property named EngineProp.DELETED.

release

public void release()

toString

public abstract java.lang.String toString()

Return a string representation of this object, usually the object's name.

Overrides:

toString in class java.lang.Object

Returns:

String - string representation of object

writeToStream

public abstract void writeToStream(java.io.PrintWriter stream)
                            throws java.io.IOException

Writes this object to the given stream in XML format. Usually this method is used to write the object to a file for saving it, but that is potentially not the only use.

We could supply a default implementation that knows how to write the id value. But that convenience is not chosen because it's never correct to use just this implementation of these methods, so I'd rather have a compilation fail if a derived class fails to implement this method.

The inverse of this method is a constructor that takes a org.xml.sax.Parser argument and other arguments.

Parameters:

stream - PrintWriter - print stream

Throws:

java.lang.IllegalArgumentException - - input arguments illegal

java.io.IOException - - an IO error occurred in java libraries

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener aListener)

Add a property change listener for properties.

Parameters:

aListener - PropertyChangeListener - a new listener

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener aListener)

Remove a property change listener for properties.

Parameters:

aListener - PropertyChangeListener - a listener to remove