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