2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.7)
3 * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, 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;
20 import jalview.datamodel.SequenceI;
21 import jalview.io.packed.DataProvider;
22 import jalview.io.packed.SimpleDataProvider;
23 import jalview.io.packed.DataProvider.JvDataType;
24 import jalview.util.GroupUrlLink.UrlStringTooLongException;
25 import jalview.util.Platform;
26 import jalview.ws.rest.params.Alignment;
27 import jalview.ws.rest.params.AnnotationFile;
28 import jalview.ws.rest.params.JobConstant;
29 import jalview.ws.rest.params.SeqGroupIndexVector;
32 import java.util.ArrayList;
33 import java.util.HashMap;
34 import java.util.Hashtable;
35 import java.util.List;
37 import java.util.NoSuchElementException;
38 import java.util.StringTokenizer;
39 import java.util.Vector;
40 import java.util.regex.Matcher;
41 import java.util.regex.Pattern;
43 import javax.swing.JViewport;
45 import com.stevesoft.pat.Regex;
46 import com.sun.org.apache.xml.internal.serialize.OutputFormat.DTD;
48 public class RestServiceDescription
51 * create a new rest service description ready to be configured
53 public RestServiceDescription()
67 public RestServiceDescription(String action, String description,
68 String name, String postUrl, String urlSuffix,
69 Map<String, InputType> inputParams, boolean hseparable,
70 boolean vseparable, char gapCharacter)
73 this.details = new UIinfo();
74 details.Action = action == null ? "" : action;
75 details.description = description == null ? "" : description;
76 details.Name = name == null ? "" : name;
77 this.postUrl = postUrl == null ? "" : postUrl;
78 this.urlSuffix = urlSuffix == null ? "" : urlSuffix;
79 if (inputParams != null)
81 this.inputParams = inputParams;
83 this.hseparable = hseparable;
84 this.vseparable = vseparable;
85 this.gapCharacter = gapCharacter;
88 public boolean equals(Object o)
90 if (o == null || !(o instanceof RestServiceDescription))
94 RestServiceDescription other = (RestServiceDescription) o;
95 boolean diff = (gapCharacter != other.gapCharacter);
96 diff |= vseparable != other.vseparable;
97 diff |= hseparable != other.hseparable;
98 diff |= !(urlSuffix.equals(other.urlSuffix));
99 // TODO - robust diff that includes constants and reordering of URL
100 // diff |= !(postUrl.equals(other.postUrl));
101 // diff |= !inputParams.equals(other.inputParams);
102 diff |= !details.Name.equals(other.details.Name);
103 diff |= !details.Action.equals(other.details.Action);
104 diff |= !details.description.equals(other.details.description);
109 * Service UI Info { Action, Specific Name of Service, Brief Description }
114 public String getAction()
119 public void setAction(String action)
124 public String getName()
129 public void setName(String name)
134 public String getDescription()
139 public void setDescription(String description)
141 this.description = description;
151 public UIinfo details = new UIinfo();
153 public String getAction()
155 return details.getAction();
158 public void setAction(String action)
160 details.setAction(action);
163 public String getName()
165 return details.getName();
168 public void setName(String name)
170 details.setName(name);
173 public String getDescription()
175 return details.getDescription();
178 public void setDescription(String description)
180 details.setDescription(description);
188 public String getPostUrl()
193 public void setPostUrl(String postUrl)
195 this.postUrl = postUrl;
198 public String getUrlSuffix()
203 public void setUrlSuffix(String urlSuffix)
205 this.urlSuffix = urlSuffix;
208 public Map<String, InputType> getInputParams()
213 public void setInputParams(Map<String, InputType> inputParams)
215 this.inputParams = inputParams;
218 public void setHseparable(boolean hseparable)
220 this.hseparable = hseparable;
223 public void setVseparable(boolean vseparable)
225 this.vseparable = vseparable;
228 public void setGapCharacter(char gapCharacter)
230 this.gapCharacter = gapCharacter;
234 * suffix that should be added to any url used if it does not already end in
240 * input info given as key/value pairs - mapped to post arguments
242 Map<String, InputType> inputParams = new HashMap<String, InputType>();
245 * assigns the given inputType it to its corresponding input parameter token
250 public void setInputParam(InputType it)
252 inputParams.put(it.token, it);
256 * remove the given input type it from the set of service input parameters.
260 public void removeInputParam(InputType it)
262 inputParams.remove(it.token);
266 * service requests alignment data
271 * service requests alignment and/or seuqence annotationo data
276 * service requests partitions defined over input (alignment) data
278 boolean partitiondata;
281 * process ths input data and set the appropriate shorthand flags describing
282 * the input the service wants
284 public void setInvolvesFlags()
286 aligndata = inputInvolves(Alignment.class);
287 annotdata = inputInvolves(AnnotationFile.class);
288 partitiondata = inputInvolves(SeqGroupIndexVector.class);
292 * Service return info { alignment, annotation file (loaded back on to
293 * alignment), tree (loaded back on to alignment), sequence annotation -
294 * loaded back on to alignment), text report, pdb structures with sequence
300 * Start with bare minimum: input is alignment + groups on alignment
306 private String invalidMessage = null;
309 * parse the given linkString of the form '<label>|<url>|separator
310 * char[|optional sequence separator char]' into parts. url may contain a
311 * string $SEQUENCEIDS<=optional regex=>$ where <=optional regex=> must be of
312 * the form =/<perl style regex>/=$ or $SEQUENCES<=optional regex=>$ or
313 * $SEQUENCES<=optional regex=>$.
317 public RestServiceDescription(String link)
319 StringBuffer warnings = new StringBuffer();
320 if (!configureFromEncodedString(link, warnings))
322 if (warnings.length() > 0)
324 invalidMessage = warnings.toString();
329 public RestServiceDescription(RestServiceDescription toedit)
331 // Rather then do the above, we cheat and use our human readable
332 // serialization code to clone everything
333 this(toedit.toString());
335 * if (toedit == null) { return; } /** urlSuffix = toedit.urlSuffix; postUrl
336 * = toedit.postUrl; hseparable = toedit.hseparable; vseparable =
337 * toedit.vseparable; gapCharacter = toedit.gapCharacter; details = new
338 * RestServiceDescription.UIinfo(); details.Action = toedit.details.Action;
339 * details.description = toedit.details.description; details.Name =
340 * toedit.details.Name; for (InputType itype: toedit.inputParams.values()) {
341 * inputParams.put(itype.token, itype.clone());
345 // TODO Implement copy constructor NOW*/
349 * @return the invalidMessage
351 public String getInvalidMessage()
353 return invalidMessage;
357 * Check if URL string was parsed properly.
359 * @return boolean - if false then <code>getInvalidMessage</code> returns an
362 public boolean isValid()
364 return invalidMessage == null;
367 private static boolean debug = false;
370 * parse the string into a list
374 * @return elements separated by separator
376 public static String[] separatorListToArray(String list, String separator)
378 int seplen = separator.length();
379 if (list == null || list.equals("") || list.equals(separator))
381 java.util.ArrayList<String> jv = new ArrayList<String>();
382 int cp = 0, pos, escape;
383 boolean wasescaped = false, wasquoted = false;
384 String lstitem = null;
385 while ((pos = list.indexOf(separator, cp)) >= cp)
388 escape = (pos > 0 && list.charAt(pos - 1) == '\\') ? -1 : 0;
389 if (wasescaped || wasquoted)
391 // append to previous pos
392 jv.set(jv.size() - 1,
393 lstitem = lstitem + separator
394 + list.substring(cp, pos + escape));
399 jv.add(lstitem = list.substring(cp, pos + escape));
402 wasescaped = escape == -1;
405 // last separator may be in an unmatched quote
406 if (java.util.regex.Pattern.matches("('[^']*')*[^']*'", lstitem))
413 if (cp < list.length())
415 String c = list.substring(cp);
416 if (wasescaped || wasquoted)
418 // append final separator
419 jv.set(jv.size() - 1, lstitem + separator + c);
423 if (!c.equals(separator))
431 String[] v = jv.toArray(new String[jv.size()]);
435 System.err.println("Array from '" + separator
436 + "' separated List:\n" + v.length);
437 for (int i = 0; i < v.length; i++)
439 System.err.println("item " + i + " '" + v[i] + "'");
446 System.err.println("Empty Array from '" + separator
447 + "' separated List");
453 * concatenate the list with separator
457 * @return concatenated string
459 public static String arrayToSeparatorList(String[] list, String separator)
461 StringBuffer v = new StringBuffer();
462 if (list != null && list.length > 0)
464 for (int i = 0, iSize = list.length; i < iSize; i++)
472 // TODO - escape any separator values in list[i]
478 System.err.println("Returning '" + separator
479 + "' separated List:\n");
480 System.err.println(v);
486 System.err.println("Returning empty '" + separator
487 + "' separated List\n");
489 return "" + separator;
493 * parse a string containing a list of service properties and configure the
494 * service description
497 * param warnings a StringBuffer that any warnings about invalid
498 * content will be appended to.
500 private boolean configureFromServiceInputProperties(String propList,
501 StringBuffer warnings)
503 String[] props = separatorListToArray(propList, ",");
509 boolean valid = true;
511 int l = warnings.length();
513 for (String prop : props)
515 if ((i = prop.indexOf("=")) > -1)
517 val = prop.substring(i + 1);
518 if (val.startsWith("\'") && val.endsWith("\'"))
520 val = val.substring(1, val.length() - 1);
522 prop = prop.substring(0, i);
525 if (prop.equals("hseparable"))
529 if (prop.equals("vseparable"))
533 if (prop.equals("gapCharacter"))
535 if (val == null || val.length() == 0 || val.length() > 1)
538 warnings.append((warnings.length() > 0 ? "\n" : "")
539 + ("Invalid service property: gapCharacter=' ' (single character) - was given '"
544 gapCharacter = val.charAt(0);
547 if (prop.equals("returns"))
549 _configureOutputFormatFrom(val, warnings);
552 // return true if valid is true and warning buffer was not appended to.
553 return valid && (l == warnings.length());
556 private String _genOutputFormatString()
559 if (resultData == null)
563 for (JvDataType type : resultData)
565 if (buff.length() > 0)
569 buff += type.toString();
574 private void _configureOutputFormatFrom(String outstring,
575 StringBuffer warnings)
577 if (outstring.indexOf(";") == -1)
579 // we add a token, for simplicity
580 outstring = outstring + ";";
582 StringTokenizer st = new StringTokenizer(outstring, ";");
584 resultData = new ArrayList<JvDataType>();
585 while (st.hasMoreTokens())
589 resultData.add(JvDataType.valueOf(tok = st.nextToken()));
590 } catch (NoSuchElementException x)
592 warnings.append("Invalid result type: '" + tok
593 + "' (must be one of: ");
595 for (JvDataType vl : JvDataType.values())
597 warnings.append(sep);
598 warnings.append(vl.toString());
601 warnings.append(" separated by semi-colons)\n");
606 private String getServiceIOProperties()
608 ArrayList<String> vls = new ArrayList<String>();
611 vls.add("hseparable");
616 vls.add("vseparable");
619 vls.add(new String("gapCharacter='" + gapCharacter + "'"));
620 vls.add(new String("returns='" + _genOutputFormatString() + "'"));
621 return arrayToSeparatorList(vls.toArray(new String[0]), ",");
624 public String toString()
626 StringBuffer result = new StringBuffer();
628 result.append(details.Name);
630 result.append(details.Action);
632 if (details.description != null)
634 result.append(details.description);
637 // list job input flags
639 result.append(getServiceIOProperties());
640 // list any additional cgi parameters needed for result retrieval
641 if (urlSuffix != null && urlSuffix.length() > 0)
644 result.append(urlSuffix);
647 result.append(getInputParamEncodedUrl());
648 return result.toString();
652 * processes a service encoded as a string (as generated by
653 * RestServiceDescription.toString()) Note - this will only use the first
654 * service definition encountered in the string to configure the service.
658 * - where warning messages are reported.
659 * @return true if configuration was parsed successfully.
661 public boolean configureFromEncodedString(String encoding,
662 StringBuffer warnings)
664 String[] list = separatorListToArray(encoding, "|");
666 int nextpos = parseServiceList(list, warnings, 0);
675 * processes the given list from position p, attempting to configure the
676 * service from it. Service lists are formed by concatenating individual
677 * stringified services. The first character of a stringified service is '|',
678 * enabling this, and the parser will ignore empty fields in a '|' separated
679 * list when they fall outside a service definition.
686 protected int parseServiceList(String[] list, StringBuffer warnings, int p)
688 boolean invalid = false;
689 // look for the first non-empty position - expect it to be service name
690 while (list[p] != null && list[p].trim().length() == 0)
694 details.Name = list[p];
695 details.Action = list[p + 1];
696 details.description = list[p + 2];
697 invalid |= !configureFromServiceInputProperties(list[p + 3], warnings);
698 if (list.length - p > 5 && list[p + 5] != null
699 && list[p + 5].trim().length() > 5)
701 urlSuffix = list[p + 4];
702 invalid |= !configureFromInputParamEncodedUrl(list[p + 5], warnings);
707 if (list.length - p > 4 && list[p + 4] != null
708 && list[p + 4].trim().length() > 5)
711 invalid |= !configureFromInputParamEncodedUrl(list[p + 4], warnings);
715 return invalid ? -1 : p;
719 * @return string representation of the input parameters, their type and
720 * constraints, appended to the service's base submission URL
722 private String getInputParamEncodedUrl()
724 StringBuffer url = new StringBuffer();
725 if (postUrl == null || postUrl.length() < 5)
731 char appendChar = (postUrl.indexOf("?") > -1) ? '&' : '?';
732 boolean consts = true;
735 for (Map.Entry<String, InputType> param : inputParams.entrySet())
737 List<String> vals = param.getValue().getURLEncodedParameter();
738 if (param.getValue().isConstant())
742 url.append(appendChar);
744 url.append(param.getValue().token);
745 if (vals.size() == 1)
748 url.append(vals.get(0));
756 url.append(appendChar);
758 url.append(param.getValue().token);
760 // write parameter set as $TOKENPREFIX:csv list of params$ for this
763 url.append(param.getValue().getURLtokenPrefix());
765 url.append(arrayToSeparatorList(vals.toArray(new String[0]),
772 // toggle consts and repeat until !consts is false:
773 } while (!(consts = !consts));
774 return url.toString();
778 * parse the service URL and input parameters from the given encoded URL
779 * string and configure the RestServiceDescription from it.
784 * @return true if URL parsed correctly. false means the configuration failed.
786 private boolean configureFromInputParamEncodedUrl(String ipurl,
787 StringBuffer warnings)
789 boolean valid = true;
791 String url = new String();
792 Matcher prms = Pattern.compile("([?&])([A-Za-z0-9_]+)=\\$([^$]+)\\$")
794 Map<String, InputType> iparams = new Hashtable<String, InputType>();
798 if (lastp < prms.start(0))
800 url += ipurl.substring(lastp, prms.start(0));
801 lastp = prms.end(0) + 1;
803 String sep = prms.group(1);
804 String tok = prms.group(2);
805 String iprm = prms.group(3);
806 int colon = iprm.indexOf(":");
807 String iprmparams = "";
810 iprmparams = iprm.substring(colon + 1);
811 iprm = iprm.substring(0, colon);
813 valid = parseTypeString(prms.group(0), tok, iprm, iprmparams,
820 URL u = new URL(url);
822 inputParams = iparams;
823 } catch (Exception e)
825 warnings.append("Failed to parse '" + url + "' as a URL.\n");
832 public static Class[] getInputTypes()
834 // TODO - find a better way of maintaining this classlist
836 { jalview.ws.rest.params.Alignment.class,
837 jalview.ws.rest.params.AnnotationFile.class,
838 SeqGroupIndexVector.class,
839 jalview.ws.rest.params.SeqIdVector.class,
840 jalview.ws.rest.params.SeqVector.class,
841 jalview.ws.rest.params.Tree.class };
844 public static boolean parseTypeString(String fullstring, String tok,
845 String iprm, String iprmparams, Map<String, InputType> iparams,
846 StringBuffer warnings)
848 boolean valid = true;
850 for (Class type : getInputTypes())
854 jinput = (InputType) (type.getConstructor().newInstance(null));
855 if (iprm.equalsIgnoreCase(jinput.getURLtokenPrefix()))
857 ArrayList<String> al = new ArrayList<String>();
858 for (String prprm : separatorListToArray(iprmparams, ","))
860 // hack to ensure that strings like "sep=','" containing unescaped
861 // commas as values are concatenated
862 al.add(prprm.trim());
864 if (!jinput.configureFromURLtokenString(al, warnings))
867 warnings.append("Failed to parse '" + fullstring + "' as a "
868 + jinput.getURLtokenPrefix() + " input tag.\n");
873 iparams.put(tok, jinput);
879 } catch (Throwable thr)
887 public static void main(String argv[])
889 // test separator list
892 assert (separatorListToArray("foo=',',min='foo',max='1,2,3',fa=','",
894 if (separatorListToArray("minsize='2', sep=','", ",").length == 2)
899 } catch (AssertionError x)
901 System.err.println("separatorListToArray is faulty.");
903 if (argv.length == 0)
905 if (!testRsdExchange("Test using default Shmmr service",
906 RestClient.makeShmmrRestClient().service))
908 System.err.println("default test failed.");
912 System.err.println("default test passed.");
918 for (String svc : argv)
920 p += testRsdExchange("Test " + (++i), svc) ? 1 : 0;
922 System.err.println("" + p + " out of " + i + " tests passed.");
927 private static boolean testRsdExchange(String desc, String servicestring)
931 RestServiceDescription newService = new RestServiceDescription(
933 if (!newService.isValid())
935 throw new Error("Failed to create service from '" + servicestring
936 + "'.\n" + newService.getInvalidMessage());
938 return testRsdExchange(desc, newService);
939 } catch (Throwable x)
941 System.err.println("Failed for service (" + desc + "): "
948 private static boolean testRsdExchange(String desc,
949 RestServiceDescription service)
953 String fromservicetostring = service.toString();
954 RestServiceDescription newService = new RestServiceDescription(
955 fromservicetostring);
956 if (!newService.isValid())
958 throw new Error("Failed to create service from '"
959 + fromservicetostring + "'.\n"
960 + newService.getInvalidMessage());
963 if (!service.equals(newService))
965 System.err.println("Failed for service (" + desc + ").");
966 System.err.println("Original service and parsed service differ.");
967 System.err.println("Original: " + fromservicetostring);
968 System.err.println("Parsed : " + newService.toString());
971 } catch (Throwable x)
973 System.err.println("Failed for service (" + desc + "): "
974 + service.toString());
982 * covenience method to generate the id and sequence string vector from a set
983 * of seuqences using each sequence's getName() and getSequenceAsString()
987 * @return String[][] {{sequence ids},{sequence strings}}
989 public static String[][] formStrings(SequenceI[] seqs)
991 String[][] idset = new String[2][seqs.length];
992 for (int i = 0; i < seqs.length; i++)
994 idset[0][i] = seqs[i].getName();
995 idset[1][i] = seqs[i].getSequenceAsString();
1001 * can this service be run on the visible portion of an alignment regardless
1002 * of hidden boundaries ?
1004 boolean hseparable = false;
1006 boolean vseparable = false;
1008 public boolean isHseparable()
1017 public boolean isVseparable()
1023 * search the input types for an instance of the given class
1025 * @param <validInput.inputType> class1
1028 public boolean inputInvolves(Class<?> class1)
1030 assert (InputType.class.isAssignableFrom(class1));
1031 for (InputType val : inputParams.values())
1033 if (class1.isAssignableFrom(val.getClass()))
1041 char gapCharacter = '-';
1045 * @return the preferred gap character for alignments input/output by this
1048 public char getGapCharacter()
1050 return gapCharacter;
1053 public String getDecoratedResultUrl(String jobId)
1055 // TODO: correctly write ?/& appropriate to result URL format.
1056 return jobId + urlSuffix;
1059 private List<JvDataType> resultData = new ArrayList<JvDataType>();
1064 * TODO: Extend to optionally specify relative/absolute url where data of this
1065 * type can be retrieved from
1069 public void addResultDatatype(JvDataType dt)
1071 if (resultData == null)
1073 resultData = new ArrayList<JvDataType>();
1078 public boolean removeRsultDatatype(JvDataType dt)
1080 if (resultData != null)
1082 return resultData.remove(dt);
1087 public List<JvDataType> getResultDataTypes()
1093 * parse a concatenated list of rest service descriptions into an array
1096 * @return zero or more services.
1097 * @throws exceptions
1098 * if the services are improperly encoded.
1100 public static List<RestServiceDescription> parseDescriptions(
1101 String services) throws Exception
1103 String[] list = separatorListToArray(services, "|");
1104 List<RestServiceDescription> svcparsed = new ArrayList<RestServiceDescription>();
1105 int p = 0, lastp = 0;
1106 StringBuffer warnings = new StringBuffer();
1109 RestServiceDescription rsd = new RestServiceDescription();
1110 p = rsd.parseServiceList(list, warnings, lastp = p);
1111 if (p > lastp && rsd.isValid())
1117 throw new Exception(
1118 "Failed to parse user defined RSBS services from :"
1120 + "\nFirst error was encountered at token " + lastp
1121 + " starting " + list[lastp] + ":\n"
1122 + rsd.getInvalidMessage());
1124 } while (p < lastp && p < list.length - 1);