Merge branch 'releases/Release_2_11_4_Branch'
[jalview.git] / jalview / util / 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 ? (DELIM + var + ((regexReplace != null) ? EQUALS
180                     + regexReplace + EQUALS + DELIM : DELIM)) : "")
181             + ((urlSuffix == null) ? "" : urlSuffix);
182   }
183
184   /**
185    * @return the regexReplace
186    */
187   public String getRegexReplace()
188   {
189     return regexReplace;
190   }
191
192   /**
193    * @return the invalidMessage
194    */
195   public String getInvalidMessage()
196   {
197     return invalidMessage;
198   }
199
200   /**
201    * Check if URL string was parsed properly.
202    * 
203    * @return boolean - if false then <code>getInvalidMessage</code> returns an
204    *         error message
205    */
206   public boolean isValid()
207   {
208     return invalidMessage == null;
209   }
210
211   /**
212    * 
213    * @return whether link is dynamic
214    */
215   public boolean isDynamic()
216   {
217     return dynamic;
218   }
219
220   /**
221    * 
222    * @return whether link uses DB Accession id
223    */
224   public boolean usesDBAccession()
225   {
226     return usesDBaccession;
227   }
228
229   /**
230    * Set the label
231    * 
232    * @param newlabel
233    */
234   public void setLabel(String newlabel)
235   {
236     this.label = newlabel;
237   }
238
239   /**
240    * Set the target
241    * 
242    * @param desc
243    */
244   public void setTarget(String desc)
245   {
246     target = desc;
247   }
248
249   /**
250    * return one or more URL strings by applying regex to the given idstring
251    * 
252    * @param idstring
253    * @param onlyIfMatches
254    *          - when true url strings are only made if regex is defined and
255    *          matches
256    * @return String[] { part of idstring substituted, full substituted url , ..
257    *         next part, next url..}
258    */
259   public String[] makeUrls(String idstring, boolean onlyIfMatches)
260   {
261     if (dynamic)
262     {
263       if (regexReplace != null)
264       {
265         com.stevesoft.pat.Regex rg = com.stevesoft.pat.Regex.perlCode("/"
266                 + regexReplace + "/");
267         if (rg.search(idstring))
268         {
269           int ns = rg.numSubs();
270           if (ns == 0)
271           {
272             // take whole regex
273             return new String[] { rg.stringMatched(),
274                 urlPrefix + rg.stringMatched() + urlSuffix };
275           } /*
276              * else if (ns==1) { // take only subgroup match return new String[]
277              * { rg.stringMatched(1), url_prefix+rg.stringMatched(1)+url_suffix
278              * }; }
279              */
280           else
281           {
282             // debug
283             for (int s = 0; s <= rg.numSubs(); s++)
284             {
285               System.err.println("Sub " + s + " : " + rg.matchedFrom(s)
286                       + " : " + rg.matchedTo(s) + " : '"
287                       + rg.stringMatched(s) + "'");
288             }
289             // try to collate subgroup matches
290             Vector<String> subs = new Vector<String>();
291             // have to loop through submatches, collating them at top level
292             // match
293             int s = 0; // 1;
294             while (s <= ns)
295             {
296               if (s + 1 <= ns && rg.matchedTo(s) > -1
297                       && rg.matchedTo(s + 1) > -1
298                       && rg.matchedTo(s + 1) < rg.matchedTo(s))
299               {
300                 // s is top level submatch. search for submatches enclosed by
301                 // this one
302                 int r = s + 1;
303                 String mtch = "";
304                 while (r <= ns && rg.matchedTo(r) <= rg.matchedTo(s))
305                 {
306                   if (rg.matchedFrom(r) > -1)
307                   {
308                     mtch += rg.stringMatched(r);
309                   }
310                   r++;
311                 }
312                 if (mtch.length() > 0)
313                 {
314                   subs.addElement(mtch);
315                   subs.addElement(urlPrefix + mtch + urlSuffix);
316                 }
317                 s = r;
318               }
319               else
320               {
321                 if (rg.matchedFrom(s) > -1)
322                 {
323                   subs.addElement(rg.stringMatched(s));
324                   subs.addElement(urlPrefix + rg.stringMatched(s)
325                           + urlSuffix);
326                 }
327                 s++;
328               }
329             }
330
331             String[] res = new String[subs.size()];
332             for (int r = 0, rs = subs.size(); r < rs; r++)
333             {
334               res[r] = subs.elementAt(r);
335             }
336             subs.removeAllElements();
337             return res;
338           }
339         }
340         if (onlyIfMatches)
341         {
342           return null;
343         }
344       }
345       /* Otherwise - trim off any 'prefix' - pre 2.4 Jalview behaviour */
346       if (idstring.indexOf(SEP) > -1)
347       {
348         idstring = idstring.substring(idstring.lastIndexOf(SEP) + 1);
349       }
350
351       // just return simple url substitution.
352       return new String[] { idstring, urlPrefix + idstring + urlSuffix };
353     }
354     else
355     {
356       return new String[] { "", urlPrefix };
357     }
358   }
359
360   @Override
361   public String toString()
362   {
363     return label + SEP + getUrlWithToken();
364   }
365
366   /**
367    * @return delimited string containing label, url and target
368    */
369   public String toStringWithTarget()
370   {
371     return label + SEP + getUrlWithToken() + SEP + target;
372   }
373
374   /**
375    * Parse the label from the link string
376    * 
377    * @param firstSep
378    *          Location of first occurrence of separator in link string
379    * @param psqid
380    *          Position of sequence id or name in link string
381    * @param link
382    *          Link string containing database name and url
383    * @return Position of last separator symbol prior to any regex symbols
384    */
385   protected int parseLabel(int firstSep, int psqid, String link)
386   {
387     int p = firstSep;
388     int sep = firstSep;
389     do
390     {
391       sep = p;
392       p = link.indexOf(SEP, sep + 1);
393     } while (p > sep && p < psqid);
394     // Assuming that the URL itself does not contain any SEP symbols
395     // sep now contains last pipe symbol position prior to any regex symbols
396     label = link.substring(0, sep);
397
398     return sep;
399   }
400
401   /**
402    * Parse the target from the link string
403    * 
404    * @param link
405    *          Link string containing database name and url
406    * @param sep
407    *          Location of first separator symbol
408    * @param endOfRegex
409    *          Location of end of any regular expression in link string
410    */
411   protected void parseTarget(String link, int sep, int endOfRegex)
412   {
413     int lastsep = link.lastIndexOf(SEP);
414
415     if ((lastsep != sep) && (lastsep > endOfRegex))
416     {
417       // final element in link string is the target
418       target = link.substring(lastsep + 1).trim();
419     }
420     else
421     {
422       target = label;
423     }
424
425     if (target.indexOf(SEP) > -1)
426     {
427       // SEP terminated database name / www target at start of Label
428       target = target.substring(0, target.indexOf(SEP));
429     }
430     else if (target.indexOf(SPACE) > 2)
431     {
432       // space separated label - first word matches database name
433       target = target.substring(0, target.indexOf(SPACE));
434     }
435   }
436
437   /**
438    * Parse the URL part of the link string
439    * 
440    * @param link
441    *          Link string containing database name and url
442    * @param varName
443    *          Name of variable in url string (e.g. SEQUENCE_ID, SEQUENCE_NAME)
444    * @param sqidPos
445    *          Position of id or name in link string
446    * @param sep
447    *          Position of separator in link string
448    * @return Location of end of any regex in link string
449    */
450   protected int parseUrl(String link, String varName, int sqidPos, int sep)
451   {
452     urlPrefix = link.substring(sep + 1, sqidPos).trim();
453
454     // delimiter at start of regex: e.g. $SEQUENCE_ID=/
455     String startDelimiter = DELIM + varName + "=/";
456
457     // delimiter at end of regex: /=$
458     String endDelimiter = "/=" + DELIM;
459
460     int startLength = startDelimiter.length();
461
462     // Parse URL : Whole URL string first
463     int p = link.indexOf(endDelimiter, sqidPos + startLength);
464
465     if (link.indexOf(startDelimiter) == sqidPos
466             && (p > sqidPos + startLength))
467     {
468       // Extract Regex and suffix
469       urlSuffix = link.substring(p + endDelimiter.length());
470       regexReplace = link.substring(sqidPos + startLength, p);
471       try
472       {
473         com.stevesoft.pat.Regex rg = com.stevesoft.pat.Regex.perlCode("/"
474                 + regexReplace + "/");
475         if (rg == null)
476         {
477           invalidMessage = "Invalid Regular Expression : '" + regexReplace
478                   + "'\n";
479         }
480       } catch (Exception e)
481       {
482         invalidMessage = "Invalid Regular Expression : '" + regexReplace
483                 + "'\n";
484       }
485     }
486     else
487     {
488       // no regex
489       regexReplace = null;
490       // verify format is really correct.
491       if (link.indexOf(DELIM + varName + DELIM) == sqidPos)
492       {
493         int lastsep = link.lastIndexOf(SEP);
494         if (lastsep < sqidPos + startLength - 1)
495         {
496           // the last SEP character was before the regex, ignore
497           lastsep = link.length();
498         }
499         urlSuffix = link.substring(sqidPos + startLength - 1, lastsep)
500                 .trim();
501         regexReplace = null;
502       }
503       else
504       {
505         invalidMessage = "Warning: invalid regex structure for URL link : "
506                 + link;
507       }
508     }
509
510     return p;
511   }
512
513   /**
514    * Create a set of URL links for a sequence
515    * 
516    * @param seq
517    *          The sequence to create links for
518    * @param linkset
519    *          Map of links: key = id + SEP + link, value = [target, label, id,
520    *          link]
521    */
522   public void createLinksFromSeq(final SequenceI seq,
523           Map<String, List<String>> linkset)
524   {
525     if (seq != null && dynamic)
526     {
527       createDynamicLinks(seq, linkset);
528     }
529     else
530     {
531       createStaticLink(linkset);
532     }
533   }
534
535   /**
536    * Create a static URL link
537    * 
538    * @param linkset
539    *          Map of links: key = id + SEP + link, value = [target, label, id,
540    *          link]
541    */
542   protected void createStaticLink(Map<String, List<String>> linkset)
543   {
544     if (!linkset.containsKey(label + SEP + getUrlPrefix()))
545     {
546       // Add a non-dynamic link
547       linkset.put(label + SEP + getUrlPrefix(),
548               Arrays.asList(target, label, null, getUrlPrefix()));
549     }
550   }
551
552   /**
553    * Create dynamic URL links
554    * 
555    * @param seq
556    *          The sequence to create links for
557    * @param linkset
558    *          Map of links: key = id + SEP + link, value = [target, label, id,
559    *          link]
560    */
561   protected void createDynamicLinks(final SequenceI seq,
562           Map<String, List<String>> linkset)
563   {
564     // collect id string too
565     String id = seq.getName();
566     String descr = seq.getDescription();
567     if (descr != null && descr.length() < 1)
568     {
569       descr = null;
570     }
571
572     if (usesDBAccession()) // link is ID
573     {
574       // collect matching db-refs
575       DBRefEntry[] dbr = DBRefUtils.selectRefs(seq.getDBRefs(),
576               new String[] { target });
577
578       // if there are any dbrefs which match up with the link
579       if (dbr != null)
580       {
581         for (int r = 0; r < dbr.length; r++)
582         {
583           // create Bare ID link for this URL
584           createBareURLLink(dbr[r].getAccessionId(), true, linkset);
585         }
586       }
587     }
588     else if (!usesDBAccession() && id != null) // link is name
589     {
590       // create Bare ID link for this URL
591       createBareURLLink(id, false, linkset);
592     }
593
594     // Create urls from description but only for URL links which are regex
595     // links
596     if (descr != null && getRegexReplace() != null)
597     {
598       // create link for this URL from description where regex matches
599       createBareURLLink(descr, false, linkset);
600     }
601   }
602
603   /*
604    * Create a bare URL Link
605    * Returns map where key = id + SEP + link, and value = [target, label, id, link]
606    */
607   protected void createBareURLLink(String id, Boolean combineLabel,
608           Map<String, List<String>> linkset)
609   {
610     String[] urls = makeUrls(id, true);
611     if (urls != null)
612     {
613       for (int u = 0; u < urls.length; u += 2)
614       {
615         if (!linkset.containsKey(urls[u] + SEP + urls[u + 1]))
616         {
617           String thisLabel = label;
618           if (combineLabel)
619           {
620             // incorporate label with idstring
621             thisLabel = label + SEP + urls[u];
622           }
623
624           linkset.put(urls[u] + SEP + urls[u + 1],
625                   Arrays.asList(target, thisLabel, urls[u], urls[u + 1]));
626         }
627       }
628     }
629   }
630 }