007da86f5d00fb2b2b9d3303972dd45839a07e77
[jalview.git] / UrlLink.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3
10  * of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License
18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
19  * The Jalview Authors are detailed in the 'AUTHORS' file.
20  */
21 package jalview.util;
22
23 import static jalview.util.UrlConstants.DB_ACCESSION;
24 import static jalview.util.UrlConstants.DELIM;
25 import static jalview.util.UrlConstants.SEP;
26 import static jalview.util.UrlConstants.SEQUENCE_ID;
27
28 import jalview.datamodel.DBRefEntry;
29 import jalview.datamodel.SequenceI;
30
31 import java.util.Arrays;
32 import java.util.List;
33 import java.util.Map;
34 import java.util.Vector;
35
36 public class UrlLink
37 {
38   /**
39    * helper class to parse URL Link strings taken from applet parameters or
40    * jalview properties file using the com.stevesoft.pat.Regex implementation.
41    * Jalview 2.4 extension allows regular expressions to be used to parse ID
42    * strings and replace the result in the URL. Regex's operate on the whole ID
43    * string given to the matchURL method, if no regex is supplied, then only
44    * text following the first pipe symbol will be substituted. Usage
45    * documentation todo.
46    */
47
48   private static final String EQUALS = "=";
49
50   private static final String SPACE = " ";
51
52   private String urlSuffix;
53
54   private String urlPrefix;
55
56   private String target;
57
58   private String label;
59
60   private String dbname;
61
62   private String regexReplace;
63
64   private boolean dynamic = false;
65
66   private boolean usesDBaccession = false;
67
68   private String invalidMessage = null;
69
70   /**
71    * parse the given linkString of the form '<label>SEP<url>' into parts url may
72    * contain a string $SEQUENCE_ID<=optional regex=>$ where <=optional regex=>
73    * must be of the form =/<perl style regex>/=$
74    * 
75    * @param link
76    */
77   public UrlLink(String link)
78   {
79     int sep = link.indexOf(SEP);
80     int psqid = link.indexOf(DELIM + DB_ACCESSION);
81     int nsqid = link.indexOf(DELIM + SEQUENCE_ID);
82     if (psqid > -1)
83     {
84       dynamic = true;
85       usesDBaccession = true;
86
87       sep = parseLabel(sep, psqid, link);
88
89       int endOfRegex = parseUrl(link, DB_ACCESSION, psqid, sep);
90       parseTarget(link, sep, endOfRegex);
91     }
92     else if (nsqid > -1)
93     {
94       dynamic = true;
95       sep = parseLabel(sep, nsqid, link);
96
97       int endOfRegex = parseUrl(link, SEQUENCE_ID, nsqid, sep);
98
99       parseTarget(link, sep, endOfRegex);
100     }
101     else
102     {
103       label = link.substring(0, sep).trim();
104
105       // if there's a third element in the url link string
106       // it is the target name, otherwise target=label
107       int lastsep = link.lastIndexOf(SEP);
108       if (lastsep != sep)
109       {
110         urlPrefix = link.substring(sep + 1, lastsep).trim();
111         target = link.substring(lastsep + 1).trim();
112       }
113       else
114       {
115         urlPrefix = link.substring(sep + 1).trim();
116         target = label;
117       }
118
119       regexReplace = null; // implies we trim any prefix if necessary //
120       urlSuffix = null;
121     }
122
123     label = label.trim();
124     target = target.trim();
125   }
126
127   /**
128    * Alternative constructor for separate name, link and description
129    * 
130    * @param name
131    *          The string used to match the link to a DB reference id
132    * @param url
133    *          The url to link to
134    * @param desc
135    *          The description of the associated target DB
136    */
137   public UrlLink(String name, String url, String desc)
138   {
139     this(name + SEP + url + SEP + desc);
140   }
141
142   /**
143    * @return the url_suffix
144    */
145   public String getUrlSuffix()
146   {
147     return urlSuffix;
148   }
149
150   /**
151    * @return the url_prefix
152    */
153   public String getUrlPrefix()
154   {
155     return urlPrefix;
156   }
157
158   /**
159    * @return the target
160    */
161   public String getTarget()
162   {
163     return target;
164   }
165
166   /**
167    * @return the label
168    */
169   public String getLabel()
170   {
171     return label;
172   }
173
174   public String getUrlWithToken()
175   {
176     String var = (usesDBaccession ? DB_ACCESSION : SEQUENCE_ID);
177
178     return urlPrefix
179             + (dynamic
180                     ? (DELIM + var
181                             + ((regexReplace != null)
182                                     ? EQUALS + regexReplace + EQUALS + DELIM
183                                     : DELIM))
184                     : "")
185             + ((urlSuffix == null) ? "" : urlSuffix);
186   }
187
188   /**
189    * @return the regexReplace
190    */
191   public String getRegexReplace()
192   {
193     return regexReplace;
194   }
195
196   /**
197    * @return the invalidMessage
198    */
199   public String getInvalidMessage()
200   {
201     return invalidMessage;
202   }
203
204   /**
205    * Check if URL string was parsed properly.
206    * 
207    * @return boolean - if false then <code>getInvalidMessage</code> returns an
208    *         error message
209    */
210   public boolean isValid()
211   {
212     return invalidMessage == null;
213   }
214
215   /**
216    * 
217    * @return whether link is dynamic
218    */
219   public boolean isDynamic()
220   {
221     return dynamic;
222   }
223
224   /**
225    * 
226    * @return whether link uses DB Accession id
227    */
228   public boolean usesDBAccession()
229   {
230     return usesDBaccession;
231   }
232
233   /**
234    * Set the label
235    * 
236    * @param newlabel
237    */
238   public void setLabel(String newlabel)
239   {
240     this.label = newlabel;
241   }
242
243   /**
244    * Set the target
245    * 
246    * @param desc
247    */
248   public void setTarget(String desc)
249   {
250     target = desc;
251   }
252
253   /**
254    * return one or more URL strings by applying regex to the given idstring
255    * 
256    * @param idstring
257    * @param onlyIfMatches
258    *          - when true url strings are only made if regex is defined and
259    *          matches
260    * @return String[] { part of idstring substituted, full substituted url , ..
261    *         next part, next url..}
262    */
263   public String[] makeUrls(String idstring, boolean onlyIfMatches)
264   {
265     if (dynamic)
266     {
267       if (regexReplace != null)
268       {
269         com.stevesoft.pat.Regex rg = com.stevesoft.pat.Regex
270                 .perlCode("/" + regexReplace + "/");
271         if (rg.search(idstring))
272         {
273           int ns = rg.numSubs();
274           if (ns == 0)
275           {
276             // take whole regex
277             return new String[] { rg.stringMatched(),
278                 urlPrefix + rg.stringMatched() + urlSuffix };
279           } /*
280              * else if (ns==1) { // take only subgroup match return new String[]
281              * { rg.stringMatched(1), url_prefix+rg.stringMatched(1)+url_suffix
282              * }; }
283              */
284           else
285           {
286             // debug
287             for (int s = 0; s <= rg.numSubs(); s++)
288             {
289               System.err.println("Sub " + s + " : " + rg.matchedFrom(s)
290                       + " : " + rg.matchedTo(s) + " : '"
291                       + rg.stringMatched(s) + "'");
292             }
293             // try to collate subgroup matches
294             Vector<String> subs = new Vector<String>();
295             // have to loop through submatches, collating them at top level
296             // match
297             int s = 0; // 1;
298             while (s <= ns)
299             {
300               if (s + 1 <= ns && rg.matchedTo(s) > -1
301                       && rg.matchedTo(s + 1) > -1
302                       && rg.matchedTo(s + 1) < rg.matchedTo(s))
303               {
304                 // s is top level submatch. search for submatches enclosed by
305                 // this one
306                 int r = s + 1;
307                 String mtch = "";
308                 while (r <= ns && rg.matchedTo(r) <= rg.matchedTo(s))
309                 {
310                   if (rg.matchedFrom(r) > -1)
311                   {
312                     mtch += rg.stringMatched(r);
313                   }
314                   r++;
315                 }
316                 if (mtch.length() > 0)
317                 {
318                   subs.addElement(mtch);
319                   subs.addElement(urlPrefix + mtch + urlSuffix);
320                 }
321                 s = r;
322               }
323               else
324               {
325                 if (rg.matchedFrom(s) > -1)
326                 {
327                   subs.addElement(rg.stringMatched(s));
328                   subs.addElement(
329                           urlPrefix + rg.stringMatched(s) + urlSuffix);
330                 }
331                 s++;
332               }
333             }
334
335             String[] res = new String[subs.size()];
336             for (int r = 0, rs = subs.size(); r < rs; r++)
337             {
338               res[r] = subs.elementAt(r);
339             }
340             subs.removeAllElements();
341             return res;
342           }
343         }
344         if (onlyIfMatches)
345         {
346           return null;
347         }
348       }
349       /* Otherwise - trim off any 'prefix' - pre 2.4 Jalview behaviour */
350       if (idstring.indexOf(SEP) > -1)
351       {
352         idstring = idstring.substring(idstring.lastIndexOf(SEP) + 1);
353       }
354
355       // just return simple url substitution.
356       return new String[] { idstring, urlPrefix + idstring + urlSuffix };
357     }
358     else
359     {
360       return new String[] { "", urlPrefix };
361     }
362   }
363
364   @Override
365   public String toString()
366   {
367     return label + SEP + getUrlWithToken();
368   }
369
370   /**
371    * @return delimited string containing label, url and target
372    */
373   public String toStringWithTarget()
374   {
375     return label + SEP + getUrlWithToken() + SEP + target;
376   }
377
378   /**
379    * Parse the label from the link string
380    * 
381    * @param firstSep
382    *          Location of first occurrence of separator in link string
383    * @param psqid
384    *          Position of sequence id or name in link string
385    * @param link
386    *          Link string containing database name and url
387    * @return Position of last separator symbol prior to any regex symbols
388    */
389   protected int parseLabel(int firstSep, int psqid, String link)
390   {
391     int p = firstSep;
392     int sep = firstSep;
393     do
394     {
395       sep = p;
396       p = link.indexOf(SEP, sep + 1);
397     } while (p > sep && p < psqid);
398     // Assuming that the URL itself does not contain any SEP symbols
399     // sep now contains last pipe symbol position prior to any regex symbols
400     label = link.substring(0, sep);
401
402     return sep;
403   }
404
405   /**
406    * Parse the target from the link string
407    * 
408    * @param link
409    *          Link string containing database name and url
410    * @param sep
411    *          Location of first separator symbol
412    * @param endOfRegex
413    *          Location of end of any regular expression in link string
414    */
415   protected void parseTarget(String link, int sep, int endOfRegex)
416   {
417     int lastsep = link.lastIndexOf(SEP);
418
419     if ((lastsep != sep) && (lastsep > endOfRegex))
420     {
421       // final element in link string is the target
422       target = link.substring(lastsep + 1).trim();
423     }
424     else
425     {
426       target = label;
427     }
428
429     if (target.indexOf(SEP) > -1)
430     {
431       // SEP terminated database name / www target at start of Label
432       target = target.substring(0, target.indexOf(SEP));
433     }
434     else if (target.indexOf(SPACE) > 2)
435     {
436       // space separated label - first word matches database name
437       target = target.substring(0, target.indexOf(SPACE));
438     }
439   }
440
441   /**
442    * Parse the URL part of the link string
443    * 
444    * @param link
445    *          Link string containing database name and url
446    * @param varName
447    *          Name of variable in url string (e.g. SEQUENCE_ID, SEQUENCE_NAME)
448    * @param sqidPos
449    *          Position of id or name in link string
450    * @param sep
451    *          Position of separator in link string
452    * @return Location of end of any regex in link string
453    */
454   protected int parseUrl(String link, String varName, int sqidPos, int sep)
455   {
456     urlPrefix = link.substring(sep + 1, sqidPos).trim();
457
458     // delimiter at start of regex: e.g. $SEQUENCE_ID=/
459     String startDelimiter = DELIM + varName + "=/";
460
461     // delimiter at end of regex: /=$
462     String endDelimiter = "/=" + DELIM;
463
464     int startLength = startDelimiter.length();
465
466     // Parse URL : Whole URL string first
467     int p = link.indexOf(endDelimiter, sqidPos + startLength);
468
469     if (link.indexOf(startDelimiter) == sqidPos
470             && (p > sqidPos + startLength))
471     {
472       // Extract Regex and suffix
473       urlSuffix = link.substring(p + endDelimiter.length());
474       regexReplace = link.substring(sqidPos + startLength, p);
475       try
476       {
477         com.stevesoft.pat.Regex rg = com.stevesoft.pat.Regex
478                 .perlCode("/" + regexReplace + "/");
479         if (rg == null)
480         {
481           invalidMessage = "Invalid Regular Expression : '" + regexReplace
482                   + "'\n";
483         }
484       } catch (Exception e)
485       {
486         invalidMessage = "Invalid Regular Expression : '" + regexReplace
487                 + "'\n";
488       }
489     }
490     else
491     {
492       // no regex
493       regexReplace = null;
494       // verify format is really correct.
495       if (link.indexOf(DELIM + varName + DELIM) == sqidPos)
496       {
497         int lastsep = link.lastIndexOf(SEP);
498         if (lastsep < sqidPos + startLength - 1)
499         {
500           // the last SEP character was before the regex, ignore
501           lastsep = link.length();
502         }
503         urlSuffix = link.substring(sqidPos + startLength - 1, lastsep)
504                 .trim();
505         regexReplace = null;
506       }
507       else
508       {
509         invalidMessage = "Warning: invalid regex structure for URL link : "
510                 + link;
511       }
512     }
513
514     return p;
515   }
516
517   /**
518    * Create a set of URL links for a sequence
519    * 
520    * @param seq
521    *          The sequence to create links for
522    * @param linkset
523    *          Map of links: key = id + SEP + link, value = [target, label, id,
524    *          link]
525    */
526   public void createLinksFromSeq(final SequenceI seq,
527           Map<String, List<String>> linkset)
528   {
529     if (seq != null && dynamic)
530     {
531       createDynamicLinks(seq, linkset);
532     }
533     else
534     {
535       createStaticLink(linkset);
536     }
537   }
538
539   /**
540    * Create a static URL link
541    * 
542    * @param linkset
543    *          Map of links: key = id + SEP + link, value = [target, label, id,
544    *          link]
545    */
546   protected void createStaticLink(Map<String, List<String>> linkset)
547   {
548     if (!linkset.containsKey(label + SEP + getUrlPrefix()))
549     {
550       // Add a non-dynamic link
551       linkset.put(label + SEP + getUrlPrefix(),
552               Arrays.asList(target, label, null, getUrlPrefix()));
553     }
554   }
555
556   /**
557    * Create dynamic URL links
558    * 
559    * @param seq
560    *          The sequence to create links for
561    * @param linkset
562    *          Map of links: key = id + SEP + link, value = [target, label, id,
563    *          link]
564    */
565   protected void createDynamicLinks(final SequenceI seq,
566           Map<String, List<String>> linkset)
567   {
568     // collect id string too
569     String id = seq.getName();
570     String descr = seq.getDescription();
571     if (descr != null && descr.length() < 1)
572     {
573       descr = null;
574     }
575
576     if (usesDBAccession()) // link is ID
577     {
578       // collect matching db-refs
579       DBRefEntry[] dbr = DBRefUtils.selectRefs(seq.getDBRefs(),
580               new String[]
581               { target });
582
583       // if there are any dbrefs which match up with the link
584       if (dbr != null)
585       {
586         for (int r = 0; r < dbr.length; r++)
587         {
588           // create Bare ID link for this URL
589           createBareURLLink(dbr[r].getAccessionId(), true, linkset);
590         }
591       }
592     }
593     else if (!usesDBAccession() && id != null) // link is name
594     {
595       // create Bare ID link for this URL
596       createBareURLLink(id, false, linkset);
597     }
598
599     // Create urls from description but only for URL links which are regex
600     // links
601     if (descr != null && getRegexReplace() != null)
602     {
603       // create link for this URL from description where regex matches
604       createBareURLLink(descr, false, linkset);
605     }
606   }
607
608   /*
609    * Create a bare URL Link
610    * Returns map where key = id + SEP + link, and value = [target, label, id, link]
611    */
612   protected void createBareURLLink(String id, Boolean combineLabel,
613           Map<String, List<String>> linkset)
614   {
615     String[] urls = makeUrls(id, true);
616     if (urls != null)
617     {
618       for (int u = 0; u < urls.length; u += 2)
619       {
620         if (!linkset.containsKey(urls[u] + SEP + urls[u + 1]))
621         {
622           String thisLabel = label;
623           if (combineLabel)
624           {
625             // incorporate label with idstring
626             thisLabel = label + SEP + urls[u];
627           }
628
629           linkset.put(urls[u] + SEP + urls[u + 1],
630                   Arrays.asList(target, thisLabel, urls[u], urls[u + 1]));
631         }
632       }
633     }
634   }
635 }