
<section>
  <title>Implementation of the &seqapi;</title>

  <section>
    <title>The list elements</title>

    <para>It is common in bioinformatics to represent a biological
      sequence as a series of characters, or a string. This has the
      several advantages, the main advantages being simplicity. Also
      many languages have special facilities for dealing with
      strings. And finally characters are printable which can make
      help during development. The facilities that Java provides
      however are not very advanced however, so this advantage is
      lessened. </para>

    <para>The main disadvantage with using characters though is that
      they are of limited number (Java actually has 65536 of them, but
      of these are unprintable, or not readily identifiable from each
      other when printed). It is for this reason amoung others that
      &quot;type&quot; errors (is this 'C' a cysteine, or a cytosine?)
      become easy to make. Additionally using characters makes it
      impossible to attach other information (about the molecular
      mass) to the element, necessitating lookup tables. There is also
      an additional problem specific to Java which is that the
      &quot;char&quot; datatype is &quot;primitive&quot;, i.e. not a
      first class Java object. This means that it can not be passed or
      returned as an Object parameter. This means that it can not be
      used by any of the standard Java data structures without using
      an &quot;Character&quot; object wrapper. During coding this
      defeats any advantages of simplicity.</para>
    
    <para>For these reasons we have implemented the <classname>Element
      </classname> as a Java object. This interface implements just a
      single method...

      <programlisting>
    public interface Element 
    {
      public char toChar();
    }// Element
      </programlisting>

      This method helps to retain one of the advantages of using
      characters which is that is provides a natural way of printing
      sequences, without any of the associated disadvantages, as the
      char representation of an
      <classname>Element</classname> is not required to be
      unique.
    </para>

    <para>We have extended <classname>Element</classname> in
      two ways. Firstly with the
      <classname>Residue</</classname> interface. This is a
      simple &quot;tagging&quot; interface with no methods. Its the
      root interface for all Objects which are to represent residues,
      as opposed to Gaps. These are represented by their own class,
      called unsurprisingly <classname>Gap</classname>. This has been
      implemented using the &quot;Singleton&quot; design pattern.

      <programlisting>
    public class Gap extends Element
    {	
    	private Gap()
    	{}
    	
    	public char toChar()
    	{
    	  return '-';
    	}
    	
    	public String toString()
    	{
    	  return "Gap Element";
    	}
    	
    	public static final Gap gap = new Gap();
    }	
      </programlisting>

      As well as <classname>Gap</classname> we have also provided
      default implementations of common
      <classname>Element's</classname>. For example the
      <classname>DNAResidue</classname> extends Residue directly
      providing a tagging interface, and this is then extended by
      <classname>DNANucleotide</classname>. This is implemented as an
      Enumerated Type which in Java is provided by a variation on the
      theme of the Singleton design pattern

      <programlisting>

    public class DNANucleotide extends AbstractElement
      implements DNAResidue
    {
        private String full;
        private DNANucleotide ( char singleChar, String full, String toString )
        {
          super( toString, singleChar );
          this.full = full;
        }
            
        public static final DNANucleotide ADENOSINE =
          new DNANucleotide('A', "Adenosine", "DNANucleotide Adenosine");
        public static final DNANucleotide GUANINE =
          new DNANucleotide('G', "Guanine", "DNANucleotide Guanine");
        public static final DNANucleotide CYTOSINE =
          new DNANucleotide('C', "Cytosine", "DNANucleotide Cytosine");
        public static final DNANucleotide THIAMINE =
          new DNANucleotide('T', "Thiamine", "DNANucleotide ThIAmine");     
    }
      </programlisting>

      The super class <classname>AbstractElement</classname> provides
      several methods for managing enumerated types.</para> 
  </section>

  <section>
    <title>Sequence types. A collection of Elements</title>

    <para>One of the requirements for the &seqapi; was to provide a
      degree of &quot;type-checking&quot; for sequences to prevent a
      sequence of an inappropriate type being added to a Sequence. The
      most obvious way of doing this in Java would have been to use
      the type system. Therefore a DNA sequence would have for
      instance a method
      <function>DNANucleotide getElementAt( int index )</function>.
      The problem is that we would like all Sequences to share an
      common inheritance, so that classes which do not care about the
      type of the sequence can deal generically with all sequences. In
      Java we could do this by giving the super class a method
      <function>Element getElementAt( int index )</function>. Sadly
      this is illegal in Java, as this method has the same signature
      as one in a subclass, but a different return type. There are
      languages which can support this kind of type system. The
      language feature known as &quot;parameterised typing&quot; would
      for instance have served nicely. Its rather depressing to note
      that the foreword of version 1.0 of the Java Language
      Specification suggests that this is a good language feature
      which might be added someday. Sadly it is not here now, or we
      would have used it in this API. At the current time though we
      have had to conclude that it is not possible to use Java's type
      system to provide compile time safety. 
    </para>

    <para>Failing compile time safety we investigated the possibility
      of providing a fail fast runtime safety check. For this we need
      to be able to tell if an Element was a valid part of a given
      Sequence. The class <classname>SequenceType</classname>This
      provides one function of critical importance...

      <programlisting>
    public interface SequenceType
    {
	public boolean isElement( Element element );
    }
      </programlisting>

      as well as a number of other convienience and informational
      functions</para>

    <para>This class is used to implement all of the &quot;type
      checks&quot; that are performed in the Sequence class. </para>
    
  </section>
</section>

<!--
 We need to define local variables to enable psgml mode to work out
 what DTD we are using, and also where we are in the document.

 Local Variables: ***
 sgml-parent-document:("sequence.sgml" "article" "section" ) ***
 End: ***
 -->
