org.jscience.biology.taxonomy
Interface TaxonFactory

All Known Implementing Classes:
SimpleTaxonFactory, WeakTaxonFactory

public interface TaxonFactory

Factory for handling a particular implementation of a Taxon.


Method Summary
 Taxon addChild(Taxon parent, Taxon child)
          Add a taxon as a child to a parent.
 Taxon createTaxon(java.lang.String scientificName, java.lang.String commonName)
          Create a new orphan Taxon with a given scientific and common name.
 java.lang.String getName()
          Name for this TaxonFactory.
 Taxon getRoot()
          Retrieve the root upon which all rooted Taxon that this factory knows about are rooted.
 Taxon importTaxon(Taxon source)
          Import a Taxon and all its children into the implementation provided by this factory.
 Taxon removeChild(Taxon parent, Taxon child)
          Remove a Taxon as a child to this one.
 Taxon search(java.lang.Object id)
          Retrieve a Taxon that matches some ID.
 

Method Detail

getName

java.lang.String getName()

Name for this TaxonFactory.

Returns:
the name of this TaxonFactory

importTaxon

Taxon importTaxon(Taxon source)

Import a Taxon and all its children into the implementation provided by this factory.

The return value of this method should be .equals() and .hasCode() compatable with the taxon parameter. It may not be implemented by the same underlying implementation.

Parameters:
source - the Taxon to copy
Returns:
a new Taxon

getRoot

Taxon getRoot()

Retrieve the root upon which all rooted Taxon that this factory knows about are rooted.

Returns:
the 'root' Taxon

search

Taxon search(java.lang.Object id)

Retrieve a Taxon that matches some ID.

This method is here out of desperation. It's nasty and should be replaced by some propper querying API. Without having different methods for every TaxonFactory I don't know what to do. All ideas appreciated.

Parameters:
id - the Object identifying a Taxon
Returns:
the Taxon matching the ID, or null if none match

createTaxon

Taxon createTaxon(java.lang.String scientificName,
                  java.lang.String commonName)

Create a new orphan Taxon with a given scientific and common name.

Parameters:
scientificName - the scientificName to give the Taxon
commonName - the common name to give the Taxon
Returns:
a new Taxon with no parent and no children

addChild

Taxon addChild(Taxon parent,
               Taxon child)
               throws CircularReferenceException

Add a taxon as a child to a parent.

The TaxonFactory may chose to add the child directly, or make a new object which is .equals() compatable with child. The actual Taxon instance inserted into the child set is returned by the add method.

Parameters:
parent - the parent Taxon to add the child to
child - the Taxon to add as a child
Returns:
the Taxon object actualy present as the child
Throws:
CircularReferenceException - if child is this Taxon or any of its parents

removeChild

Taxon removeChild(Taxon parent,
                  Taxon child)

Remove a Taxon as a child to this one.

This Taxon should attempt to remove a child that is .equals() compatable with child. If it is sucessful, it should return the Taxon instance that was removed. If not, it should return null.

Parameters:
parent - the parent Taxon to remove the child from
child - the Taxon to remove as a child
Returns:
the actual Taxon removed, or null if none were removed