org.concord.biologica.engine
Class SpeciesAllele

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

All Implemented Interfaces:

org.xml.sax.DocumentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, INucleicAcidHolder, java.io.Serializable

public final class SpeciesAllele

extends EngineObject

implements INucleicAcidHolder, java.io.Serializable

This class represents a species allele - a known, fixed variation of a species gene.

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

• EngineProp.BASE_VALUES - base values for allele's raw nucleic acid changed
• EngineProp.DELETED - object has been deleted
• EngineProp.DESCRIPTION - the object description has changed
• EngineProp.ID - object's id has changed
• EngineProp.LOCKED_STATE - the object's locked state has changed
• EngineProp.MUTATION_ALLELE - this is the allele used when there is a weird mutation
• EngineProp.TEXT_SYMBOL - text symbol for allele changed
• EngineProp.VISIBLE - visible, typically used for mutation allele becoming visible when user edits DNA
• EngineProp.WEIGHT - probabalistic weight of this allele relative to other alleles of this gene

Version:

$Revision: 1.1.1.1 $ $Date: 2001/04/28 00:39:15 $

Author:

$Author: ed $

See Also:

EngineProp.BASE_VALUES, EngineProp.DELETED, EngineProp.DESCRIPTION, EngineProp.ID, EngineProp.LOCKED_STATE, EngineProp.MUTATION_ALLELE, EngineProp.TEXT_SYMBOL, EngineProp.VISIBLE, EngineProp.WEIGHT, PropertyChangeListener, Serialized Form

Fields inherited from class org.concord.biologica.engine.EngineObject

AUTOMATIC_LOCKED, AUTOMATIC_LOCKED_STRING, changes, deleted, FALSE, id, lockedState, MANUAL_AND_AUTOMATIC_LOCKED, MANUAL_AND_AUTOMATIC_LOCKED_STRING, MANUAL_LOCKED, MANUAL_LOCKED_STRING, NULL_ID, TRUE, UNLOCKED, UNLOCKED_STRING, xmlElementContext

Constructor Summary

SpeciesAllele(Gene aGene, java.lang.String aTextSymbol, byte[] baseValues)
Create a new allele given a gene and the base values to use.

SpeciesAllele(Gene aGene, java.lang.String anElementName, int anElementID, com.sun.xml.parser.Parser anXMLParser, ImportContext importContext)
Create a new species allele and start handling XML parsing events to set the properties of this object.

Method Summary

void	addNucleicAcid(INucleicAcid aNucleicAcid) Adds a nucleic acid to the holder.
void	characters(char[] ch, int start, int length) Receive notification of character data.
void	delete() Delete this object, notifying parent objects and deleting any child objects.
void	delete(boolean notifyChange)
void	endElement(java.lang.String anElementName) Handle notification that the parsing of the given element has ended.
byte	getBase(int index) Returns the base value at the given index in this allele.
byte[]	getBases() Get the base values array for this allele.
java.lang.String	getBasesAsString() Get the bases as a String of characters A,T,C and G.
java.lang.String	getDescription() Return the description of this allele.
Gene	getGene() Returns the allele's gene.
int	getLengthInBases() Returns the length of the allele in bases.
int	getLengthInCodons() Returns the length of the allele in codons.
Species	getSpecies() Get the species containing this object.
SpeciesChromosome	getSpeciesChromosome() Get the species chromosome containing this object.
int	getStartIndexInHolder() Returns the start index of this nucleic acid in its holder.
java.lang.String	getTextSymbol() Returns the allele's text symbol.
int	getWeight() Get the weight of this allele.
World	getWorld() Get the world containing this object.
void	ignorableWhitespace(char[] ch, int start, int length) Receive notification of ignorable white space character data.
boolean	isMutationAllele() Is this allele the mutation allele for its gene?
boolean	isVisible() Is this allele visible?
boolean	matchBases(byte[] inputBases) Do the input bases match the bases of this allele?
boolean	removeNucleicAcid(INucleicAcid aNucleicAcid) Removes a nucleic acid from the holder.
void	setAutomaticLocked(boolean automaticLocked) Set or unset the automatic locked state of this object, leaving other components of the locked state untouched.
void	setBase(int index, byte newBase) Sets the base value at the given index in this allele.
void	setBases(byte[] newBases) Sets the base values array for this allele.
void	setBasesAsString(java.lang.String bases) Sets the bases for this allele using a String as input.
void	setDescription(java.lang.String aDescription) Set the description of this allele.
void	setLockedState(int aLockedState) Set the lock state of the object, recursively setting the lock state of children objects.
void	setManualLocked(boolean manualLocked) Set or unset the manual locked state of this object, leaving other components of the locked state untouched.
void	setMutationAllele(boolean aMutationAllele) Set whether or not this allele is the mutation allele for its gene.
void	setTextSymbol(java.lang.String aTextSymbol) Set the text symbol of the allele.
void	setVisible(boolean aVisible) Set whether or not this allele is visible.
void	setWeight(int aWeight) Set the weight of this allele.
void	startElement(java.lang.String anElementName, org.xml.sax.AttributeList amap) Handle notification that the parser has hit the start of a new element with the given name and attributes.
java.lang.String	toString() Return a string representation of this object, usually the object's name.
void	writeToStream(java.io.PrintWriter stream) Writes this object to the given stream in XML format.

Methods inherited from class org.concord.biologica.engine.EngineObject

addPropertyChangeListener, getID, getLockedState, getLockedStateAsString, isAutomaticLocked, isDeleted, isLocked, isManualLocked, notifySelected, release, removePropertyChangeListener, setID, setLockedStateAsString

Methods inherited from class org.xml.sax.HandlerBase

endDocument, error, fatalError, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, startDocument, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.concord.biologica.engine.INucleicAcidHolder

getID

Constructor Detail

SpeciesAllele

public SpeciesAllele(Gene aGene,
                     java.lang.String aTextSymbol,
                     byte[] baseValues)

Create a new allele given a gene and the base values to use.

Parameters:

aGene - Gene - the gene of this allele, may not be null

aTextSymbol - String - textual symbol of this allele (e.g. "h", "H"), may not be null

baseValues - byte[] - base values array, may not be null or zero length

Throws:

java.lang.IllegalArgumentException - - input argument(s) illegal

SpeciesAllele

public SpeciesAllele(Gene aGene,
                     java.lang.String anElementName,
                     int anElementID,
                     com.sun.xml.parser.Parser anXMLParser,
                     ImportContext importContext)

Create a new species allele and start handling XML parsing events to set the properties of this object.

Parameters:

aGene - Gene - the enclosing gene for this new species allele

anElementName - String - the element name

anElementID - int - the element id

anXMLParser - com.sun.xml.parser.Parser - the element parser

importContext - ImportContext - import context for mapping ids from file to this world

Throws:

java.lang.IllegalArgumentException - - input arguments illegal

Method Detail

startElement

public void startElement(java.lang.String anElementName,
                         org.xml.sax.AttributeList amap)
                  throws org.xml.sax.SAXException

Handle notification that the parser has hit the start of a new element with the given name and attributes.

For internal elements (elements that are non-EngineObject instance variables of this object), call xmlElementContext.startElement() and xmlElementContext will receive the remaining element notifications. For external elements (elements that are EngineObject instance variables of this object), create an object of the appropriate class and that object will receive the remaining element notifications.

Overrides:

startElement in class org.xml.sax.HandlerBase

Parameters:

anElementName - String - name of element

amap - AttributeList - an attribute list

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws org.xml.sax.SAXException

Receive notification of character data.

Overrides:

characters in class org.xml.sax.HandlerBase

Parameters:

ch - char[] - characters

start - int - start of string

length - int - length of string

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws org.xml.sax.SAXException

Receive notification of ignorable white space character data.

Overrides:

ignorableWhitespace in class org.xml.sax.HandlerBase

Parameters:

ch - char[] - characters

start - int - start of string

length - int - length of string

endElement

public void endElement(java.lang.String anElementName)
                throws org.xml.sax.SAXException

Handle notification that the parsing of the given element has ended.

Specified by:

endElement in interface INucleicAcidHolder

Overrides:

endElement in class org.xml.sax.HandlerBase

Parameters:

anElementName - String - the element name

delete

public void delete()

Delete this object, notifying parent objects and deleting any child objects.

When this method is called, a property change event is generated for the property named EngineProp.DELETED.

Overrides:

delete in class EngineObject

delete

public void delete(boolean notifyChange)

setAutomaticLocked

public void setAutomaticLocked(boolean automaticLocked)

Set or unset the automatic locked state of this object, leaving other components of the locked state untouched. Recursively sets the automatic locked state of children of this object.

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

Overrides:

setAutomaticLocked in class EngineObject

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. Recursively sets the manual locked state of children of this object.

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

Overrides:

setManualLocked in class EngineObject

Parameters:

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

setLockedState

public void setLockedState(int aLockedState)

Set the lock state of the object, recursively setting the lock state of children objects.

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

Overrides:

setLockedState in class EngineObject

Parameters:

aLockedState - int - new locked state of this object

Throws:

java.lang.IllegalArgumentException - - new locked state invalid

toString

public java.lang.String toString()

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

Overrides:

toString in class EngineObject

Returns:

String - string representation of object

isMutationAllele

public boolean isMutationAllele()

Is this allele the mutation allele for its gene?

Returns:

boolean - mutation allele for its gene?

setMutationAllele

public void setMutationAllele(boolean aMutationAllele)

Set whether or not this allele is the mutation allele for its gene.

Parameters:

aMutationAllele - boolean - is this allele the mutation allele for its gene?

isVisible

public boolean isVisible()

Is this allele visible?

Returns:

boolean - visible?

setVisible

public void setVisible(boolean aVisible)

Set whether or not this allele is visible.

Parameters:

aVisible - boolean - is this allele visible?

getTextSymbol

public java.lang.String getTextSymbol()

Returns the allele's text symbol.

Returns:

String - allele's text symbol

setTextSymbol

public void setTextSymbol(java.lang.String aTextSymbol)

Set the text symbol of the allele.

Parameters:

aTextSymbol - String - new text symbol for object, may not be null

Throws:

java.lang.IllegalArgumentException - - input argument illegal

ObjectDeletedException - - object is deleted and cannot be modified

ObjectLockedException - - object is locked and cannot be deleted

getGene

public Gene getGene()

Returns the allele's gene.

Returns:

Gene - allele's gene, may not be null

getSpeciesChromosome

public SpeciesChromosome getSpeciesChromosome()

Get the species chromosome containing this object.

Returns:

SpeciesChromosome - the species chromosome containing this object, never null.

getSpecies

public Species getSpecies()

Get the species containing this object.

Returns:

Species - the species containing this object, never null.

getWorld

public World getWorld()

Get the world containing this object.

Specified by:

getWorld in interface INucleicAcidHolder

Overrides:

getWorld in class EngineObject

Returns:

World - the world containing this object, never null.

getLengthInBases

public int getLengthInBases()

Returns the length of the allele in bases.

Returns:

int - length of this autosome in bases

getLengthInCodons

public int getLengthInCodons()

Returns the length of the allele in codons. Note that this is calculated by dividing the number of bases by 3, ignoring bases which may not fit evenly into multiples of 3 (codons).

Returns:

int - length of this autosome in codons

getBase

public byte getBase(int index)

Returns the base value at the given index in this allele. Note that this value is along one strand. If the value of the other strand is desired, use Base.getPairBase().

Parameters:

index - int - index into allele, must be 0 to length of allele-1

Returns:

byte - base value at given index

Throws:

java.lang.IllegalArgumentException - - input argument(s) illegal

See Also:

Base.getPairBase(byte, int)

getBasesAsString

public java.lang.String getBasesAsString()

Get the bases as a String of characters A,T,C and G.

Returns:

String - bases in a string using A,T,C and G characters

setBase

public void setBase(int index,
                    byte newBase)

Sets the base value at the given index in this allele.

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

Parameters:

index - int - index into allele, must be 0 to length of allele-1

newBase - byte - new base value at given index

Throws:

java.lang.IllegalArgumentException - - input argument(s) illegal

ObjectDeletedException - - object is deleted and cannot be modified

ObjectLockedException - - object is locked and cannot be deleted

getBases

public byte[] getBases()

Get the base values array for this allele.

Returns:

byte[] - base values as a byte array

setBases

public void setBases(byte[] newBases)

Sets the base values array for this allele.

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

Parameters:

newBases - byte[] - new base values array

Throws:

java.lang.IllegalArgumentException - - input argument(s) illegal

ObjectDeletedException - - object is deleted and cannot be modified

ObjectLockedException - - object is locked and cannot be deleted

setBasesAsString

public void setBasesAsString(java.lang.String bases)

Sets the bases for this allele using a String as input. The String must have character values 'A','a','C','c','G','g','T','t' or an IllegalArgumentException will be thrown.

Parameters:

String - - bases in a string using A,T,C and G characters, may be null

Throws:

java.lang.IllegalArgumentException - - input argument(s) illegal

ObjectDeletedException - - object is deleted and cannot be modified

ObjectLockedException - - object is locked and cannot be deleted

matchBases

public boolean matchBases(byte[] inputBases)

Do the input bases match the bases of this allele?

Parameters:

inputBases - byte[] - input bases

Returns:

boolean - true (they match) or false (they don't match)

getStartIndexInHolder

public int getStartIndexInHolder()

Returns the start index of this nucleic acid in its holder.

For an allele, this is always zero as the allele's position in the chromosome isn't known to the allele, but rather its gene.

Returns:

int - index in holder

addNucleicAcid

public void addNucleicAcid(INucleicAcid aNucleicAcid)

Adds a nucleic acid to the holder.

This SHOULD be package protected because this is only to be called from the nucleic acid's constructor. Creating a nucleic acid automatically adds it to the holder via this method.

BUT, Java has some wierd idea that interface methods are always public, so I can't make this package protected. So please don't use them method from outside of the engine package!!

Specified by:

addNucleicAcid in interface INucleicAcidHolder

Parameters:

aNucleicAcid - INucleicAcid - a new nucleic acid, may not be null

Throws:

java.lang.IllegalArgumentException - - input argument illegal

removeNucleicAcid

public boolean removeNucleicAcid(INucleicAcid aNucleicAcid)

Removes a nucleic acid from the holder.

This SHOULD be package protected because this is only to be called from the nucleic acid's delete method. Deleting a nucleic acid automatically removes it from the holder via this method.

BUT, Java has some wierd idea that interface methods are always public, so I can't make this package protected. So please don't use them method from outside of the engine package!!

Specified by:

removeNucleicAcid in interface INucleicAcidHolder

Parameters:

aNucleicAcid - INucleicAcid - a nucleic acid, may not be null

Returns:

boolean indicating whether or not the nucleic acid was found and removed

Throws:

java.lang.IllegalArgumentException - - input argument illegal

getWeight

public int getWeight()

Get the weight of this allele.

Returns:

int - weight of this allele

setWeight

public void setWeight(int aWeight)

Set the weight of this allele.

Parameters:

aWeight - int - new weight of this allele, must be zero or greater

Throws:

java.lang.IllegalArgumentException - - weight less than zero

getDescription

public java.lang.String getDescription()

Return the description of this allele. May be null.

Returns:

String - description of this allele, may not be null.

setDescription

public void setDescription(java.lang.String aDescription)

Set the description of this allele.

When this method is successful, a property change event is fired for the property named EngineProp.DESCRIPTION.

Parameters:

aDescription - String - the new description of this allele, may not be null

Throws:

java.lang.IllegalArgumentException - - input argument illegal

ObjectDeletedException - - object is deleted and cannot be modified

ObjectLockedException - - object is locked and cannot be modified

writeToStream

public 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.

Overrides:

writeToStream in class EngineObject

Parameters:

stream - PrintWriter - print stream

Throws:

java.lang.IllegalArgumentException - - input arguments illegal

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