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
5 * This file is part of Jalview.
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.
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.
16 * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.
18 package jalview.ws.rest;
21 import jalview.datamodel.SequenceI;
22 import jalview.io.packed.DataProvider;
23 import jalview.io.packed.SimpleDataProvider;
24 import jalview.io.packed.DataProvider.JvDataType;
25 import jalview.util.GroupUrlLink.UrlStringTooLongException;
26 import jalview.util.Platform;
27 import jalview.ws.rest.params.Alignment;
28 import jalview.ws.rest.params.AnnotationFile;
29 import jalview.ws.rest.params.SeqGroupIndexVector;
31 import java.util.ArrayList;
32 import java.util.HashMap;
33 import java.util.Hashtable;
34 import java.util.List;
38 public class RestServiceDescription
49 public RestServiceDescription(String action,String description,String name, String postUrl,
50 String urlSuffix, Map<String, InputType> inputParams,
51 boolean hseparable, boolean vseparable, char gapCharacter)
54 this.details = new UIinfo();
55 details.Action= action;
56 details.description = description;
58 this.postUrl = postUrl;
59 this.urlSuffix = urlSuffix;
60 this.inputParams = inputParams;
61 this.hseparable = hseparable;
62 this.vseparable = vseparable;
63 this.gapCharacter = gapCharacter;
66 * Service UI Info { Action, Specific Name of Service, Brief Description }
74 UIinfo details = new UIinfo();
80 * suffix that should be added to any url used if it does not already end in the suffix.
84 /** input info given as key/value pairs - mapped to post arguments
86 Map<String,InputType> inputParams=new HashMap();
88 * assigns the given inputType it to its corresponding input parameter token it.token
91 public void setInputParam(InputType it)
93 inputParams.put(it.token, it);
96 * remove the given input type it from the set of service input parameters.
99 public void removeInputParam(InputType it)
101 inputParams.remove(it.token);
104 * service requests alignment data
108 * service requests alignment and/or seuqence annotationo data
112 * service requests partitions defined over input (alignment) data
114 boolean partitiondata;
117 * process ths input data and set the appropriate shorthand flags describing the input the service wants
119 public void setInvolvesFlags() {
120 aligndata = inputInvolves(Alignment.class);
121 annotdata = inputInvolves(AnnotationFile.class);
122 partitiondata = inputInvolves(SeqGroupIndexVector.class);
125 /** 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 )
129 /** Start with bare minimum: input is alignment + groups on alignment
136 * Helper class based on the UrlLink class which enables URLs to be
137 * constructed from sequences or IDs associated with a group of sequences. URL
138 * definitions consist of a pipe separated string containing a <label>|<url
139 * construct>|<separator character>[|<sequence separator character>]. The url
140 * construct includes regex qualified tokens which are replaced with seuqence
141 * IDs ($SEQUENCE_IDS$) and/or seuqence regions ($SEQUENCES$) that are
142 * extracted from the group. See <code>UrlLink</code> for more information
143 * about the approach, and the original implementation. Documentation to come.
144 * Note - groupUrls can be very big!
146 private String url_prefix, target, label;
149 * these are all filled in order of the occurence of each token in the url
152 private String url_suffix[], separators[], regexReplace[];
154 private String invalidMessage = null;
157 * tokens that can be replaced in the URL.
159 private static String[] tokens;
162 * position of each token (which can appear once only) in the url
167 * contains tokens in the order they appear in the URL template.
169 private String[] mtch;
174 tokens = new String[]
175 { "SEQUENCEIDS", "SEQUENCES", "DATASETID" };
180 * test for GroupURLType bitfield (with default tokens)
182 public static final int SEQUENCEIDS = 1;
185 * test for GroupURLType bitfield (with default tokens)
187 public static final int SEQUENCES = 2;
190 * test for GroupURLType bitfield (with default tokens)
192 public static final int DATASETID = 4;
194 // private int idseg = -1, seqseg = -1;
197 * parse the given linkString of the form '<label>|<url>|separator
198 * char[|optional sequence separator char]' into parts. url may contain a
199 * string $SEQUENCEIDS<=optional regex=>$ where <=optional regex=> must be of
200 * the form =/<perl style regex>/=$ or $SEQUENCES<=optional regex=>$ or
201 * $SEQUENCES<=optional regex=>$.
205 public RestServiceDescription(String link)
207 int sep = link.indexOf("|");
208 segs = new int[tokens.length];
210 for (int i = 0; i < segs.length; i++)
212 if ((segs[i] = link.indexOf("$" + tokens[i])) > -1)
217 // expect at least one token
220 invalidMessage = "Group URL string must contain at least one of ";
221 for (int i = 0; i < segs.length; i++)
223 invalidMessage += " '$" + tokens[i] + "[=/regex=/]$'";
228 int[] ptok = new int[ntoks + 1];
229 String[] tmtch = new String[ntoks + 1];
230 mtch = new String[ntoks];
231 for (int i = 0, t = 0; i < segs.length; i++)
236 tmtch[t++] = tokens[i];
239 ptok[ntoks] = link.length();
240 tmtch[ntoks] = "$$$$$$$$$";
241 jalview.util.QuickSort.sort(ptok, tmtch);
242 for (int i = 0; i < ntoks; i++)
244 mtch[i] = tmtch[i]; // TODO: check order is ascending
247 * replaces the specific code below {}; if (psqids > -1 && pseqs > -1) { if
248 * (psqids > pseqs) { idseg = 1; seqseg = 0;
250 * ptok = new int[] { pseqs, psqids, link.length() }; mtch = new String[] {
251 * "$SEQUENCES", "$SEQUENCEIDS" }; } else { idseg = 0; seqseg = 1; ptok =
252 * new int[] { psqids, pseqs, link.length() }; mtch = new String[] {
253 * "$SEQUENCEIDS", "$SEQUENCES" }; } } else { if (psqids != -1) { idseg = 0;
254 * ptok = new int[] { psqids, link.length() }; mtch = new String[] {
255 * "$SEQUENCEIDS" }; } else { seqseg = 0; ptok = new int[] { pseqs,
256 * link.length() }; mtch = new String[] { "$SEQUENCES" }; } }
260 // first get the label and target part before the first |
264 p = link.indexOf("|", sep + 1);
265 } while (p > sep && p < ptok[0]);
266 // Assuming that the URL itself does not contain any '|' symbols
267 // sep now contains last pipe symbol position prior to any regex symbols
268 label = link.substring(0, sep);
269 if (label.indexOf("|") > -1)
271 // | terminated database name / www target at start of Label
272 target = label.substring(0, label.indexOf("|"));
274 else if (label.indexOf(" ") > 2)
276 // space separated Label - matches database name
277 target = label.substring(0, label.indexOf(" "));
283 // Now Parse URL : Whole URL string first
284 url_prefix = link.substring(sep + 1, ptok[0]);
285 url_suffix = new String[mtch.length];
286 regexReplace = new String[mtch.length];
287 // and loop through tokens
288 for (int pass = 0; pass < mtch.length; pass++)
290 int mlength = 3 + mtch[pass].length();
291 if (link.indexOf("$" + mtch[pass] + "=/") == ptok[pass]
292 && (p = link.indexOf("/=$", ptok[pass] + mlength)) > ptok[pass]
295 // Extract Regex and suffix
296 if (ptok[pass + 1] < p + 3)
298 // tokens are not allowed inside other tokens - e.g. inserting a
299 // $sequences$ into the regex match for the sequenceid
300 invalidMessage = "Token regexes cannot contain other regexes (did you terminate the $"
301 + mtch[pass] + " regex with a '/=$' ?";
304 url_suffix[pass] = link.substring(p + 3, ptok[pass + 1]);
305 regexReplace[pass] = link.substring(ptok[pass] + mlength, p);
308 com.stevesoft.pat.Regex rg = com.stevesoft.pat.Regex.perlCode("/"
309 + regexReplace[pass] + "/");
312 invalidMessage = "Invalid Regular Expression : '"
313 + regexReplace[pass] + "'\n";
315 } catch (Exception e)
317 invalidMessage = "Invalid Regular Expression : '"
318 + regexReplace[pass] + "'\n";
323 regexReplace[pass] = null;
324 // verify format is really correct.
325 if ((p = link.indexOf("$" + mtch[pass] + "$")) == ptok[pass])
327 url_suffix[pass] = link.substring(p + mtch[pass].length() + 2,
332 invalidMessage = "Warning: invalid regex structure (after '"
333 + mtch[0] + "') for URL link : " + link;
338 separators = new String[url_suffix.length];
339 String suffices = url_suffix[url_suffix.length - 1], lastsep = ",";
340 // have a look in the last suffix for any more separators.
341 while ((p = suffices.indexOf('|')) > -1)
343 separators[pass] = suffices.substring(p + 1);
346 // trim the original suffix string
347 url_suffix[url_suffix.length - 1] = suffices.substring(0, p);
351 lastsep = (separators[pass - 1] = separators[pass - 1].substring(0,
354 suffices = separators[pass];
359 lastsep = separators[pass - 1];
361 // last separator is always used for all the remaining separators
362 while (pass < separators.length)
364 separators[pass++] = lastsep;
369 * @return the url_suffix
371 public String getUrl_suffix()
373 return url_suffix[url_suffix.length - 1];
377 * @return the url_prefix
379 public String getUrl_prefix()
387 public String getTarget()
395 public String getLabel()
401 * @return the sequence ID regexReplace
403 public String getIDRegexReplace()
405 return _replaceFor(tokens[0]);
408 private String _replaceFor(String token)
410 for (int i = 0; i < mtch.length; i++)
411 if (segs[i] > -1 && mtch[i].equals(token))
413 return regexReplace[i];
419 * @return the sequence ID regexReplace
421 public String getSeqRegexReplace()
423 return _replaceFor(tokens[1]);
427 * @return the invalidMessage
429 public String getInvalidMessage()
431 return invalidMessage;
435 * Check if URL string was parsed properly.
437 * @return boolean - if false then <code>getInvalidMessage</code> returns an
440 public boolean isValid()
442 return invalidMessage == null;
447 * gathers input into a hashtable
454 private Hashtable replacementArgs(String[] idstrings,
455 String[] seqstrings, String dsstring)
457 Hashtable rstrings = new Hashtable();
458 rstrings.put(tokens[0], idstrings);
459 rstrings.put(tokens[1], seqstrings);
460 rstrings.put(tokens[2], new String[]
462 if (idstrings.length != seqstrings.length)
465 "idstrings and seqstrings contain one string each per sequence.");
474 * conditionally generate urls or stubs for a given input.
476 * @param createFullUrl
477 * set to false if you only want to test if URLs would be generated.
479 * @param onlyIfMatches
480 * @return null if no url is generated. Object[] { int[] { number of matches
481 * seqs }, boolean[] { which matched }, (if createFullUrl also has
482 * StringBuffer[] { segment generated from inputs that is used in URL
483 * }, String[] { url })}
485 * @throws UrlStringTooLongException
487 protected Object[] makeUrlsIf(boolean createFullUrl,
488 Hashtable repstrings, boolean onlyIfMatches) throws Exception
492 // prepare string arrays in correct order to be assembled into URL input
493 String[][] idseq = new String[mtch.length][]; // indexed by pass
494 int mins = 0, maxs = 0; // allowed two values, 1 or n-sequences.
495 for (int i = 0; i < mtch.length; i++)
497 idseq[i] = (String[]) repstrings.get(mtch[i]);
498 if (idseq[i].length >= 1)
500 if (mins == 0 && idseq[i].length == 1)
506 maxs = idseq[i].length;
510 if (maxs != idseq[i].length)
513 "Cannot have mixed length replacement vectors. Replacement vector for "
514 + (mtch[i]) + " is " + idseq[i].length
515 + " strings long, and have already seen a "
516 + maxs + " length vector.");
523 "Cannot have zero length vector of replacement strings - either 1 value or n values.");
526 // iterate through input, collating segments to be inserted into url
527 StringBuffer matched[] = new StringBuffer[idseq.length];
528 // and precompile regexes
529 com.stevesoft.pat.Regex[] rgxs = new com.stevesoft.pat.Regex[matched.length];
530 for (pass = 0; pass < matched.length; pass++)
532 matched[pass] = new StringBuffer();
533 if (regexReplace[pass] != null)
535 rgxs[pass] = com.stevesoft.pat.Regex.perlCode("/"
536 + regexReplace[pass] + "/");
543 // tot up the invariant lengths for this url
544 int urllength = url_prefix.length();
545 for (pass = 0; pass < matched.length; pass++)
547 urllength += url_suffix[pass].length();
550 // flags to record which of the input sequences were actually used to
553 boolean[] thismatched = new boolean[maxs];
555 for (int sq = 0; sq < maxs; sq++)
557 // initialise flag for match
558 thismatched[sq] = false;
559 StringBuffer[] thematches = new StringBuffer[rgxs.length];
560 for (pass = 0; pass < rgxs.length; pass++)
562 thematches[pass] = new StringBuffer(); // initialise - in case there are
565 // if a regex is provided, then it must match for all sequences in all
566 // tokens for it to be considered.
567 if (idseq[pass].length <= sq)
569 // no more replacement strings to try for this token
572 if (rgxs[pass] != null)
574 com.stevesoft.pat.Regex rg = rgxs[pass];
576 // concatenate all matches of re in the given string!
577 while (rg.searchFrom(idseq[pass][sq], rematchat))
579 rematchat = rg.matchedTo();
580 thismatched[sq] |= true;
581 urllength += rg.charsMatched(); // count length
582 if ((urllength + 32) > Platform.getMaxCommandLineLength())
584 throw new Exception("urllength");
589 continue; // don't bother making the URL replacement text.
591 // do we take the cartesian products of the substituents ?
592 int ns = rg.numSubs();
595 thematches[pass].append(rg.stringMatched());// take whole regex
598 * else if (ns==1) { // take only subgroup match return new String[]
599 * { rg.stringMatched(1), url_prefix+rg.stringMatched(1)+url_suffix
602 // deal with multiple submatch case - for moment we do the simplest
603 // - concatenate the matched regions, instead of creating a complete
604 // list for each alternate match over all sequences.
605 // TODO: specify a 'replace pattern' - next refinement
610 * for (int s = 0; s <= rg.numSubs(); s++) {
611 * System.err.println("Sub " + s + " : " + rg.matchedFrom(s) +
612 * " : " + rg.matchedTo(s) + " : '" + rg.stringMatched(s) + "'");
615 // try to collate subgroup matches
616 StringBuffer subs = new StringBuffer();
617 // have to loop through submatches, collating them at top level
622 if (s + 1 <= ns && rg.matchedTo(s) > -1
623 && rg.matchedTo(s + 1) > -1
624 && rg.matchedTo(s + 1) < rg.matchedTo(s))
626 // s is top level submatch. search for submatches enclosed by
629 StringBuffer rmtch = new StringBuffer();
630 while (r <= ns && rg.matchedTo(r) <= rg.matchedTo(s))
632 if (rg.matchedFrom(r) > -1)
634 rmtch.append(rg.stringMatched(r));
638 if (rmtch.length() > 0)
640 subs.append(rmtch); // simply concatenate
646 if (rg.matchedFrom(s) > -1)
648 subs.append(rg.stringMatched(s)); // concatenate
653 thematches[pass].append(subs);
659 // are we only supposed to take regex matches ?
662 thismatched[sq] |= true;
663 urllength += idseq[pass][sq].length(); // tot up length
666 thematches[pass] = new StringBuffer(idseq[pass][sq]); // take
669 // regardless - probably not a
672 * TODO: do some boilerplate trimming of the fields to make them
673 * sensible e.g. trim off any 'prefix' in the id string (see
674 * UrlLink for the below) - pre 2.4 Jalview behaviour if
675 * (idstring.indexOf("|") > -1) { idstring =
676 * idstring.substring(idstring.lastIndexOf("|") + 1); }
684 // check if we are going to add this sequence's results ? all token
685 // replacements must be valid for this to happen!
686 // (including single value replacements - eg. dataset name)
691 for (pass = 0; pass < matched.length; pass++)
693 if (idseq[pass].length > 1 && matched[pass].length() > 0)
695 matched[pass].append(separators[pass]);
697 matched[pass].append(thematches[pass]);
703 // finally, if any sequences matched, then form the URL and return
704 if (seqsmatched == 0 || (createFullUrl && matched[0].length() == 0))
706 // no matches - no url generated
709 // check if we are beyond the feasible command line string limit for this
711 if ((urllength + 32) > Platform.getMaxCommandLineLength())
713 throw new Exception("urllength");
717 // just return the essential info about what the URL would be generated
721 { seqsmatched }, thismatched };
723 // otherwise, create the URL completely.
725 StringBuffer submiturl = new StringBuffer();
726 submiturl.append(url_prefix);
727 for (pass = 0; pass < matched.length; pass++)
729 submiturl.append(matched[pass]);
730 if (url_suffix[pass] != null)
732 submiturl.append(url_suffix[pass]);
738 { seqsmatched }, thismatched, matched, new String[]
739 { submiturl.toString() } };
745 * @return number of distinct sequence (id or seuqence) replacements predicted
748 public int getNumberInvolved(Object[] urlstub)
750 return ((int[]) urlstub[0])[0]; // returns seqsmatched from
751 // makeUrlsIf(false,...)
755 * get token types present in this url as a bitfield indicating presence of
756 * each token from tokens (LSB->MSB).
758 * @return groupURL class as integer
760 public int getGroupURLType()
763 for (int pass = 0; pass < tokens.length; pass++)
765 for (int i = 0; i < mtch.length; i++)
767 if (mtch[i].equals(tokens[pass]))
776 public String toString()
778 StringBuffer result = new StringBuffer();
779 result.append(label + "|" + url_prefix);
781 for (r = 0; r < url_suffix.length; r++)
784 result.append(mtch[r]);
785 if (regexReplace[r] != null)
788 result.append(regexReplace[r]);
792 result.append(url_suffix[r]);
794 for (r = 0; r < separators.length; r++)
797 result.append(separators[r]);
799 return result.toString();
803 * report stats about the generated url string given an input set
809 private static void testUrls(RestServiceDescription
810 ul, String[][] idstring,
816 System.out.println("Created NO urls.");
820 System.out.println("Created a url from " + ((int[]) url[0])[0]
821 + "out of " + idstring[0].length + " sequences.");
822 System.out.println("Sequences that did not match:");
823 for (int sq = 0; sq < idstring[0].length; sq++)
825 if (!((boolean[]) url[1])[sq])
827 System.out.println("Seq " + sq + ": " + idstring[0][sq] + "\t: "
831 System.out.println("Sequences that DID match:");
832 for (int sq = 0; sq < idstring[0].length; sq++)
834 if (((boolean[]) url[1])[sq])
836 System.out.println("Seq " + sq + ": " + idstring[0][sq] + "\t: "
840 System.out.println("The generated URL:");
841 System.out.println(((String[]) url[3])[0]);
845 public static void main(String argv[])
850 * covenience method to generate the id and sequence string vector from a set
851 * of seuqences using each sequence's getName() and getSequenceAsString()
855 * @return String[][] {{sequence ids},{sequence strings}}
857 public static String[][] formStrings(SequenceI[] seqs)
859 String[][] idset = new String[2][seqs.length];
860 for (int i = 0; i < seqs.length; i++)
862 idset[0][i] = seqs[i].getName();
863 idset[1][i] = seqs[i].getSequenceAsString();
868 public void setLabel(String newlabel)
870 this.label = newlabel;
874 * can this service be run on the visible portion of an alignment regardless of hidden boundaries ?
876 boolean hseparable=false;
877 boolean vseparable=false;
879 public boolean isHseparable()
881 // TODO Auto-generated method stub
888 public boolean isVseparable()
890 // TODO Auto-generated method stub
895 * search the input types for an instance of the given class
896 * @param <validInput.inputType> class1
899 public boolean inputInvolves(Class<?> class1)
901 assert(InputType.class.isAssignableFrom(class1));
902 for (InputType val:inputParams.values())
904 if (class1.isAssignableFrom(val.getClass()))
911 char gapCharacter = '-';
914 * @return the preferred gap character for alignments input/output by this service
916 public char getGapCharacter()
921 public String getDecoratedResultUrl(String jobId)
923 // TODO: correctly write ?/& appropriate to result URL format.
924 return jobId+urlSuffix;
926 private List<JvDataType> resultData;
930 * TODO: Extend to optionally specify relative/absolute url where data of this type can be retrieved from
933 public void addResultDatatype(JvDataType dt)
935 if (resultData==null)
937 resultData = new ArrayList<JvDataType>();
941 public boolean removeRsultDatatype(JvDataType dt)
943 if (resultData!=null)
945 return resultData.remove(dt);
949 public List<JvDataType> getResultDataTypes()