JAL-2046 clarify contract for copy constructor and initSeqFrom implementation
[jalview.git] / src / jalview / datamodel / Sequence.java
index c7581d8..fbe3670 100755 (executable)
 package jalview.datamodel;
 
 import jalview.analysis.AlignSeq;
+import jalview.api.DBRefEntryI;
 import jalview.util.StringUtils;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Enumeration;
 import java.util.List;
 import java.util.Vector;
@@ -55,6 +57,8 @@ public class Sequence extends ASequence implements SequenceI
 
   String vamsasId;
 
+  DBRefEntryI sourceDBRef;
+
   DBRefEntry[] dbrefs;
 
   RNA rna;
@@ -182,12 +186,13 @@ public class Sequence extends ASequence implements SequenceI
   }
 
   /**
-   * Creates a new Sequence object with new features, DBRefEntries,
-   * AlignmentAnnotations, and PDBIds but inherits any existing dataset sequence
-   * reference.
+   * Creates a new Sequence object with new AlignmentAnnotations but inherits
+   * any existing dataset sequence reference. If non exists, everything is
+   * copied.
    * 
    * @param seq
-   *          DOCUMENT ME!
+   *          if seq is a dataset sequence, behaves like a plain old copy
+   *          constructor
    */
   public Sequence(SequenceI seq)
   {
@@ -210,29 +215,48 @@ public class Sequence extends ASequence implements SequenceI
 
   }
 
+  /**
+   * does the heavy lifting when cloning a dataset sequence, or coping data from
+   * dataset to a new derived sequence.
+   * 
+   * @param seq
+   *          - source of attributes.
+   * @param alAnnotation
+   *          - alignment annotation present on seq that should be copied onto
+   *          this sequence
+   */
   protected void initSeqFrom(SequenceI seq,
           AlignmentAnnotation[] alAnnotation)
   {
-    initSeqAndName(seq.getName(), seq.getSequence(), seq.getStart(),
+    {
+      char[] oseq = seq.getSequence();
+      initSeqAndName(seq.getName(), Arrays.copyOf(oseq, oseq.length),
+              seq.getStart(),
             seq.getEnd());
+    }
     description = seq.getDescription();
-    if (seq.getSequenceFeatures() != null)
+    sourceDBRef = seq.getSourceDBRef() == null ? null : new DBRefEntry(
+            seq.getSourceDBRef());
+    if (seq != datasetSequence)
     {
-      SequenceFeature[] sf = seq.getSequenceFeatures();
-      for (int i = 0; i < sf.length; i++)
-      {
-        addSequenceFeature(new SequenceFeature(sf[i]));
-      }
+      setDatasetSequence(seq.getDatasetSequence());
     }
-    setDatasetSequence(seq.getDatasetSequence());
-    if (datasetSequence == null && seq.getDBRef() != null)
+    if (datasetSequence == null && seq.getDBRefs() != null)
     {
-      // only copy DBRefs if we really are a dataset sequence
-      DBRefEntry[] dbr = seq.getDBRef();
+      // only copy DBRefs and seqfeatures if we really are a dataset sequence
+      DBRefEntry[] dbr = seq.getDBRefs();
       for (int i = 0; i < dbr.length; i++)
       {
         addDBRef(new DBRefEntry(dbr[i]));
       }
+      if (seq.getSequenceFeatures() != null)
+      {
+        SequenceFeature[] sf = seq.getSequenceFeatures();
+        for (int i = 0; i < sf.length; i++)
+        {
+          addSequenceFeature(new SequenceFeature(sf[i]));
+        }
+      }
     }
     if (seq.getAnnotation() != null)
     {
@@ -261,11 +285,10 @@ public class Sequence extends ASequence implements SequenceI
     }
     if (seq.getAllPDBEntries() != null)
     {
-      Vector ids = seq.getAllPDBEntries();
-      Enumeration e = ids.elements();
-      while (e.hasMoreElements())
+      Vector<PDBEntry> ids = seq.getAllPDBEntries();
+      for (PDBEntry pdb : ids)
       {
-        this.addPDBId(new PDBEntry((PDBEntry) e.nextElement()));
+        this.addPDBId(new PDBEntry(pdb));
       }
     }
   }
@@ -276,13 +299,16 @@ public class Sequence extends ASequence implements SequenceI
    * @param v
    *          DOCUMENT ME!
    */
+  @Override
   public void setSequenceFeatures(SequenceFeature[] features)
   {
     sequenceFeatures = features;
   }
 
+  @Override
   public synchronized void addSequenceFeature(SequenceFeature sf)
   {
+    // TODO add to dataset sequence instead if there is one?
     if (sequenceFeatures == null)
     {
       sequenceFeatures = new SequenceFeature[0];
@@ -303,6 +329,7 @@ public class Sequence extends ASequence implements SequenceI
     sequenceFeatures = temp;
   }
 
+  @Override
   public void deleteFeature(SequenceFeature sf)
   {
     if (sequenceFeatures == null)
@@ -352,6 +379,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @return
    */
+  @Override
   public SequenceFeature[] getSequenceFeatures()
   {
     SequenceFeature[] features = sequenceFeatures;
@@ -367,6 +395,7 @@ public class Sequence extends ASequence implements SequenceI
     return features;
   }
 
+  @Override
   public void addPDBId(PDBEntry entry)
   {
     if (pdbIds == null)
@@ -411,7 +440,7 @@ public class Sequence extends ASequence implements SequenceI
   @Override
   public Vector<PDBEntry> getAllPDBEntries()
   {
-    return pdbIds;
+    return pdbIds == null ? new Vector<PDBEntry>() : pdbIds;
   }
 
   /**
@@ -419,6 +448,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @return DOCUMENT ME!
    */
+  @Override
   public String getDisplayId(boolean jvsuffix)
   {
     StringBuffer result = new StringBuffer(name);
@@ -436,6 +466,7 @@ public class Sequence extends ASequence implements SequenceI
    * @param name
    *          DOCUMENT ME!
    */
+  @Override
   public void setName(String name)
   {
     this.name = name;
@@ -447,6 +478,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @return DOCUMENT ME!
    */
+  @Override
   public String getName()
   {
     return this.name;
@@ -458,6 +490,7 @@ public class Sequence extends ASequence implements SequenceI
    * @param start
    *          DOCUMENT ME!
    */
+  @Override
   public void setStart(int start)
   {
     this.start = start;
@@ -468,6 +501,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @return DOCUMENT ME!
    */
+  @Override
   public int getStart()
   {
     return this.start;
@@ -479,6 +513,7 @@ public class Sequence extends ASequence implements SequenceI
    * @param end
    *          DOCUMENT ME!
    */
+  @Override
   public void setEnd(int end)
   {
     this.end = end;
@@ -489,6 +524,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @return DOCUMENT ME!
    */
+  @Override
   public int getEnd()
   {
     return this.end;
@@ -499,6 +535,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @return DOCUMENT ME!
    */
+  @Override
   public int getLength()
   {
     return this.sequence.length;
@@ -510,22 +547,26 @@ public class Sequence extends ASequence implements SequenceI
    * @param seq
    *          DOCUMENT ME!
    */
+  @Override
   public void setSequence(String seq)
   {
     this.sequence = seq.toCharArray();
     checkValidRange();
   }
 
+  @Override
   public String getSequenceAsString()
   {
     return new String(sequence);
   }
 
+  @Override
   public String getSequenceAsString(int start, int end)
   {
     return new String(getSequence(start, end));
   }
 
+  @Override
   public char[] getSequence()
   {
     return sequence;
@@ -536,6 +577,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @see jalview.datamodel.SequenceI#getSequence(int, int)
    */
+  @Override
   public char[] getSequence(int start, int end)
   {
     if (start < 0)
@@ -589,16 +631,15 @@ public class Sequence extends ASequence implements SequenceI
   }
 
   /**
-   * DOCUMENT ME!
+   * Returns the character of the aligned sequence at the given position (base
+   * zero), or space if the position is not within the sequence's bounds
    * 
-   * @param i
-   *          DOCUMENT ME!
-   * 
-   * @return DOCUMENT ME!
+   * @return
    */
+  @Override
   public char getCharAt(int i)
   {
-    if (i < sequence.length)
+    if (i >= 0 && i < sequence.length)
     {
       return sequence[i];
     }
@@ -614,6 +655,7 @@ public class Sequence extends ASequence implements SequenceI
    * @param desc
    *          DOCUMENT ME!
    */
+  @Override
   public void setDescription(String desc)
   {
     this.description = desc;
@@ -624,6 +666,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @return DOCUMENT ME!
    */
+  @Override
   public String getDescription()
   {
     return this.description;
@@ -634,6 +677,7 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @see jalview.datamodel.SequenceI#findIndex(int)
    */
+  @Override
   public int findIndex(int pos)
   {
     // returns the alignment position for a residue
@@ -686,6 +730,7 @@ public class Sequence extends ASequence implements SequenceI
    * @return int[SequenceI.getEnd()-SequenceI.getStart()+1] or null if no
    *         residues in SequenceI object
    */
+  @Override
   public int[] gapMap()
   {
     String seq = jalview.analysis.AlignSeq.extractGaps(
@@ -885,18 +930,18 @@ public class Sequence extends ASequence implements SequenceI
   }
 
   @Override
-  public void setDBRef(DBRefEntry[] dbref)
+  public void setDBRefs(DBRefEntry[] dbref)
   {
     dbrefs = dbref;
   }
 
   @Override
-  public DBRefEntry[] getDBRef()
+  public DBRefEntry[] getDBRefs()
   {
     if (dbrefs == null && datasetSequence != null
             && this != datasetSequence)
     {
-      return datasetSequence.getDBRef();
+      return datasetSequence.getDBRefs();
     }
     return dbrefs;
   }
@@ -904,6 +949,7 @@ public class Sequence extends ASequence implements SequenceI
   @Override
   public void addDBRef(DBRefEntry entry)
   {
+    // TODO add to dataset sequence instead if there is one?
     if (dbrefs == null)
     {
       dbrefs = new DBRefEntry[0];
@@ -937,6 +983,7 @@ public class Sequence extends ASequence implements SequenceI
   @Override
   public void setDatasetSequence(SequenceI seq)
   {
+    // TODO check for circular reference before setting?
     datasetSequence = seq;
   }
 
@@ -973,6 +1020,7 @@ public class Sequence extends ASequence implements SequenceI
     annotation.setSequenceRef(this);
   }
 
+  @Override
   public void removeAlignmentAnnotation(AlignmentAnnotation annotation)
   {
     if (this.annotation != null)
@@ -1040,24 +1088,32 @@ public class Sequence extends ASequence implements SequenceI
    * 
    * @see jalview.datamodel.SequenceI#createDatasetSequence()
    */
+  @Override
   public SequenceI createDatasetSequence()
   {
     if (datasetSequence == null)
     {
-      datasetSequence = new Sequence(getName(), AlignSeq.extractGaps(
+      Sequence dsseq = new Sequence(getName(), AlignSeq.extractGaps(
               jalview.util.Comparison.GapChars, getSequenceAsString()),
               getStart(), getEnd());
-      datasetSequence.setSequenceFeatures(getSequenceFeatures());
-      datasetSequence.setDescription(getDescription());
-      setSequenceFeatures(null);
-      // move database references onto dataset sequence
-      datasetSequence.setDBRef(getDBRef());
-      setDBRef(null);
-      datasetSequence.setPDBId(getAllPDBEntries());
-      setPDBId(null);
+
+      datasetSequence = dsseq;
+
+      dsseq.setDescription(description);
+      // move features and database references onto dataset sequence
+      dsseq.sequenceFeatures = sequenceFeatures;
+      sequenceFeatures=null;
+      dsseq.dbrefs = dbrefs;
+      dbrefs=null;
+      // TODO: search and replace any references to this sequence with
+      // references to the dataset sequence in Mappings on dbref
+      dsseq.pdbIds = pdbIds;
+      pdbIds = null;
       datasetSequence.updatePDBIds();
       if (annotation != null)
       {
+        // annotation is cloned rather than moved, to preserve what's currently
+        // on the alignment
         for (AlignmentAnnotation aa : annotation)
         {
           AlignmentAnnotation _aa = new AlignmentAnnotation(aa);
@@ -1078,6 +1134,7 @@ public class Sequence extends ASequence implements SequenceI
    * jalview.datamodel.SequenceI#setAlignmentAnnotation(AlignmmentAnnotation[]
    * annotations)
    */
+  @Override
   public void setAlignmentAnnotation(AlignmentAnnotation[] annotations)
   {
     if (annotation != null)
@@ -1226,7 +1283,7 @@ public class Sequence extends ASequence implements SequenceI
       }
     }
     // transfer database references
-    DBRefEntry[] entryRefs = entry.getDBRef();
+    DBRefEntry[] entryRefs = entry.getDBRefs();
     if (entryRefs != null)
     {
       for (int r = 0; r < entryRefs.length; r++)
@@ -1250,6 +1307,7 @@ public class Sequence extends ASequence implements SequenceI
    * @return The index (zero-based) on this sequence in the MSA. It returns
    *         {@code -1} if this information is not available.
    */
+  @Override
   public int getIndex()
   {
     return index;
@@ -1263,16 +1321,19 @@ public class Sequence extends ASequence implements SequenceI
    *          position for this sequence. This value is zero-based (zero for
    *          this first sequence)
    */
+  @Override
   public void setIndex(int value)
   {
     index = value;
   }
 
+  @Override
   public void setRNA(RNA r)
   {
     rna = r;
   }
 
+  @Override
   public RNA getRNA()
   {
     return rna;
@@ -1297,6 +1358,7 @@ public class Sequence extends ASequence implements SequenceI
     return result;
   }
 
+  @Override
   public String toString()
   {
     return getDisplayId(false);
@@ -1321,4 +1383,16 @@ public class Sequence extends ASequence implements SequenceI
     return null;
   }
 
+  @Override
+  public void setSourceDBRef(DBRefEntryI dbRef)
+  {
+    this.sourceDBRef = dbRef;
+  }
+
+  @Override
+  public DBRefEntryI getSourceDBRef()
+  {
+    return this.sourceDBRef;
+  }
+
 }