src/jalview/bin/JalviewJSApi.java

   1 package jalview.bin;
   2
   3 import java.io.IOException;
   4 import java.net.URL;
   5 import java.util.Hashtable;
   6
   7 import jalview.api.AlignViewportI;
   8 import jalview.datamodel.ColumnSelection;
   9 import jalview.datamodel.HiddenColumns;
  10 import jalview.datamodel.PDBEntry;
  11 import jalview.datamodel.SequenceGroup;
  12 import jalview.datamodel.SequenceI;
  13 import jalview.gui.AlignFrame;
  14 import jalview.io.DataSourceType;
  15 import jalview.io.NewickFile;
  16 import jalview.structure.SelectionSource;
  17 import jalview.structure.VamsasSource;
  18
  19 /**
  20  * JAL-3369 JalviewJS API BH 2019.07.17
  21  *
  22  * @author hansonr
  23  *
  24  */
  25 public interface JalviewJSApi
  26 {
  27
  28   // debug flag - controls output to standard out
  29   public static boolean debug = false;
  30
  31   /**
  32    * bind a pdb file to a sequence in the given AlignFrame.
  33    *
  34    * @param alFrame
  35    *          - null or specific AlignFrame. This specifies the dataset that
  36    *          will be searched for a seuqence called sequenceId
  37    * @param sequenceId
  38    *          - sequenceId within the dataset.
  39    * @param pdbEntryString
  40    *          - the short name for the PDB file
  41    * @param pdbFile
  42    *          - pdb file - either a URL or a valid PDB file.
  43    * @return true if binding was as success TODO: consider making an exception
  44    *         structure for indicating when PDB parsing or sequenceId location
  45    *         fails.
  46    */
  47   public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
  48           String pdbEntryString, String pdbFile);
  49
  50   public String arrayToSeparatorList(String[] array);
  51
  52   /**
  53    * The following public methods may be called externally, eg via javascript in
  54    * an HTML page.
  55    *
  56    * <br>
  57    * <em>TODO: introduce abstract interface for
  58    * jalview.appletgui.AlignFrame</em><br>
  59    *
  60    * Most function arguments are strings, which contain serialised versions of
  61    * lists. Lists of things are separated by a separator character - either the
  62    * default or a user supplied one. Ranges and positions on an alignment or
  63    * sequence can be specified as a list, where an item containing a single
  64    * number is a single position, and an item like 1-2 specifies columns 1 and 2
  65    * as a range.
  66    */
  67
  68   // /**
  69   // * @author jimp
  70   // *
  71   // */
  72   // public interface JalviewLiteJsApi
  73   // {
  74
  75   /**
  76    * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
  77    * PFAM - see jalview.io.AppletFormatAdapter for full list);
  78    *
  79    * @param format
  80    * @return
  81    */
  82
  83   public abstract String getAlignment(String format);
  84
  85   /**
  86    * get alignment as format with jalview start-end sequence suffix appended
  87    *
  88    * @param format
  89    * @param suffix
  90    * @return
  91    */
  92
  93   public abstract String getAlignment(String format, String suffix);
  94
  95   /**
  96    * get alignment displayed in alf as format
  97    *
  98    * @param alf
  99    * @param format
 100    * @return
 101    */
 102   public abstract String getAlignmentFrom(AlignFrame alf, String format);
 103
 104   /**
 105    * get alignment displayed in alf as format with or without the jalview
 106    * start-end sequence suffix appended
 107    *
 108    * @param alf
 109    * @param format
 110    * @param suffix
 111    * @return
 112    */
 113   public abstract String getAlignmentFrom(AlignFrame alf, String format,
 114           String suffix);
 115
 116   /**
 117    * get a separator separated list of sequence IDs reflecting the order of the
 118    * current alignment
 119    *
 120    * @return
 121    */
 122
 123   public abstract String getAlignmentOrder();
 124
 125   /**
 126    * get a separator separated list of sequence IDs reflecting the order of the
 127    * alignment in alf
 128    *
 129    * @param alf
 130    * @return
 131    */
 132   public abstract String getAlignmentOrderFrom(AlignFrame alf);
 133
 134   /**
 135    * get a sep separated list of sequence IDs reflecting the order of the
 136    * alignment in alf
 137    *
 138    * @param alf
 139    * @param sep
 140    *          - separator to use
 141    * @return
 142    */
 143   public abstract String getAlignmentOrderFrom(AlignFrame alf, String sep);
 144
 145   /**
 146    * get current alignment's annotation as an annotation file
 147    *
 148    * @return
 149    */
 150
 151   public abstract String getAnnotation();
 152
 153   /**
 154    * get alignment view alf's annotation as an annotation file
 155    *
 156    * @param alf
 157    * @return
 158    */
 159   public abstract String getAnnotationFrom(AlignFrame alf);
 160
 161   public Object getAppletParameter(String name, boolean asString);
 162
 163   public URL getCodeBase();
 164
 165   public URL getDocumentBase();
 166
 167   /**
 168    *
 169    * @return
 170    * @see jalview.appletgui.AlignFrame#getFeatureGroups();
 171    */
 172
 173   public abstract String getFeatureGroups();
 174
 175   /**
 176    * @param visible
 177    * @return
 178    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
 179    */
 180
 181   public abstract String getFeatureGroupsOfState(boolean visible);
 182
 183   /**
 184    * @param alf
 185    *          align frame to get groups of state visible
 186    * @param visible
 187    * @return
 188    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean);
 189    */
 190   public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
 191           boolean visible);
 192
 193   /**
 194    * @param alf
 195    *          AlignFrame to get feature groups on
 196    * @return
 197    * @see jalview.appletgui.AlignFrame#getFeatureGroups();
 198    */
 199   public abstract String getFeatureGroupsOn(AlignFrame alf);
 200
 201   /**
 202    * get the sequence features in the given format (Jalview or GFF);
 203    *
 204    * @param format
 205    * @return
 206    */
 207
 208   public abstract String getFeatures(String format);
 209
 210   /**
 211    * get the sequence features in alf in the given format (Jalview or GFF);
 212    *
 213    * @param alf
 214    * @param format
 215    * @return
 216    */
 217   public abstract String getFeaturesFrom(AlignFrame alf, String format);
 218
 219   public Object getFrameForSource(VamsasSource source);
 220
 221   public Hashtable<String, int[]> getJSHashes();
 222
 223   /**
 224    * Retrieve fragments of a large packet of data made available by JalviewLite.
 225    *
 226    * @param messageclass
 227    * @param viewId
 228    * @return next chunk of message
 229    */
 230
 231   public abstract String getJsMessage(String messageclass, String viewId);
 232
 233   Hashtable<String, Hashtable<String, String[]>> getJSMessages();
 234
 235   public Object getJSObject();
 236
 237   public jalview.renderer.seqfeatures.FeatureRenderer getNewFeatureRenderer(
 238           AlignViewportI vp);
 239
 240   public String getParameter(String name);
 241
 242   /**
 243    * @return String list of selected sequence IDs, each terminated by the
 244    *         'boolean not' character (""+0x00AC); or (&#172;);
 245    */
 246
 247   public abstract String getSelectedSequences();
 248
 249   /**
 250    * @param sep
 251    *          separator string or null for default
 252    * @return String list of selected sequence IDs, each terminated by given
 253    *         separator string
 254    */
 255
 256   public abstract String getSelectedSequences(String sep);
 257
 258   /**
 259    * get sequences selected in current AlignFrame and return their alignment in
 260    * format 'format' either with or without suffix
 261    *
 262    * @param alf
 263    *          - where selection is
 264    * @param format
 265    *          - format of alignment file
 266    * @param suffix
 267    *          - "true" to append /start-end string to each sequence ID
 268    * @return selected sequences as flat file or empty string if there was no
 269    *         current selection
 270    */
 271
 272   public abstract String getSelectedSequencesAsAlignment(String format,
 273           String suffix);
 274
 275   /**
 276    * get sequences selected in alf and return their alignment in format 'format'
 277    * either with or without suffix
 278    *
 279    * @param alf
 280    *          - where selection is
 281    * @param format
 282    *          - format of alignment file
 283    * @param suffix
 284    *          - "true" to append /start-end string to each sequence ID
 285    * @return selected sequences as flat file or empty string if there was no
 286    *         current selection
 287    */
 288   public abstract String getSelectedSequencesAsAlignmentFrom(AlignFrame alf,
 289           String format, String suffix);
 290
 291   /**
 292    * @param alf
 293    *          AlignFrame containing selection
 294    * @return String list of selected sequence IDs, each terminated by current
 295    *         default separator sequence
 296    *
 297    */
 298   public abstract String getSelectedSequencesFrom(AlignFrame alf);
 299
 300   // BH incompatibility here -- JalviewLite created an AlignFrame; Jalview
 301   // creates an AlignmentPanel
 302   // /**
 303   // * create a new view and return the AlignFrame instance
 304   // *
 305   // * @return
 306   // */
 307   //
 308   // public abstract AlignFrame newView();
 309   //
 310   // /**
 311   // * create a new view named name and return the AlignFrame instance
 312   // *
 313   // * @param name
 314   // * @return
 315   // */
 316   //
 317   // public abstract AlignFrame newView(String name);
 318   //
 319   // /**
 320   // * create a new view on alf and return the AlignFrame instance
 321   // *
 322   // * @param alf
 323   // * @return
 324   // */
 325   // public abstract AlignFrame newViewFrom(AlignFrame alf);
 326   //
 327   // /**
 328   // * create a new view named name on alf
 329   // *
 330   // * @param alf
 331   // * @param name
 332   // * @return
 333   // */
 334   // public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
 335
 336   /**
 337    * get list of selected sequence IDs separated by given separator
 338    *
 339    * @param alf
 340    *          window containing selection
 341    * @param sep
 342    *          separator string to use - default is 'boolean not'
 343    * @return String list of selected sequence IDs, each terminated by the given
 344    *         separator
 345    */
 346   public abstract String getSelectedSequencesFrom(AlignFrame alf,
 347           String sep);
 348
 349   public Object[] getSelectionForListener(SequenceGroup seqsel,
 350           ColumnSelection colsel, HiddenColumns hidden,
 351           SelectionSource source, Object alignFrame);
 352
 353   /**
 354    * List separator string
 355    *
 356    * @return the separator
 357    */
 358
 359   public abstract String getSeparator();
 360
 361   public AlignViewportI getViewport();
 362
 363   /**
 364    *
 365    * @param sequenceId
 366    *          id of sequence to highlight
 367    * @param position
 368    *          integer position [ tobe implemented or range ] on sequence
 369    * @param alignedPosition
 370    *          true/false/empty string - indicate if position is an alignment
 371    *          column or unaligned sequence position
 372    */
 373
 374   public abstract void highlight(String sequenceId, String position,
 375           String alignedPosition);
 376
 377   /**
 378    *
 379    * @param sequenceId
 380    *          id of sequence to highlight
 381    * @param position
 382    *          integer position [ tobe implemented or range ] on sequence
 383    * @param alignedPosition
 384    *          false, blank or something else - indicate if position is an
 385    *          alignment column or unaligned sequence position
 386    */
 387   public abstract void highlightIn(AlignFrame alf, String sequenceId,
 388           String position, String alignedPosition);
 389
 390   /**
 391    *
 392    * @param text
 393    *          alignment file as a string
 394    * @param title
 395    *          window title
 396    * @return null or new alignment frame
 397    */
 398
 399   public abstract AlignFrame loadAlignment(String text, String title);
 400
 401   /**
 402    * add the given features or annotation to the current alignment
 403    *
 404    * @param annotation
 405    */
 406
 407   public abstract void loadAnnotation(String annotation);
 408
 409   /**
 410    * add the given features or annotation to the given alignment view
 411    *
 412    * @param alf
 413    * @param annotation
 414    */
 415   public abstract void loadAnnotationFrom(AlignFrame alf,
 416           String annotation);
 417
 418   /**
 419    * parse the given string as a jalview feature or GFF annotation file and
 420    * optionally enable feature display on the current AlignFrame
 421    *
 422    * @param features
 423    *          - gff or features file
 424    * @param autoenabledisplay
 425    *          - when true, feature display will be enabled if any features can
 426    *          be parsed from the string.
 427    */
 428
 429   public abstract void loadFeatures(String features,
 430           boolean autoenabledisplay);
 431
 432   /**
 433    * parse the given string as a jalview feature or GFF annotation file and
 434    * optionally enable feature display on the given AlignFrame.
 435    *
 436    * @param alf
 437    * @param features
 438    *          - gff or features file
 439    * @param autoenabledisplay
 440    *          - when true, feature display will be enabled if any features can
 441    *          be parsed from the string.
 442    * @return true if data parsed as features
 443    */
 444   public abstract boolean loadFeaturesFrom(AlignFrame alf, String features,
 445           boolean autoenabledisplay);
 446
 447   public boolean loadScoreFile(String sScoreFile) throws IOException;
 448
 449   public void newFeatureSettings();
 450
 451   public void newStructureView(PDBEntry pdb, SequenceI[] seqs,
 452           String[] chains, DataSourceType protocol);
 453
 454   /**
 455    * public static method for JalviewJS API to open a PCAPanel without
 456    * necessarily using a dialog.
 457    *
 458    * @param af
 459    *          may be null
 460    * @param modelName
 461    * @return the PCAPanel, or the string "label.you_need_at_least_n_sequences"
 462    *         if number of sequences selected is inappropriate
 463    */
 464   public Object openPcaPanel(AlignFrame af, String modelName);
 465
 466   /**
 467    * Open a new Tree panel on the desktop statically. Params are standard (not
 468    * set by Groovy). No dialog is opened.
 469    *
 470    * @param af
 471    *          may be null
 472    * @param treeType
 473    * @param modelName
 474    * @return null, or the string "label.you_need_at_least_n_sequences" if number
 475    *         of sequences selected is inappropriate
 476    */
 477   public Object openTreePanel(AlignFrame af, String treeType,
 478           String modelName);
 479
 480   /// in http://www.jalview.org/examples/jalviewLiteJs.html but missing here
 481
 482   // get selected sequences as alignment as format with or without start-end
 483   // suffix
 484
 485   /**
 486    * re-order the given alignment using the given list of sequence IDs separated
 487    * by sep
 488    *
 489    * @param alf
 490    * @param order
 491    *          - sep separated list
 492    * @param undoName
 493    *          - string to use when referring to ordering action in undo buffer
 494    * @param sep
 495    * @return 'true' if alignment was actually reordered. empty string if
 496    *         alignment did not contain sequences.
 497    */
 498   public abstract String orderAlignmentBy(AlignFrame alf, String order,
 499           String undoName, String sep);
 500
 501   // get a string array from a list
 502
 503   /**
 504    * re-order the current alignment using the given list of sequence IDs
 505    *
 506    * @param order
 507    *          - sep separated list
 508    * @param undoName
 509    *          - string to use when referring to ordering action in undo buffer
 510    * @return 'true' if alignment was actually reordered. empty string if
 511    *         alignment did not contain sequences.
 512    */
 513
 514   public abstract String orderBy(String order, String undoName);
 515
 516   /**
 517    * re-order the current alignment using the given list of sequence IDs
 518    * separated by sep
 519    *
 520    * @param order
 521    *          - sep separated list
 522    * @param undoName
 523    *          - string to use when referring to ordering action in undo buffer
 524    * @param sep
 525    * @return 'true' if alignment was actually reordered. empty string if
 526    *         alignment did not contain sequences.
 527    */
 528
 529   public abstract String orderBy(String order, String undoName, String sep);
 530
 531   /**
 532    * process commandline arguments after the JavaScript application has started
 533    *
 534    * @param args
 535    * @return
 536    */
 537   Object parseArguments(String[] args);
 538
 539   // public boolean getDefaultParameter(String name, boolean def);
 540
 541   public boolean parseFeaturesFile(String param, DataSourceType protocol);
 542
 543   /**
 544    * remove any callback using the given listener function and associated with
 545    * the given AlignFrame (or null for all callbacks);
 546    *
 547    * @param af
 548    *          (may be null);
 549    * @param listener
 550    *          (may be null);
 551    */
 552   public abstract void removeSelectionListener(AlignFrame af,
 553           String listener);
 554
 555   // public void setAlignPdbStructures(boolean defaultParameter);
 556
 557   /**
 558    * adjust horizontal scroll to make the given column the left one in the given
 559    * view
 560    *
 561    * @param alf
 562    * @param leftHandColumn
 563    */
 564   public abstract void scrollViewToColumnIn(AlignFrame alf,
 565           String leftHandColumn);
 566
 567   /**
 568    * adjust horizontal/vertical scroll to make the given location the top left
 569    * hand corner for the given view
 570    *
 571    * @param alf
 572    * @param topRow
 573    * @param leftHandColumn
 574    */
 575   public abstract void scrollViewToIn(AlignFrame alf, String topRow,
 576           String leftHandColumn);
 577
 578   /**
 579    * adjust vertical scroll to make the given row the top one for given view
 580    *
 581    * @param alf
 582    * @param topRow
 583    */
 584   public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
 585
 586   /**
 587    * select regions of the currrent alignment frame
 588    *
 589    * @param sequenceIds
 590    *          String separated list of sequence ids or empty string
 591    * @param columns
 592    *          String separated list { column range or column, ..} or empty
 593    *          string
 594    */
 595
 596   public abstract void select(String sequenceIds, String columns);
 597
 598   /**
 599    * select regions of the currrent alignment frame
 600    *
 601    * @param toselect
 602    *          String separated list { column range, seq1...seqn sequence ids }
 603    * @param sep
 604    *          separator between toselect fields
 605    */
 606
 607   public abstract void select(String sequenceIds, String columns,
 608           String sep);
 609
 610   /**
 611    * select regions of the given alignment frame
 612    *
 613    * @param alf
 614    * @param toselect
 615    *          String separated list { column range, seq1...seqn sequence ids }
 616    * @param sep
 617    *          separator between toselect fields
 618    */
 619   public abstract void selectIn(AlignFrame alf, String sequenceIds,
 620           String columns);
 621
 622   /**
 623    * select regions of the given alignment frame
 624    *
 625    * @param alf
 626    * @param toselect
 627    *          String separated list { column range, seq1...seqn sequence ids }
 628    * @param sep
 629    *          separator between toselect fields
 630    */
 631   public abstract void selectIn(AlignFrame alf, String sequenceIds,
 632           String columns, String sep);
 633
 634   public String[] separatorListToArray(String list);
 635
 636   public abstract void setFeatureGroupState(String groups, boolean state);
 637
 638   public void setFeatureGroupState(String[] groups, boolean state);
 639
 640   // public StructureSelectionManagerProvider
 641   // getStructureSelectionManagerProvider();
 642
 643   /**
 644    * @param groups
 645    *          tab separated list of group names
 646    * @param state
 647    *          true or false
 648    * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
 649    *      boolean);
 650    */
 651   public abstract void setFeatureGroupStateOn(AlignFrame alf, String groups,
 652           boolean state);
 653
 654   public abstract void setSelectionListener(AlignFrame af, String listener);
 655
 656   /**
 657    * register a javascript function to handle any alignment selection events.
 658    * Events are generated when the user completes a selection event, or when the
 659    * user deselects all selected regions.
 660    *
 661    * @param listener
 662    *          name of javascript function (called with arguments
 663    *          [jalview.appletgui.AlignFrame, String(sequence set id);,
 664    *          String(separator separated list of sequences which were
 665    *          selected);, String(separator separated list of column ranges (i.e.
 666    *          single number or hyphenated range); that were selected);]
 667    */
 668
 669   public abstract void setSelectionListener(String listener);
 670
 671   /**
 672    * List separator string
 673    *
 674    * @param separator
 675    *          the separator to set. empty string will reset separator to default
 676    */
 677
 678   public abstract void setSeparator(String separator);
 679
 680   void showOverview();
 681
 682   public void updateForAnnotations();
 683
 684 }