src/jalview/structure/StructureSelectionManager.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.structure;
  22
  23 import jalview.analysis.AlignSeq;
  24 import jalview.api.StructureSelectionManagerProvider;
  25 import jalview.commands.CommandI;
  26 import jalview.commands.EditCommand;
  27 import jalview.commands.OrderCommand;
  28 import jalview.datamodel.AlignedCodonFrame;
  29 import jalview.datamodel.AlignmentAnnotation;
  30 import jalview.datamodel.AlignmentI;
  31 import jalview.datamodel.Annotation;
  32 import jalview.datamodel.PDBEntry;
  33 import jalview.datamodel.SearchResults;
  34 import jalview.datamodel.SequenceI;
  35 import jalview.gui.IProgressIndicator;
  36 import jalview.io.AppletFormatAdapter;
  37 import jalview.util.MappingUtils;
  38 import jalview.util.MessageManager;
  39 import jalview.ws.sifts.SiftsClient;
  40 import jalview.ws.sifts.SiftsException;
  41 import jalview.ws.sifts.SiftsSettings;
  42
  43 import java.io.PrintStream;
  44 import java.util.ArrayList;
  45 import java.util.Arrays;
  46 import java.util.Collections;
  47 import java.util.Enumeration;
  48 import java.util.HashMap;
  49 import java.util.IdentityHashMap;
  50 import java.util.LinkedHashSet;
  51 import java.util.List;
  52 import java.util.Map;
  53 import java.util.Set;
  54 import java.util.Vector;
  55
  56 import MCview.Atom;
  57 import MCview.PDBChain;
  58 import MCview.PDBfile;
  59
  60 public class StructureSelectionManager
  61 {
  62   public final static String NEWLINE = System.lineSeparator();
  63
  64   static IdentityHashMap<StructureSelectionManagerProvider, StructureSelectionManager> instances;
  65
  66   private List<StructureMapping> mappings = new ArrayList<StructureMapping>();
  67
  68   private boolean processSecondaryStructure = false;
  69
  70   private boolean secStructServices = false;
  71
  72   private boolean addTempFacAnnot = false;
  73
  74   private IProgressIndicator progressIndicator;
  75
  76   private SiftsClient siftsClient = null;
  77
  78   private long progressSessionId;
  79
  80   /*
  81    * Set of any registered mappings between (dataset) sequences.
  82    */
  83   public Set<AlignedCodonFrame> seqmappings = new LinkedHashSet<AlignedCodonFrame>();
  84
  85   private List<CommandListener> commandListeners = new ArrayList<CommandListener>();
  86
  87   private List<SelectionListener> sel_listeners = new ArrayList<SelectionListener>();
  88
  89   /**
  90    * @return true if will try to use external services for processing secondary
  91    *         structure
  92    */
  93   public boolean isSecStructServices()
  94   {
  95     return secStructServices;
  96   }
  97
  98   /**
  99    * control use of external services for processing secondary structure
 100    *
 101    * @param secStructServices
 102    */
 103   public void setSecStructServices(boolean secStructServices)
 104   {
 105     this.secStructServices = secStructServices;
 106   }
 107
 108   /**
 109    * flag controlling addition of any kind of structural annotation
 110    *
 111    * @return true if temperature factor annotation will be added
 112    */
 113   public boolean isAddTempFacAnnot()
 114   {
 115     return addTempFacAnnot;
 116   }
 117
 118   /**
 119    * set flag controlling addition of structural annotation
 120    *
 121    * @param addTempFacAnnot
 122    */
 123   public void setAddTempFacAnnot(boolean addTempFacAnnot)
 124   {
 125     this.addTempFacAnnot = addTempFacAnnot;
 126   }
 127
 128   /**
 129    *
 130    * @return if true, the structure manager will attempt to add secondary
 131    *         structure lines for unannotated sequences
 132    */
 133
 134   public boolean isProcessSecondaryStructure()
 135   {
 136     return processSecondaryStructure;
 137   }
 138
 139   /**
 140    * Control whether structure manager will try to annotate mapped sequences
 141    * with secondary structure from PDB data.
 142    *
 143    * @param enable
 144    */
 145   public void setProcessSecondaryStructure(boolean enable)
 146   {
 147     processSecondaryStructure = enable;
 148   }
 149
 150   /**
 151    * debug function - write all mappings to stdout
 152    */
 153   public void reportMapping()
 154   {
 155     if (mappings.isEmpty())
 156     {
 157       System.err.println("reportMapping: No PDB/Sequence mappings.");
 158     }
 159     else
 160     {
 161       System.err.println("reportMapping: There are " + mappings.size()
 162               + " mappings.");
 163       int i = 0;
 164       for (StructureMapping sm : mappings)
 165       {
 166         System.err.println("mapping " + i++ + " : " + sm.pdbfile);
 167       }
 168     }
 169   }
 170
 171   /**
 172    * map between the PDB IDs (or structure identifiers) used by Jalview and the
 173    * absolute filenames for PDB data that corresponds to it
 174    */
 175   Map<String, String> pdbIdFileName = new HashMap<String, String>();
 176
 177   Map<String, String> pdbFileNameId = new HashMap<String, String>();
 178
 179   public void registerPDBFile(String idForFile, String absoluteFile)
 180   {
 181     pdbIdFileName.put(idForFile, absoluteFile);
 182     pdbFileNameId.put(absoluteFile, idForFile);
 183   }
 184
 185   public String findIdForPDBFile(String idOrFile)
 186   {
 187     String id = pdbFileNameId.get(idOrFile);
 188     return id;
 189   }
 190
 191   public String findFileForPDBId(String idOrFile)
 192   {
 193     String id = pdbIdFileName.get(idOrFile);
 194     return id;
 195   }
 196
 197   public boolean isPDBFileRegistered(String idOrFile)
 198   {
 199     return pdbFileNameId.containsKey(idOrFile)
 200             || pdbIdFileName.containsKey(idOrFile);
 201   }
 202
 203   private static StructureSelectionManager nullProvider = null;
 204
 205   public static StructureSelectionManager getStructureSelectionManager(
 206           StructureSelectionManagerProvider context)
 207   {
 208     if (context == null)
 209     {
 210       if (nullProvider == null)
 211       {
 212         if (instances != null)
 213         {
 214           throw new Error(
 215                   MessageManager
 216                           .getString("error.implementation_error_structure_selection_manager_null"),
 217                   new NullPointerException(MessageManager
 218                           .getString("exception.ssm_context_is_null")));
 219         }
 220         else
 221         {
 222           nullProvider = new StructureSelectionManager();
 223         }
 224         return nullProvider;
 225       }
 226     }
 227     if (instances == null)
 228     {
 229       instances = new java.util.IdentityHashMap<StructureSelectionManagerProvider, StructureSelectionManager>();
 230     }
 231     StructureSelectionManager instance = instances.get(context);
 232     if (instance == null)
 233     {
 234       if (nullProvider != null)
 235       {
 236         instance = nullProvider;
 237       }
 238       else
 239       {
 240         instance = new StructureSelectionManager();
 241       }
 242       instances.put(context, instance);
 243     }
 244     return instance;
 245   }
 246
 247   /**
 248    * flag controlling whether SeqMappings are relayed from received sequence
 249    * mouse over events to other sequences
 250    */
 251   boolean relaySeqMappings = true;
 252
 253   /**
 254    * Enable or disable relay of seqMapping events to other sequences. You might
 255    * want to do this if there are many sequence mappings and the host computer
 256    * is slow
 257    *
 258    * @param relay
 259    */
 260   public void setRelaySeqMappings(boolean relay)
 261   {
 262     relaySeqMappings = relay;
 263   }
 264
 265   /**
 266    * get the state of the relay seqMappings flag.
 267    *
 268    * @return true if sequence mouse overs are being relayed to other mapped
 269    *         sequences
 270    */
 271   public boolean isRelaySeqMappingsEnabled()
 272   {
 273     return relaySeqMappings;
 274   }
 275
 276   Vector listeners = new Vector();
 277
 278   /**
 279    * register a listener for alignment sequence mouseover events
 280    *
 281    * @param svl
 282    */
 283   public void addStructureViewerListener(Object svl)
 284   {
 285     if (!listeners.contains(svl))
 286     {
 287       listeners.addElement(svl);
 288     }
 289   }
 290
 291   /**
 292    * Returns the file name for a mapped PDB id (or null if not mapped).
 293    *
 294    * @param pdbid
 295    * @return
 296    */
 297   public String alreadyMappedToFile(String pdbid)
 298   {
 299     for (StructureMapping sm : mappings)
 300     {
 301       if (sm.getPdbId().equals(pdbid))
 302       {
 303         return sm.pdbfile;
 304       }
 305     }
 306     return null;
 307   }
 308
 309   /**
 310    * Import structure data and register a structure mapping for broadcasting
 311    * colouring, mouseovers and selection events (convenience wrapper).
 312    *
 313    * @param sequence
 314    *          - one or more sequences to be mapped to pdbFile
 315    * @param targetChains
 316    *          - optional chain specification for mapping each sequence to pdb
 317    *          (may be nill, individual elements may be nill)
 318    * @param pdbFile
 319    *          - structure data resource
 320    * @param protocol
 321    *          - how to resolve data from resource
 322    * @return null or the structure data parsed as a pdb file
 323    */
 324   synchronized public PDBfile setMapping(SequenceI[] sequence,
 325           String[] targetChains, String pdbFile, String protocol)
 326   {
 327     return setMapping(true, sequence, targetChains, pdbFile, protocol);
 328   }
 329
 330   /**
 331    * create sequence structure mappings between each sequence and the given
 332    * pdbFile (retrieved via the given protocol).
 333    *
 334    * @param forStructureView
 335    *          when true, record the mapping for use in mouseOvers
 336    *
 337    * @param sequenceArray
 338    *          - one or more sequences to be mapped to pdbFile
 339    * @param targetChainIds
 340    *          - optional chain specification for mapping each sequence to pdb
 341    *          (may be nill, individual elements may be nill)
 342    * @param pdbFile
 343    *          - structure data resource
 344    * @param protocol
 345    *          - how to resolve data from resource
 346    * @return null or the structure data parsed as a pdb file
 347    */
 348   synchronized public PDBfile setMapping(boolean forStructureView,
 349           SequenceI[] sequenceArray, String[] targetChainIds,
 350           String pdbFile,
 351           String protocol)
 352   {
 353     /*
 354      * There will be better ways of doing this in the future, for now we'll use
 355      * the tried and tested MCview pdb mapping
 356      */
 357     boolean parseSecStr = processSecondaryStructure;
 358     if (isPDBFileRegistered(pdbFile))
 359     {
 360       for (SequenceI sq : sequenceArray)
 361       {
 362         SequenceI ds = sq;
 363         while (ds.getDatasetSequence() != null)
 364         {
 365           ds = ds.getDatasetSequence();
 366         }
 367         ;
 368         if (ds.getAnnotation() != null)
 369         {
 370           for (AlignmentAnnotation ala : ds.getAnnotation())
 371           {
 372             // false if any annotation present from this structure
 373             // JBPNote this fails for jmol/chimera view because the *file* is
 374             // passed, not the structure data ID -
 375             if (PDBfile.isCalcIdForFile(ala, findIdForPDBFile(pdbFile)))
 376             {
 377               parseSecStr = false;
 378             }
 379           }
 380         }
 381       }
 382     }
 383     PDBfile pdb = null;
 384     boolean isMapUsingSIFTs = SiftsSettings.isMapWithSifts();
 385     try
 386     {
 387       pdb = new PDBfile(addTempFacAnnot, parseSecStr, secStructServices,
 388               pdbFile, protocol);
 389
 390       if (pdb.getId() != null && pdb.getId().trim().length() > 0
 391               && AppletFormatAdapter.FILE.equals(protocol))
 392       {
 393         registerPDBFile(pdb.getId().trim(), pdbFile);
 394       }
 395     } catch (Exception ex)
 396     {
 397       ex.printStackTrace();
 398       return null;
 399     }
 400
 401     try
 402     {
 403       if (isMapUsingSIFTs)
 404       {
 405         siftsClient = new SiftsClient(pdb);
 406       }
 407     } catch (SiftsException e)
 408     {
 409       isMapUsingSIFTs = false;
 410       e.printStackTrace();
 411     }
 412
 413     String targetChainId;
 414     for (int s = 0; s < sequenceArray.length; s++)
 415     {
 416       boolean infChain = true;
 417       final SequenceI seq = sequenceArray[s];
 418       if (targetChainIds != null && targetChainIds[s] != null)
 419       {
 420         infChain = false;
 421         targetChainId = targetChainIds[s];
 422       }
 423       else if (seq.getName().indexOf("|") > -1)
 424       {
 425         targetChainId = seq.getName().substring(
 426                 seq.getName().lastIndexOf("|") + 1);
 427         if (targetChainId.length() > 1)
 428         {
 429           if (targetChainId.trim().length() == 0)
 430           {
 431             targetChainId = " ";
 432           }
 433           else
 434           {
 435             // not a valid chain identifier
 436             targetChainId = "";
 437           }
 438         }
 439       }
 440       else
 441       {
 442         targetChainId = "";
 443       }
 444
 445       /*
 446        * Attempt pairwise alignment of the sequence with each chain in the PDB,
 447        * and remember the highest scoring chain
 448        */
 449       int max = -10;
 450       AlignSeq maxAlignseq = null;
 451       String maxChainId = " ";
 452       PDBChain maxChain = null;
 453       boolean first = true;
 454       for (PDBChain chain : pdb.getChains())
 455       {
 456         if (targetChainId.length() > 0 && !targetChainId.equals(chain.id)
 457                 && !infChain)
 458         {
 459           continue; // don't try to map chains don't match.
 460         }
 461         // TODO: correctly determine sequence type for mixed na/peptide
 462         // structures
 463         final String type = chain.isNa ? AlignSeq.DNA : AlignSeq.PEP;
 464         AlignSeq as = AlignSeq.doGlobalNWAlignment(seq, chain.sequence,
 465                 type);
 466         // equivalent to:
 467         // AlignSeq as = new AlignSeq(sequence[s], chain.sequence, type);
 468         // as.calcScoreMatrix();
 469         // as.traceAlignment();
 470
 471         if (first || as.maxscore > max
 472                 || (as.maxscore == max && chain.id.equals(targetChainId)))
 473         {
 474           first = false;
 475           maxChain = chain;
 476           max = as.maxscore;
 477           maxAlignseq = as;
 478           maxChainId = chain.id;
 479         }
 480       }
 481       if (maxChain == null)
 482       {
 483         continue;
 484       }
 485
 486       if (protocol.equals(jalview.io.AppletFormatAdapter.PASTE))
 487       {
 488         pdbFile = "INLINE" + pdb.getId();
 489       }
 490
 491       ArrayList<StructureMapping> seqToStrucMapping = new ArrayList<StructureMapping>();
 492       if (isMapUsingSIFTs)
 493       {
 494         setProgressBar(null);
 495         setProgressBar("Obtaining mapping with SIFTS");
 496         jalview.datamodel.Mapping sqmpping = maxAlignseq
 497                 .getMappingFromS1(false);
 498         if (targetChainId != null && !targetChainId.trim().isEmpty())
 499         {
 500           StructureMapping mapping = getStructureMapping(seq, pdbFile,
 501                   targetChainId, pdb, maxChain, sqmpping, maxAlignseq);
 502           seqToStrucMapping.add(mapping);
 503         }
 504         else
 505         {
 506           for (PDBChain chain : pdb.getChains())
 507           {
 508             StructureMapping mapping = getStructureMapping(seq, pdbFile,
 509                     chain.id, pdb, chain, sqmpping, maxAlignseq);
 510             seqToStrucMapping.add(mapping);
 511           }
 512         }
 513       }
 514       else
 515       {
 516         setProgressBar(null);
 517         setProgressBar("Obtaining mapping with NW alignment");
 518         seqToStrucMapping.add(getNWMappings(seq, pdbFile, maxChainId,
 519                 maxChain, pdb, maxAlignseq));
 520       }
 521
 522       if (forStructureView)
 523       {
 524         mappings.addAll(seqToStrucMapping);
 525       }
 526     }
 527     return pdb;
 528   }
 529
 530   private StructureMapping getStructureMapping(SequenceI seq,
 531           String pdbFile, String targetChainId, PDBfile pdb,
 532           PDBChain maxChain, jalview.datamodel.Mapping sqmpping,
 533           AlignSeq maxAlignseq)
 534   {
 535     String maxChainId = targetChainId;
 536     try
 537     {
 538       StructureMapping curChainMapping = siftsClient
 539               .getSiftsStructureMapping(seq, pdbFile, targetChainId);
 540       try
 541       {
 542       PDBChain chain = pdb.findChain(targetChainId);
 543       if (chain != null)
 544       {
 545         chain.transferResidueAnnotation(curChainMapping, sqmpping);
 546       }
 547       } catch (Exception e)
 548       {
 549         e.printStackTrace();
 550       }
 551       return curChainMapping;
 552     } catch (SiftsException e)
 553     {
 554       System.err.println(e.getMessage());
 555       System.err.println(">>> Now switching mapping with NW alignment...");
 556       setProgressBar(null);
 557       setProgressBar(">>> Now switching mapping with NW alignment...");
 558       return getNWMappings(seq, pdbFile, maxChainId, maxChain, pdb,
 559               maxAlignseq);
 560     }
 561   }
 562
 563   private StructureMapping getNWMappings(SequenceI seq,
 564           String pdbFile,
 565           String maxChainId, PDBChain maxChain, PDBfile pdb,
 566           AlignSeq maxAlignseq)
 567   {
 568     final StringBuilder mappingDetails = new StringBuilder(128);
 569     mappingDetails.append(NEWLINE).append(
 570             "Sequence \u27f7 Structure mapping details");
 571     mappingDetails.append(NEWLINE);
 572     mappingDetails
 573             .append("Method: inferred with Needleman & Wunsch alignment");
 574     mappingDetails.append(NEWLINE).append("PDB Sequence is :")
 575             .append(NEWLINE).append("Sequence = ")
 576             .append(maxChain.sequence.getSequenceAsString());
 577     mappingDetails.append(NEWLINE).append("No of residues = ")
 578             .append(maxChain.residues.size()).append(NEWLINE)
 579             .append(NEWLINE);
 580     PrintStream ps = new PrintStream(System.out)
 581     {
 582       @Override
 583       public void print(String x)
 584       {
 585         mappingDetails.append(x);
 586       }
 587
 588       @Override
 589       public void println()
 590       {
 591         mappingDetails.append(NEWLINE);
 592       }
 593     };
 594
 595     maxAlignseq.printAlignment(ps);
 596
 597     mappingDetails.append(NEWLINE).append("PDB start/end ");
 598     mappingDetails.append(String.valueOf(maxAlignseq.seq2start))
 599             .append(" ");
 600     mappingDetails.append(String.valueOf(maxAlignseq.seq2end));
 601     mappingDetails.append(NEWLINE).append("SEQ start/end ");
 602     mappingDetails.append(
 603             String.valueOf(maxAlignseq.seq1start + (seq.getStart() - 1)))
 604             .append(" ");
 605     mappingDetails.append(String.valueOf(maxAlignseq.seq1end
 606             + (seq.getStart() - 1)));
 607     mappingDetails.append(NEWLINE);
 608     maxChain.makeExactMapping(maxAlignseq, seq);
 609     jalview.datamodel.Mapping sqmpping = maxAlignseq
 610             .getMappingFromS1(false);
 611     maxChain.transferRESNUMFeatures(seq, null);
 612
 613     HashMap<Integer, int[]> mapping = new HashMap<Integer, int[]>();
 614     int resNum = -10000;
 615     int index = 0;
 616     char insCode = ' ';
 617
 618     do
 619     {
 620       Atom tmp = maxChain.atoms.elementAt(index);
 621       if ((resNum != tmp.resNumber || insCode != tmp.insCode)
 622               && tmp.alignmentMapping != -1)
 623       {
 624         resNum = tmp.resNumber;
 625         insCode = tmp.insCode;
 626         if (tmp.alignmentMapping >= -1)
 627         {
 628           mapping.put(tmp.alignmentMapping + 1, new int[] { tmp.resNumber,
 629               tmp.atomIndex });
 630         }
 631       }
 632
 633       index++;
 634     } while (index < maxChain.atoms.size());
 635
 636     StructureMapping nwMapping = new StructureMapping(seq, pdbFile,
 637             pdb.getId(), maxChainId, mapping, mappingDetails.toString());
 638     maxChain.transferResidueAnnotation(nwMapping, sqmpping);
 639     return nwMapping;
 640   }
 641
 642   public void removeStructureViewerListener(Object svl, String[] pdbfiles)
 643   {
 644     listeners.removeElement(svl);
 645     if (svl instanceof SequenceListener)
 646     {
 647       for (int i = 0; i < listeners.size(); i++)
 648       {
 649         if (listeners.elementAt(i) instanceof StructureListener)
 650         {
 651           ((StructureListener) listeners.elementAt(i))
 652                   .releaseReferences(svl);
 653         }
 654       }
 655     }
 656
 657     if (pdbfiles == null)
 658     {
 659       return;
 660     }
 661
 662     /*
 663      * Remove mappings to the closed listener's PDB files, but first check if
 664      * another listener is still interested
 665      */
 666     List<String> pdbs = new ArrayList<String>(Arrays.asList(pdbfiles));
 667
 668     StructureListener sl;
 669     for (int i = 0; i < listeners.size(); i++)
 670     {
 671       if (listeners.elementAt(i) instanceof StructureListener)
 672       {
 673         sl = (StructureListener) listeners.elementAt(i);
 674         for (String pdbfile : sl.getPdbFile())
 675         {
 676           pdbs.remove(pdbfile);
 677         }
 678       }
 679     }
 680
 681     /*
 682      * Rebuild the mappings set, retaining only those which are for 'other' PDB
 683      * files
 684      */
 685     if (pdbs.size() > 0)
 686     {
 687       List<StructureMapping> tmp = new ArrayList<StructureMapping>();
 688       for (StructureMapping sm : mappings)
 689       {
 690         if (!pdbs.contains(sm.pdbfile))
 691         {
 692           tmp.add(sm);
 693         }
 694       }
 695
 696       mappings = tmp;
 697     }
 698   }
 699
 700   /**
 701    * Propagate mouseover of a single position in a structure
 702    *
 703    * @param pdbResNum
 704    * @param chain
 705    * @param pdbfile
 706    */
 707   public void mouseOverStructure(int pdbResNum, String chain, String pdbfile)
 708   {
 709     AtomSpec atomSpec = new AtomSpec(pdbfile, chain, pdbResNum, 0);
 710     List<AtomSpec> atoms = Collections.singletonList(atomSpec);
 711     mouseOverStructure(atoms);
 712   }
 713
 714   /**
 715    * Propagate mouseover or selection of multiple positions in a structure
 716    *
 717    * @param atoms
 718    */
 719   public void mouseOverStructure(List<AtomSpec> atoms)
 720   {
 721     if (listeners == null)
 722     {
 723       // old or prematurely sent event
 724       return;
 725     }
 726     boolean hasSequenceListener = false;
 727     for (int i = 0; i < listeners.size(); i++)
 728     {
 729       if (listeners.elementAt(i) instanceof SequenceListener)
 730       {
 731         hasSequenceListener = true;
 732       }
 733     }
 734     if (!hasSequenceListener)
 735     {
 736       return;
 737     }
 738
 739     SearchResults results = new SearchResults();
 740     for (AtomSpec atom : atoms)
 741     {
 742       SequenceI lastseq = null;
 743       int lastipos = -1;
 744       for (StructureMapping sm : mappings)
 745       {
 746         if (sm.pdbfile.equals(atom.getPdbFile())
 747                 && sm.pdbchain.equals(atom.getChain()))
 748         {
 749           int indexpos = sm.getSeqPos(atom.getPdbResNum());
 750           if (lastipos != indexpos && lastseq != sm.sequence)
 751           {
 752             results.addResult(sm.sequence, indexpos, indexpos);
 753             lastipos = indexpos;
 754             lastseq = sm.sequence;
 755             // construct highlighted sequence list
 756             for (AlignedCodonFrame acf : seqmappings)
 757             {
 758               acf.markMappedRegion(sm.sequence, indexpos, results);
 759             }
 760           }
 761         }
 762       }
 763     }
 764     for (Object li : listeners)
 765     {
 766       if (li instanceof SequenceListener)
 767       {
 768         ((SequenceListener) li).highlightSequence(results);
 769       }
 770     }
 771   }
 772
 773   /**
 774    * highlight regions associated with a position (indexpos) in seq
 775    *
 776    * @param seq
 777    *          the sequence that the mouse over occurred on
 778    * @param indexpos
 779    *          the absolute position being mouseovered in seq (0 to seq.length())
 780    * @param index
 781    *          the sequence position (if -1, seq.findPosition is called to
 782    *          resolve the residue number)
 783    */
 784   public void mouseOverSequence(SequenceI seq, int indexpos, int index,
 785           VamsasSource source)
 786   {
 787     boolean hasSequenceListeners = handlingVamsasMo
 788             || !seqmappings.isEmpty();
 789     SearchResults results = null;
 790     if (index == -1)
 791     {
 792       index = seq.findPosition(indexpos);
 793     }
 794     for (int i = 0; i < listeners.size(); i++)
 795     {
 796       Object listener = listeners.elementAt(i);
 797       if (listener == source)
 798       {
 799         // TODO listener (e.g. SeqPanel) is never == source (AlignViewport)
 800         // Temporary fudge with SequenceListener.getVamsasSource()
 801         continue;
 802       }
 803       if (listener instanceof StructureListener)
 804       {
 805         highlightStructure((StructureListener) listener, seq, index);
 806       }
 807       else
 808       {
 809         if (listener instanceof SequenceListener)
 810         {
 811           final SequenceListener seqListener = (SequenceListener) listener;
 812           if (hasSequenceListeners
 813                   && seqListener.getVamsasSource() != source)
 814           {
 815             if (relaySeqMappings)
 816             {
 817               if (results == null)
 818               {
 819                 results = MappingUtils.buildSearchResults(seq, index,
 820                         seqmappings);
 821               }
 822               if (handlingVamsasMo)
 823               {
 824                 results.addResult(seq, index, index);
 825
 826               }
 827               if (!results.isEmpty())
 828               {
 829                 seqListener.highlightSequence(results);
 830               }
 831             }
 832           }
 833         }
 834         else if (listener instanceof VamsasListener && !handlingVamsasMo)
 835         {
 836           ((VamsasListener) listener).mouseOverSequence(seq, indexpos,
 837                   source);
 838         }
 839         else if (listener instanceof SecondaryStructureListener)
 840         {
 841           ((SecondaryStructureListener) listener).mouseOverSequence(seq,
 842                   indexpos, index);
 843         }
 844       }
 845     }
 846   }
 847
 848   /**
 849    * Send suitable messages to a StructureListener to highlight atoms
 850    * corresponding to the given sequence position.
 851    *
 852    * @param sl
 853    * @param seq
 854    * @param index
 855    */
 856   protected void highlightStructure(StructureListener sl, SequenceI seq,
 857           int index)
 858   {
 859     if (!sl.isListeningFor(seq))
 860     {
 861       return;
 862     }
 863     int atomNo;
 864     List<AtomSpec> atoms = new ArrayList<AtomSpec>();
 865     for (StructureMapping sm : mappings)
 866     {
 867       if (sm.sequence == seq || sm.sequence == seq.getDatasetSequence())
 868       {
 869         atomNo = sm.getAtomNum(index);
 870
 871         if (atomNo > 0)
 872         {
 873           atoms.add(new AtomSpec(sm.pdbfile, sm.pdbchain, sm
 874                   .getPDBResNum(index), atomNo));
 875         }
 876       }
 877     }
 878     sl.highlightAtoms(atoms);
 879   }
 880
 881   /**
 882    * true if a mouse over event from an external (ie Vamsas) source is being
 883    * handled
 884    */
 885   boolean handlingVamsasMo = false;
 886
 887   long lastmsg = 0;
 888
 889   /**
 890    * as mouseOverSequence but only route event to SequenceListeners
 891    *
 892    * @param sequenceI
 893    * @param position
 894    *          in an alignment sequence
 895    */
 896   public void mouseOverVamsasSequence(SequenceI sequenceI, int position,
 897           VamsasSource source)
 898   {
 899     handlingVamsasMo = true;
 900     long msg = sequenceI.hashCode() * (1 + position);
 901     if (lastmsg != msg)
 902     {
 903       lastmsg = msg;
 904       mouseOverSequence(sequenceI, position, -1, source);
 905     }
 906     handlingVamsasMo = false;
 907   }
 908
 909   public Annotation[] colourSequenceFromStructure(SequenceI seq,
 910           String pdbid)
 911   {
 912     return null;
 913     // THIS WILL NOT BE AVAILABLE IN JALVIEW 2.3,
 914     // UNTIL THE COLOUR BY ANNOTATION IS REWORKED
 915     /*
 916      * Annotation [] annotations = new Annotation[seq.getLength()];
 917      *
 918      * StructureListener sl; int atomNo = 0; for (int i = 0; i <
 919      * listeners.size(); i++) { if (listeners.elementAt(i) instanceof
 920      * StructureListener) { sl = (StructureListener) listeners.elementAt(i);
 921      *
 922      * for (int j = 0; j < mappings.length; j++) {
 923      *
 924      * if (mappings[j].sequence == seq && mappings[j].getPdbId().equals(pdbid)
 925      * && mappings[j].pdbfile.equals(sl.getPdbFile())) {
 926      * System.out.println(pdbid+" "+mappings[j].getPdbId() +"
 927      * "+mappings[j].pdbfile);
 928      *
 929      * java.awt.Color col; for(int index=0; index<seq.getLength(); index++) {
 930      * if(jalview.util.Comparison.isGap(seq.getCharAt(index))) continue;
 931      *
 932      * atomNo = mappings[j].getAtomNum(seq.findPosition(index)); col =
 933      * java.awt.Color.white; if (atomNo > 0) { col = sl.getColour(atomNo,
 934      * mappings[j].getPDBResNum(index), mappings[j].pdbchain,
 935      * mappings[j].pdbfile); }
 936      *
 937      * annotations[index] = new Annotation("X",null,' ',0,col); } return
 938      * annotations; } } } }
 939      *
 940      * return annotations;
 941      */
 942   }
 943
 944   public void structureSelectionChanged()
 945   {
 946   }
 947
 948   public void sequenceSelectionChanged()
 949   {
 950   }
 951
 952   public void sequenceColoursChanged(Object source)
 953   {
 954     StructureListener sl;
 955     for (int i = 0; i < listeners.size(); i++)
 956     {
 957       if (listeners.elementAt(i) instanceof StructureListener)
 958       {
 959         sl = (StructureListener) listeners.elementAt(i);
 960         sl.updateColours(source);
 961       }
 962     }
 963   }
 964
 965   public StructureMapping[] getMapping(String pdbfile)
 966   {
 967     List<StructureMapping> tmp = new ArrayList<StructureMapping>();
 968     for (StructureMapping sm : mappings)
 969     {
 970       if (sm.pdbfile.equals(pdbfile))
 971       {
 972         tmp.add(sm);
 973       }
 974     }
 975     return tmp.toArray(new StructureMapping[tmp.size()]);
 976   }
 977
 978   /**
 979    * Returns a readable description of all mappings for the given pdbfile to any
 980    * of the given sequences
 981    *
 982    * @param pdbfile
 983    * @param seqs
 984    * @return
 985    */
 986   public String printMappings(String pdbfile, List<SequenceI> seqs)
 987   {
 988     if (pdbfile == null || seqs == null || seqs.isEmpty())
 989     {
 990       return "";
 991     }
 992
 993     StringBuilder sb = new StringBuilder(64);
 994     for (StructureMapping sm : mappings)
 995     {
 996       if (sm.pdbfile.equals(pdbfile) && seqs.contains(sm.sequence))
 997       {
 998         sb.append(sm.mappingDetails);
 999         sb.append(NEWLINE);
1000         // separator makes it easier to read multiple mappings
1001         sb.append("=====================");
1002         sb.append(NEWLINE);
1003       }
1004     }
1005     sb.append(NEWLINE);
1006
1007     return sb.toString();
1008   }
1009
1010   /**
1011    * Remove the given mapping
1012    *
1013    * @param acf
1014    */
1015   public void deregisterMapping(AlignedCodonFrame acf)
1016   {
1017     if (acf != null)
1018     {
1019       boolean removed = seqmappings.remove(acf);
1020       if (removed && seqmappings.isEmpty())
1021       { // debug
1022         System.out.println("All mappings removed");
1023       }
1024     }
1025   }
1026
1027   /**
1028    * Add each of the given codonFrames to the stored set, if not aready present.
1029    *
1030    * @param set
1031    */
1032   public void registerMappings(Set<AlignedCodonFrame> set)
1033   {
1034     if (set != null)
1035     {
1036       for (AlignedCodonFrame acf : set)
1037       {
1038         registerMapping(acf);
1039       }
1040     }
1041   }
1042
1043   /**
1044    * Add the given mapping to the stored set, unless already stored.
1045    */
1046   public void registerMapping(AlignedCodonFrame acf)
1047   {
1048     if (acf != null)
1049     {
1050       if (!seqmappings.contains(acf))
1051       {
1052         seqmappings.add(acf);
1053       }
1054     }
1055   }
1056
1057   /**
1058    * Resets this object to its initial state by removing all registered
1059    * listeners, codon mappings, PDB file mappings
1060    */
1061   public void resetAll()
1062   {
1063     if (mappings != null)
1064     {
1065       mappings.clear();
1066     }
1067     if (seqmappings != null)
1068     {
1069       seqmappings.clear();
1070     }
1071     if (sel_listeners != null)
1072     {
1073       sel_listeners.clear();
1074     }
1075     if (listeners != null)
1076     {
1077       listeners.clear();
1078     }
1079     if (commandListeners != null)
1080     {
1081       commandListeners.clear();
1082     }
1083     if (view_listeners != null)
1084     {
1085       view_listeners.clear();
1086     }
1087     if (pdbFileNameId != null)
1088     {
1089       pdbFileNameId.clear();
1090     }
1091     if (pdbIdFileName != null)
1092     {
1093       pdbIdFileName.clear();
1094     }
1095   }
1096
1097   public void addSelectionListener(SelectionListener selecter)
1098   {
1099     if (!sel_listeners.contains(selecter))
1100     {
1101       sel_listeners.add(selecter);
1102     }
1103   }
1104
1105   public void removeSelectionListener(SelectionListener toremove)
1106   {
1107     if (sel_listeners.contains(toremove))
1108     {
1109       sel_listeners.remove(toremove);
1110     }
1111   }
1112
1113   public synchronized void sendSelection(
1114           jalview.datamodel.SequenceGroup selection,
1115           jalview.datamodel.ColumnSelection colsel, SelectionSource source)
1116   {
1117     for (SelectionListener slis : sel_listeners)
1118     {
1119       if (slis != source)
1120       {
1121         slis.selection(selection, colsel, source);
1122       }
1123     }
1124   }
1125
1126   Vector<AlignmentViewPanelListener> view_listeners = new Vector<AlignmentViewPanelListener>();
1127
1128   public synchronized void sendViewPosition(
1129           jalview.api.AlignmentViewPanel source, int startRes, int endRes,
1130           int startSeq, int endSeq)
1131   {
1132
1133     if (view_listeners != null && view_listeners.size() > 0)
1134     {
1135       Enumeration<AlignmentViewPanelListener> listeners = view_listeners
1136               .elements();
1137       while (listeners.hasMoreElements())
1138       {
1139         AlignmentViewPanelListener slis = listeners.nextElement();
1140         if (slis != source)
1141         {
1142           slis.viewPosition(startRes, endRes, startSeq, endSeq, source);
1143         }
1144         ;
1145       }
1146     }
1147   }
1148
1149   /**
1150    * release all references associated with this manager provider
1151    *
1152    * @param jalviewLite
1153    */
1154   public static void release(StructureSelectionManagerProvider jalviewLite)
1155   {
1156     // synchronized (instances)
1157     {
1158       if (instances == null)
1159       {
1160         return;
1161       }
1162       StructureSelectionManager mnger = (instances.get(jalviewLite));
1163       if (mnger != null)
1164       {
1165         instances.remove(jalviewLite);
1166         try
1167         {
1168           mnger.finalize();
1169         } catch (Throwable x)
1170         {
1171         }
1172       }
1173     }
1174   }
1175
1176   public void registerPDBEntry(PDBEntry pdbentry)
1177   {
1178     if (pdbentry.getFile() != null
1179             && pdbentry.getFile().trim().length() > 0)
1180     {
1181       registerPDBFile(pdbentry.getId(), pdbentry.getFile());
1182     }
1183   }
1184
1185   public void addCommandListener(CommandListener cl)
1186   {
1187     if (!commandListeners.contains(cl))
1188     {
1189       commandListeners.add(cl);
1190     }
1191   }
1192
1193   public boolean hasCommandListener(CommandListener cl)
1194   {
1195     return this.commandListeners.contains(cl);
1196   }
1197
1198   public boolean removeCommandListener(CommandListener l)
1199   {
1200     return commandListeners.remove(l);
1201   }
1202
1203   /**
1204    * Forward a command to any command listeners (except for the command's
1205    * source).
1206    *
1207    * @param command
1208    *          the command to be broadcast (in its form after being performed)
1209    * @param undo
1210    *          if true, the command was being 'undone'
1211    * @param source
1212    */
1213   public void commandPerformed(CommandI command, boolean undo,
1214           VamsasSource source)
1215   {
1216     for (CommandListener listener : commandListeners)
1217     {
1218       listener.mirrorCommand(command, undo, this, source);
1219     }
1220   }
1221
1222   /**
1223    * Returns a new CommandI representing the given command as mapped to the
1224    * given sequences. If no mapping could be made, or the command is not of a
1225    * mappable kind, returns null.
1226    *
1227    * @param command
1228    * @param undo
1229    * @param mapTo
1230    * @param gapChar
1231    * @return
1232    */
1233   public CommandI mapCommand(CommandI command, boolean undo,
1234           final AlignmentI mapTo, char gapChar)
1235   {
1236     if (command instanceof EditCommand)
1237     {
1238       return MappingUtils.mapEditCommand((EditCommand) command, undo,
1239               mapTo, gapChar, seqmappings);
1240     }
1241     else if (command instanceof OrderCommand)
1242     {
1243       return MappingUtils.mapOrderCommand((OrderCommand) command, undo,
1244               mapTo, seqmappings);
1245     }
1246     return null;
1247   }
1248
1249   public IProgressIndicator getProgressIndicator()
1250   {
1251     return progressIndicator;
1252   }
1253
1254   public void setProgressIndicator(IProgressIndicator progressIndicator)
1255   {
1256     this.progressIndicator = progressIndicator;
1257   }
1258
1259   public long getProgressSessionId()
1260   {
1261     return progressSessionId;
1262   }
1263
1264   public void setProgressSessionId(long progressSessionId)
1265   {
1266     this.progressSessionId = progressSessionId;
1267   }
1268
1269   public void setProgressBar(String message)
1270   {
1271     progressIndicator.setProgressBar(message, progressSessionId);
1272   }
1273
1274 }