src/jalview/ws/rest/RestServiceDescription.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.6)
   3  * Copyright (C) 2010 J Procter, AM Waterhouse, G Barton, M Clamp, S Searle
   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 of the License, or (at your option) any later version.
  10  *
  11  * Jalview is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty
  13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  14  * PURPOSE.  See the GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18 package jalview.ws.rest;
  19
  20
  21 import jalview.datamodel.SequenceI;
  22 import jalview.util.GroupUrlLink.UrlStringTooLongException;
  23 import jalview.util.Platform;
  24 import jalview.ws.rest.params.Alignment;
  25 import jalview.ws.rest.params.AnnotationFile;
  26 import jalview.ws.rest.params.SeqGroupIndexVector;
  27
  28 import java.util.HashMap;
  29 import java.util.Hashtable;
  30 import java.util.Map;
  31
  32
  33 public class RestServiceDescription
  34 {
  35   /**
  36    * @param details
  37    * @param postUrl
  38    * @param urlSuffix
  39    * @param inputParams
  40    * @param hseparable
  41    * @param vseparable
  42    * @param gapCharacter
  43    */
  44   public RestServiceDescription(String action,String description,String name, String postUrl,
  45           String urlSuffix, Map<String, InputType> inputParams,
  46           boolean hseparable, boolean vseparable, char gapCharacter)
  47   {
  48     super();
  49     this.details = new UIinfo();
  50     details.Action= action;
  51     details.description = description;
  52     details.Name = name;
  53     this.postUrl = postUrl;
  54     this.urlSuffix = urlSuffix;
  55     this.inputParams = inputParams;
  56     this.hseparable = hseparable;
  57     this.vseparable = vseparable;
  58     this.gapCharacter = gapCharacter;
  59   }
  60   /**
  61    * Service UI Info { Action, Specific Name of Service, Brief Description }
  62    */
  63
  64   public class UIinfo {
  65     String Action;
  66     String Name;
  67     String description;
  68   }
  69   UIinfo details = new UIinfo();
  70
  71   /** Service base URL
  72    */
  73   String postUrl;
  74   /**
  75    * suffix that should be added to any url used if it does not already end in the suffix.
  76    */
  77   String urlSuffix;
  78
  79   /***
  80    * modelling the io:
  81    * validation of input
  82    * { formatter for type, parser for type }
  83    *
  84    */
  85   /** input info given as key/value pairs - mapped to post arguments
  86    */
  87   Map<String,InputType> inputParams=new HashMap();
  88   /**
  89    * service requests alignment data
  90    */
  91   boolean aligndata;
  92   /**
  93    * service requests alignment and/or seuqence annotationo data
  94    */
  95   boolean annotdata;
  96   /**
  97    * service requests partitions defined over input (alignment) data
  98    */
  99   boolean partitiondata;
 100
 101   /**
 102    * process ths input data and set the appropriate shorthand flags describing the input the service wants
 103    */
 104   public void setInvolvesFlags() {
 105     aligndata = inputInvolves(Alignment.class);
 106     annotdata = inputInvolves(AnnotationFile.class);
 107     partitiondata = inputInvolves(SeqGroupIndexVector.class);
 108   }
 109
 110   /** Service return info { alignment, annotation file (loaded back on to alignment), tree (loaded back on to alignment), sequence annotation - loaded back on to alignment), text report, pdb structures with sequence mapping )
 111    *
 112    */
 113
 114   /** Start with bare minimum: input is alignment + groups on alignment
 115    *
 116    * @author JimP
 117    *
 118    */
 119
 120   /**
 121    * Helper class based on the UrlLink class which enables URLs to be
 122    * constructed from sequences or IDs associated with a group of sequences. URL
 123    * definitions consist of a pipe separated string containing a <label>|<url
 124    * construct>|<separator character>[|<sequence separator character>]. The url
 125    * construct includes regex qualified tokens which are replaced with seuqence
 126    * IDs ($SEQUENCE_IDS$) and/or seuqence regions ($SEQUENCES$) that are
 127    * extracted from the group. See <code>UrlLink</code> for more information
 128    * about the approach, and the original implementation. Documentation to come.
 129    * Note - groupUrls can be very big!
 130    */
 131   private String url_prefix, target, label;
 132
 133   /**
 134    * these are all filled in order of the occurence of each token in the url
 135    * string template
 136    */
 137   private String url_suffix[], separators[], regexReplace[];
 138
 139   private String invalidMessage = null;
 140
 141   /**
 142    * tokens that can be replaced in the URL.
 143    */
 144   private static String[] tokens;
 145
 146   /**
 147    * position of each token (which can appear once only) in the url
 148    */
 149   private int[] segs;
 150
 151   /**
 152    * contains tokens in the order they appear in the URL template.
 153    */
 154   private String[] mtch;
 155   static
 156   {
 157     if (tokens == null)
 158     {
 159       tokens = new String[]
 160       { "SEQUENCEIDS", "SEQUENCES", "DATASETID" };
 161     }
 162   }
 163
 164   /**
 165    * test for GroupURLType bitfield (with default tokens)
 166    */
 167   public static final int SEQUENCEIDS = 1;
 168
 169   /**
 170    * test for GroupURLType bitfield (with default tokens)
 171    */
 172   public static final int SEQUENCES = 2;
 173
 174   /**
 175    * test for GroupURLType bitfield (with default tokens)
 176    */
 177   public static final int DATASETID = 4;
 178
 179   // private int idseg = -1, seqseg = -1;
 180
 181   /**
 182    * parse the given linkString of the form '<label>|<url>|separator
 183    * char[|optional sequence separator char]' into parts. url may contain a
 184    * string $SEQUENCEIDS<=optional regex=>$ where <=optional regex=> must be of
 185    * the form =/<perl style regex>/=$ or $SEQUENCES<=optional regex=>$ or
 186    * $SEQUENCES<=optional regex=>$.
 187    *
 188    * @param link
 189    */
 190   public RestServiceDescription(String link)
 191   {
 192     int sep = link.indexOf("|");
 193     segs = new int[tokens.length];
 194     int ntoks = 0;
 195     for (int i = 0; i < segs.length; i++)
 196     {
 197       if ((segs[i] = link.indexOf("$" + tokens[i])) > -1)
 198       {
 199         ntoks++;
 200       }
 201     }
 202     // expect at least one token
 203     if (ntoks == 0)
 204     {
 205       invalidMessage = "Group URL string must contain at least one of ";
 206       for (int i = 0; i < segs.length; i++)
 207       {
 208         invalidMessage += " '$" + tokens[i] + "[=/regex=/]$'";
 209       }
 210       return;
 211     }
 212
 213     int[] ptok = new int[ntoks + 1];
 214     String[] tmtch = new String[ntoks + 1];
 215     mtch = new String[ntoks];
 216     for (int i = 0, t = 0; i < segs.length; i++)
 217     {
 218       if (segs[i] > -1)
 219       {
 220         ptok[t] = segs[i];
 221         tmtch[t++] = tokens[i];
 222       }
 223     }
 224     ptok[ntoks] = link.length();
 225     tmtch[ntoks] = "$$$$$$$$$";
 226     jalview.util.QuickSort.sort(ptok, tmtch);
 227     for (int i = 0; i < ntoks; i++)
 228     {
 229       mtch[i] = tmtch[i]; // TODO: check order is ascending
 230     }
 231     /*
 232      * replaces the specific code below {}; if (psqids > -1 && pseqs > -1) { if
 233      * (psqids > pseqs) { idseg = 1; seqseg = 0;
 234      *
 235      * ptok = new int[] { pseqs, psqids, link.length() }; mtch = new String[] {
 236      * "$SEQUENCES", "$SEQUENCEIDS" }; } else { idseg = 0; seqseg = 1; ptok =
 237      * new int[] { psqids, pseqs, link.length() }; mtch = new String[] {
 238      * "$SEQUENCEIDS", "$SEQUENCES" }; } } else { if (psqids != -1) { idseg = 0;
 239      * ptok = new int[] { psqids, link.length() }; mtch = new String[] {
 240      * "$SEQUENCEIDS" }; } else { seqseg = 0; ptok = new int[] { pseqs,
 241      * link.length() }; mtch = new String[] { "$SEQUENCES" }; } }
 242      */
 243
 244     int p = sep;
 245     // first get the label and target part before the first |
 246     do
 247     {
 248       sep = p;
 249       p = link.indexOf("|", sep + 1);
 250     } while (p > sep && p < ptok[0]);
 251     // Assuming that the URL itself does not contain any '|' symbols
 252     // sep now contains last pipe symbol position prior to any regex symbols
 253     label = link.substring(0, sep);
 254     if (label.indexOf("|") > -1)
 255     {
 256       // | terminated database name / www target at start of Label
 257       target = label.substring(0, label.indexOf("|"));
 258     }
 259     else if (label.indexOf(" ") > 2)
 260     {
 261       // space separated Label - matches database name
 262       target = label.substring(0, label.indexOf(" "));
 263     }
 264     else
 265     {
 266       target = label;
 267     }
 268     // Now Parse URL : Whole URL string first
 269     url_prefix = link.substring(sep + 1, ptok[0]);
 270     url_suffix = new String[mtch.length];
 271     regexReplace = new String[mtch.length];
 272     // and loop through tokens
 273     for (int pass = 0; pass < mtch.length; pass++)
 274     {
 275       int mlength = 3 + mtch[pass].length();
 276       if (link.indexOf("$" + mtch[pass] + "=/") == ptok[pass]
 277               && (p = link.indexOf("/=$", ptok[pass] + mlength)) > ptok[pass]
 278                       + mlength)
 279       {
 280         // Extract Regex and suffix
 281         if (ptok[pass + 1] < p + 3)
 282         {
 283           // tokens are not allowed inside other tokens - e.g. inserting a
 284           // $sequences$ into the regex match for the sequenceid
 285           invalidMessage = "Token regexes cannot contain other regexes (did you terminate the $"
 286                   + mtch[pass] + " regex with a '/=$' ?";
 287           return;
 288         }
 289         url_suffix[pass] = link.substring(p + 3, ptok[pass + 1]);
 290         regexReplace[pass] = link.substring(ptok[pass] + mlength, p);
 291         try
 292         {
 293           com.stevesoft.pat.Regex rg = com.stevesoft.pat.Regex.perlCode("/"
 294                   + regexReplace[pass] + "/");
 295           if (rg == null)
 296           {
 297             invalidMessage = "Invalid Regular Expression : '"
 298                     + regexReplace[pass] + "'\n";
 299           }
 300         } catch (Exception e)
 301         {
 302           invalidMessage = "Invalid Regular Expression : '"
 303                   + regexReplace[pass] + "'\n";
 304         }
 305       }
 306       else
 307       {
 308         regexReplace[pass] = null;
 309         // verify format is really correct.
 310         if ((p = link.indexOf("$" + mtch[pass] + "$")) == ptok[pass])
 311         {
 312           url_suffix[pass] = link.substring(p + mtch[pass].length() + 2,
 313                   ptok[pass + 1]);
 314         }
 315         else
 316         {
 317           invalidMessage = "Warning: invalid regex structure (after '"
 318                   + mtch[0] + "') for URL link : " + link;
 319         }
 320       }
 321     }
 322     int pass = 0;
 323     separators = new String[url_suffix.length];
 324     String suffices = url_suffix[url_suffix.length - 1], lastsep = ",";
 325     // have a look in the last suffix for any more separators.
 326     while ((p = suffices.indexOf('|')) > -1)
 327     {
 328       separators[pass] = suffices.substring(p + 1);
 329       if (pass == 0)
 330       {
 331         // trim the original suffix string
 332         url_suffix[url_suffix.length - 1] = suffices.substring(0, p);
 333       }
 334       else
 335       {
 336         lastsep = (separators[pass - 1] = separators[pass - 1].substring(0,
 337                 p));
 338       }
 339       suffices = separators[pass];
 340       pass++;
 341     }
 342     if (pass > 0)
 343     {
 344       lastsep = separators[pass - 1];
 345     }
 346     // last separator is always used for all the remaining separators
 347     while (pass < separators.length)
 348     {
 349       separators[pass++] = lastsep;
 350     }
 351   }
 352
 353   /**
 354    * @return the url_suffix
 355    */
 356   public String getUrl_suffix()
 357   {
 358     return url_suffix[url_suffix.length - 1];
 359   }
 360
 361   /**
 362    * @return the url_prefix
 363    */
 364   public String getUrl_prefix()
 365   {
 366     return url_prefix;
 367   }
 368
 369   /**
 370    * @return the target
 371    */
 372   public String getTarget()
 373   {
 374     return target;
 375   }
 376
 377   /**
 378    * @return the label
 379    */
 380   public String getLabel()
 381   {
 382     return label;
 383   }
 384
 385   /**
 386    * @return the sequence ID regexReplace
 387    */
 388   public String getIDRegexReplace()
 389   {
 390     return _replaceFor(tokens[0]);
 391   }
 392
 393   private String _replaceFor(String token)
 394   {
 395     for (int i = 0; i < mtch.length; i++)
 396       if (segs[i] > -1 && mtch[i].equals(token))
 397       {
 398         return regexReplace[i];
 399       }
 400     return null;
 401   }
 402
 403   /**
 404    * @return the sequence ID regexReplace
 405    */
 406   public String getSeqRegexReplace()
 407   {
 408     return _replaceFor(tokens[1]);
 409   }
 410
 411   /**
 412    * @return the invalidMessage
 413    */
 414   public String getInvalidMessage()
 415   {
 416     return invalidMessage;
 417   }
 418
 419   /**
 420    * Check if URL string was parsed properly.
 421    *
 422    * @return boolean - if false then <code>getInvalidMessage</code> returns an
 423    *         error message
 424    */
 425   public boolean isValid()
 426   {
 427     return invalidMessage == null;
 428   }
 429
 430
 431   /**
 432    * gathers input into a hashtable
 433    *
 434    * @param idstrings
 435    * @param seqstrings
 436    * @param dsstring
 437    * @return
 438    */
 439   private Hashtable replacementArgs(String[] idstrings,
 440           String[] seqstrings, String dsstring)
 441   {
 442     Hashtable rstrings = new Hashtable();
 443     rstrings.put(tokens[0], idstrings);
 444     rstrings.put(tokens[1], seqstrings);
 445     rstrings.put(tokens[2], new String[]
 446     { dsstring });
 447     if (idstrings.length != seqstrings.length)
 448     {
 449       throw new Error(
 450               "idstrings and seqstrings contain one string each per sequence.");
 451     }
 452     return rstrings;
 453   }
 454
 455
 456
 457
 458   /**
 459    * conditionally generate urls or stubs for a given input.
 460    *
 461    * @param createFullUrl
 462    *          set to false if you only want to test if URLs would be generated.
 463    * @param repstrings
 464    * @param onlyIfMatches
 465    * @return null if no url is generated. Object[] { int[] { number of matches
 466    *         seqs }, boolean[] { which matched }, (if createFullUrl also has
 467    *         StringBuffer[] { segment generated from inputs that is used in URL
 468    *         }, String[] { url })}
 469    * @throws Exception
 470    * @throws UrlStringTooLongException
 471    */
 472   protected Object[] makeUrlsIf(boolean createFullUrl,
 473           Hashtable repstrings, boolean onlyIfMatches) throws Exception
 474   {
 475     int pass = 0;
 476
 477     // prepare string arrays in correct order to be assembled into URL input
 478     String[][] idseq = new String[mtch.length][]; // indexed by pass
 479     int mins = 0, maxs = 0; // allowed two values, 1 or n-sequences.
 480     for (int i = 0; i < mtch.length; i++)
 481     {
 482       idseq[i] = (String[]) repstrings.get(mtch[i]);
 483       if (idseq[i].length >= 1)
 484       {
 485         if (mins == 0 && idseq[i].length == 1)
 486         {
 487           mins = 1;
 488         }
 489         if (maxs < 2)
 490         {
 491           maxs = idseq[i].length;
 492         }
 493         else
 494         {
 495           if (maxs != idseq[i].length)
 496           {
 497             throw new Error(
 498                     "Cannot have mixed length replacement vectors. Replacement vector for "
 499                             + (mtch[i]) + " is " + idseq[i].length
 500                             + " strings long, and have already seen a "
 501                             + maxs + " length vector.");
 502           }
 503         }
 504       }
 505       else
 506       {
 507         throw new Error(
 508                 "Cannot have zero length vector of replacement strings - either 1 value or n values.");
 509       }
 510     }
 511     // iterate through input, collating segments to be inserted into url
 512     StringBuffer matched[] = new StringBuffer[idseq.length];
 513     // and precompile regexes
 514     com.stevesoft.pat.Regex[] rgxs = new com.stevesoft.pat.Regex[matched.length];
 515     for (pass = 0; pass < matched.length; pass++)
 516     {
 517       matched[pass] = new StringBuffer();
 518       if (regexReplace[pass] != null)
 519       {
 520         rgxs[pass] = com.stevesoft.pat.Regex.perlCode("/"
 521                 + regexReplace[pass] + "/");
 522       }
 523       else
 524       {
 525         rgxs[pass] = null;
 526       }
 527     }
 528     // tot up the invariant lengths for this url
 529     int urllength = url_prefix.length();
 530     for (pass = 0; pass < matched.length; pass++)
 531     {
 532       urllength += url_suffix[pass].length();
 533     }
 534
 535     // flags to record which of the input sequences were actually used to
 536     // generate the
 537     // url
 538     boolean[] thismatched = new boolean[maxs];
 539     int seqsmatched = 0;
 540     for (int sq = 0; sq < maxs; sq++)
 541     {
 542       // initialise flag for match
 543       thismatched[sq] = false;
 544       StringBuffer[] thematches = new StringBuffer[rgxs.length];
 545       for (pass = 0; pass < rgxs.length; pass++)
 546       {
 547         thematches[pass] = new StringBuffer(); // initialise - in case there are
 548                                                // no more
 549         // matches.
 550         // if a regex is provided, then it must match for all sequences in all
 551         // tokens for it to be considered.
 552         if (idseq[pass].length <= sq)
 553         {
 554           // no more replacement strings to try for this token
 555           continue;
 556         }
 557         if (rgxs[pass] != null)
 558         {
 559           com.stevesoft.pat.Regex rg = rgxs[pass];
 560           int rematchat = 0;
 561           // concatenate all matches of re in the given string!
 562           while (rg.searchFrom(idseq[pass][sq], rematchat))
 563           {
 564             rematchat = rg.matchedTo();
 565             thismatched[sq] |= true;
 566             urllength += rg.charsMatched(); // count length
 567             if ((urllength + 32) > Platform.getMaxCommandLineLength())
 568             {
 569               throw new Exception("urllength");
 570             }
 571
 572             if (!createFullUrl)
 573             {
 574               continue; // don't bother making the URL replacement text.
 575             }
 576             // do we take the cartesian products of the substituents ?
 577             int ns = rg.numSubs();
 578             if (ns == 0)
 579             {
 580               thematches[pass].append(rg.stringMatched());// take whole regex
 581             }
 582             /*
 583              * else if (ns==1) { // take only subgroup match return new String[]
 584              * { rg.stringMatched(1), url_prefix+rg.stringMatched(1)+url_suffix
 585              * }; }
 586              */
 587             // deal with multiple submatch case - for moment we do the simplest
 588             // - concatenate the matched regions, instead of creating a complete
 589             // list for each alternate match over all sequences.
 590             // TODO: specify a 'replace pattern' - next refinement
 591             else
 592             {
 593               // debug
 594               /*
 595                * for (int s = 0; s <= rg.numSubs(); s++) {
 596                * System.err.println("Sub " + s + " : " + rg.matchedFrom(s) +
 597                * " : " + rg.matchedTo(s) + " : '" + rg.stringMatched(s) + "'");
 598                * }
 599                */
 600               // try to collate subgroup matches
 601               StringBuffer subs = new StringBuffer();
 602               // have to loop through submatches, collating them at top level
 603               // match
 604               int s = 0; // 1;
 605               while (s <= ns)
 606               {
 607                 if (s + 1 <= ns && rg.matchedTo(s) > -1
 608                         && rg.matchedTo(s + 1) > -1
 609                         && rg.matchedTo(s + 1) < rg.matchedTo(s))
 610                 {
 611                   // s is top level submatch. search for submatches enclosed by
 612                   // this one
 613                   int r = s + 1;
 614                   StringBuffer rmtch = new StringBuffer();
 615                   while (r <= ns && rg.matchedTo(r) <= rg.matchedTo(s))
 616                   {
 617                     if (rg.matchedFrom(r) > -1)
 618                     {
 619                       rmtch.append(rg.stringMatched(r));
 620                     }
 621                     r++;
 622                   }
 623                   if (rmtch.length() > 0)
 624                   {
 625                     subs.append(rmtch); // simply concatenate
 626                   }
 627                   s = r;
 628                 }
 629                 else
 630                 {
 631                   if (rg.matchedFrom(s) > -1)
 632                   {
 633                     subs.append(rg.stringMatched(s)); // concatenate
 634                   }
 635                   s++;
 636                 }
 637               }
 638               thematches[pass].append(subs);
 639             }
 640           }
 641         }
 642         else
 643         {
 644           // are we only supposed to take regex matches ?
 645           if (!onlyIfMatches)
 646           {
 647             thismatched[sq] |= true;
 648             urllength += idseq[pass][sq].length(); // tot up length
 649             if (createFullUrl)
 650             {
 651               thematches[pass] = new StringBuffer(idseq[pass][sq]); // take
 652                                                                     // whole
 653                                                                     // string -
 654               // regardless - probably not a
 655               // good idea!
 656               /*
 657                * TODO: do some boilerplate trimming of the fields to make them
 658                * sensible e.g. trim off any 'prefix' in the id string (see
 659                * UrlLink for the below) - pre 2.4 Jalview behaviour if
 660                * (idstring.indexOf("|") > -1) { idstring =
 661                * idstring.substring(idstring.lastIndexOf("|") + 1); }
 662                */
 663             }
 664
 665           }
 666         }
 667       }
 668
 669       // check if we are going to add this sequence's results ? all token
 670       // replacements must be valid for this to happen!
 671       // (including single value replacements - eg. dataset name)
 672       if (thismatched[sq])
 673       {
 674         if (createFullUrl)
 675         {
 676           for (pass = 0; pass < matched.length; pass++)
 677           {
 678             if (idseq[pass].length > 1 && matched[pass].length() > 0)
 679             {
 680               matched[pass].append(separators[pass]);
 681             }
 682             matched[pass].append(thematches[pass]);
 683           }
 684         }
 685         seqsmatched++;
 686       }
 687     }
 688     // finally, if any sequences matched, then form the URL and return
 689     if (seqsmatched == 0 || (createFullUrl && matched[0].length() == 0))
 690     {
 691       // no matches - no url generated
 692       return null;
 693     }
 694     // check if we are beyond the feasible command line string limit for this
 695     // platform
 696     if ((urllength + 32) > Platform.getMaxCommandLineLength())
 697     {
 698       throw new Exception("urllength");
 699     }
 700     if (!createFullUrl)
 701     {
 702       // just return the essential info about what the URL would be generated
 703       // from
 704       return new Object[]
 705       { new int[]
 706       { seqsmatched }, thismatched };
 707     }
 708     // otherwise, create the URL completely.
 709
 710     StringBuffer submiturl = new StringBuffer();
 711     submiturl.append(url_prefix);
 712     for (pass = 0; pass < matched.length; pass++)
 713     {
 714       submiturl.append(matched[pass]);
 715       if (url_suffix[pass] != null)
 716       {
 717         submiturl.append(url_suffix[pass]);
 718       }
 719     }
 720
 721     return new Object[]
 722     { new int[]
 723     { seqsmatched }, thismatched, matched, new String[]
 724     { submiturl.toString() } };
 725   }
 726
 727   /**
 728    *
 729    * @param urlstub
 730    * @return number of distinct sequence (id or seuqence) replacements predicted
 731    *         for this stub
 732    */
 733   public int getNumberInvolved(Object[] urlstub)
 734   {
 735     return ((int[]) urlstub[0])[0]; // returns seqsmatched from
 736                                     // makeUrlsIf(false,...)
 737   }
 738
 739   /**
 740    * get token types present in this url as a bitfield indicating presence of
 741    * each token from tokens (LSB->MSB).
 742    *
 743    * @return groupURL class as integer
 744    */
 745   public int getGroupURLType()
 746   {
 747     int r = 0;
 748     for (int pass = 0; pass < tokens.length; pass++)
 749     {
 750       for (int i = 0; i < mtch.length; i++)
 751       {
 752         if (mtch[i].equals(tokens[pass]))
 753         {
 754           r += 1 << pass;
 755         }
 756       }
 757     }
 758     return r;
 759   }
 760
 761   public String toString()
 762   {
 763     StringBuffer result = new StringBuffer();
 764     result.append(label + "|" + url_prefix);
 765     int r;
 766     for (r = 0; r < url_suffix.length; r++)
 767     {
 768       result.append("$");
 769       result.append(mtch[r]);
 770       if (regexReplace[r] != null)
 771       {
 772         result.append("=/");
 773         result.append(regexReplace[r]);
 774         result.append("/=");
 775       }
 776       result.append("$");
 777       result.append(url_suffix[r]);
 778     }
 779     for (r = 0; r < separators.length; r++)
 780     {
 781       result.append("|");
 782       result.append(separators[r]);
 783     }
 784     return result.toString();
 785   }
 786
 787   /**
 788    * report stats about the generated url string given an input set
 789    *
 790    * @param ul
 791    * @param idstring
 792    * @param url
 793    */
 794   private static void testUrls(RestServiceDescription
 795           ul, String[][] idstring,
 796           Object[] url)
 797   {
 798
 799     if (url == null)
 800     {
 801       System.out.println("Created NO urls.");
 802     }
 803     else
 804     {
 805       System.out.println("Created a url from " + ((int[]) url[0])[0]
 806               + "out of " + idstring[0].length + " sequences.");
 807       System.out.println("Sequences that did not match:");
 808       for (int sq = 0; sq < idstring[0].length; sq++)
 809       {
 810         if (!((boolean[]) url[1])[sq])
 811         {
 812           System.out.println("Seq " + sq + ": " + idstring[0][sq] + "\t: "
 813                   + idstring[1][sq]);
 814         }
 815       }
 816       System.out.println("Sequences that DID match:");
 817       for (int sq = 0; sq < idstring[0].length; sq++)
 818       {
 819         if (((boolean[]) url[1])[sq])
 820         {
 821           System.out.println("Seq " + sq + ": " + idstring[0][sq] + "\t: "
 822                   + idstring[1][sq]);
 823         }
 824       }
 825       System.out.println("The generated URL:");
 826       System.out.println(((String[]) url[3])[0]);
 827     }
 828   }
 829
 830   public static void main(String argv[])
 831   {
 832   }
 833
 834   /**
 835    * covenience method to generate the id and sequence string vector from a set
 836    * of seuqences using each sequence's getName() and getSequenceAsString()
 837    * method
 838    *
 839    * @param seqs
 840    * @return String[][] {{sequence ids},{sequence strings}}
 841    */
 842   public static String[][] formStrings(SequenceI[] seqs)
 843   {
 844     String[][] idset = new String[2][seqs.length];
 845     for (int i = 0; i < seqs.length; i++)
 846     {
 847       idset[0][i] = seqs[i].getName();
 848       idset[1][i] = seqs[i].getSequenceAsString();
 849     }
 850     return idset;
 851   }
 852
 853   public void setLabel(String newlabel)
 854   {
 855     this.label = newlabel;
 856   }
 857
 858   /**
 859    * can this service be run on the visible portion of an alignment regardless of hidden boundaries ?
 860    */
 861   boolean hseparable=false;
 862   boolean vseparable=false;
 863
 864   public boolean isHseparable()
 865   {
 866     // TODO Auto-generated method stub
 867     return hseparable;
 868   }
 869   /**
 870    *
 871    * @return
 872    */
 873   public boolean isVseparable()
 874   {
 875     // TODO Auto-generated method stub
 876     return hseparable;
 877   }
 878
 879   /**
 880    * search the input types for an instance of the given class
 881    * @param <validInput.inputType> class1
 882    * @return
 883    */
 884   public boolean inputInvolves(Class<?> class1)
 885   {
 886     assert(InputType.class.isAssignableFrom(class1));
 887     for (InputType val:inputParams.values())
 888     {
 889       if (class1.isAssignableFrom(val.getClass()))
 890       {
 891         return true;
 892       }
 893     }
 894     return false;
 895   }
 896   char gapCharacter = '-';
 897   /**
 898    *
 899    * @return the preferred gap character for alignments input/output by this service
 900    */
 901   public char getGapCharacter()
 902   {
 903     return gapCharacter;
 904   }
 905
 906   public String getDecoratedResultUrl(String jobId)
 907   {
 908     // TODO: correctly write ?/& appropriate to result URL format.
 909     return jobId+urlSuffix;
 910   }
 911 }