JAL-2778 try another way to draw sequences with reduced synchronisation
[jalview.git] / utils / HelpLinksChecker.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 import java.io.BufferedReader;
22 import java.io.File;
23 import java.io.FileReader;
24 import java.io.IOException;
25 import java.io.InputStream;
26 import java.net.URL;
27 import java.util.HashMap;
28 import java.util.Map;
29
30 /**
31  * A class to check help file cross-references, and external URLs if internet
32  * access is available
33  * 
34  * @author gmcarstairs
35  *
36  */
37 public class HelpLinksChecker implements BufferedLineReader.LineCleaner
38 {
39   private static final String HELP_HS = "help.hs";
40
41   private static final String HELP_TOC_XML = "helpTOC.xml";
42
43   private static final String HELP_JHM = "help.jhm";
44
45   private static boolean internetAvailable = true;
46
47   private int targetCount = 0;
48
49   private int mapCount = 0;
50
51   private int internalHrefCount = 0;
52
53   private int anchorRefCount = 0;
54
55   private int invalidAnchorRefCount = 0;
56
57   private int externalHrefCount = 0;
58
59   private int invalidMapUrlCount = 0;
60
61   private int invalidTargetCount = 0;
62
63   private int invalidImageCount = 0;
64
65   private int invalidInternalHrefCount = 0;
66
67   private int invalidExternalHrefCount = 0;
68
69   /**
70    * The only parameter should be a path to the root of the help directory in
71    * the workspace
72    * 
73    * @param args
74    *          [0] path to the /html folder in the workspace
75    * @param args
76    *          [1] (optional) -nointernet to suppress external link checking for
77    *          a fast check of internal links only
78    * @throws IOException
79    */
80   public static void main(String[] args) throws IOException
81   {
82     if (args.length == 0 || args.length > 2
83             || (args.length == 2 && !args[1].equals("-nointernet")))
84     {
85       log("Usage: <pathToHelpFolder> [-nointernet]");
86       return;
87     }
88
89     if (args.length == 2)
90     {
91       internetAvailable = false;
92     }
93
94     new HelpLinksChecker().checkLinks(args[0]);
95   }
96
97   /**
98    * Checks help links and reports results
99    * 
100    * @param helpDirectoryPath
101    * @throws IOException
102    */
103   void checkLinks(String helpDirectoryPath) throws IOException
104   {
105     log("Checking help file links");
106     File helpFolder = new File(helpDirectoryPath).getCanonicalFile();
107     if (!helpFolder.exists())
108     {
109       log("Can't find " + helpDirectoryPath);
110       return;
111     }
112
113     internetAvailable &= connectToUrl("http://www.example.org");
114
115     Map<String, String> tocTargets = checkHelpMappings(helpFolder);
116
117     Map<String, String> unusedTargets = new HashMap<String, String>(
118             tocTargets);
119
120     checkTableOfContents(helpFolder, tocTargets, unusedTargets);
121
122     checkHelpSet(helpFolder, tocTargets, unusedTargets);
123
124     checkHtmlFolder(new File(helpFolder, "html"));
125
126     reportResults(unusedTargets);
127   }
128
129   /**
130    * Checks all html files in the given directory or its sub-directories
131    * 
132    * @param folder
133    * @throws IOException
134    */
135   private void checkHtmlFolder(File folder) throws IOException
136   {
137     File[] files = folder.listFiles();
138     for (File f : files)
139     {
140       if (f.isDirectory())
141       {
142         checkHtmlFolder(f);
143       }
144       else
145       {
146         if (f.getAbsolutePath().endsWith(".html"))
147         {
148           checkHtmlFile(f, folder);
149         }
150       }
151     }
152   }
153
154   /**
155    * Checks that any image attribute in help.hs is a valid target
156    * 
157    * @param helpFolder
158    * @param tocTargets
159    * @param unusedTargets
160    *          used targets are removed from here
161    */
162   private void checkHelpSet(File helpFolder,
163           Map<String, String> tocTargets, Map<String, String> unusedTargets)
164           throws IOException
165   {
166     BufferedReader br = new BufferedReader(new FileReader(new File(
167             helpFolder, HELP_HS)));
168     String data = br.readLine();
169     int lineNo = 0;
170
171     while (data != null)
172     {
173       lineNo++;
174       String image = getAttribute(data, "image");
175       if (image != null)
176       {
177         unusedTargets.remove(image);
178         if (!tocTargets.containsKey(image))
179         {
180           log(String.format("Invalid image '%s' at line %d of %s", image,
181                   lineNo, HELP_HS));
182           invalidImageCount++;
183         }
184       }
185       data = br.readLine();
186     }
187     br.close();
188   }
189
190   /**
191    * Print counts to sysout
192    * 
193    * @param unusedTargets
194    */
195   private void reportResults(Map<String, String> unusedTargets)
196   {
197     log("\nResults:");
198     log(targetCount + " distinct help targets");
199     log(mapCount + " help mappings");
200     log(invalidTargetCount + " invalid targets");
201     log(unusedTargets.size() + " unused targets");
202     for (String target : unusedTargets.keySet())
203     {
204       log(String.format("    %s: %s", target, unusedTargets.get(target)));
205     }
206     log(invalidMapUrlCount + " invalid map urls");
207     log(invalidImageCount + " invalid image attributes");
208     log(String.format("%d internal href links (%d with anchors)",
209             internalHrefCount, anchorRefCount));
210     log(invalidInternalHrefCount + " invalid internal href links");
211     log(invalidAnchorRefCount + " invalid internal anchor links");
212     log(externalHrefCount + " external href links");
213     if (internetAvailable)
214     {
215       log(invalidExternalHrefCount + " invalid external href links");
216     }
217     else
218     {
219       System.out
220               .println("External links not verified as internet not available");
221     }
222     if (invalidInternalHrefCount > 0 || invalidExternalHrefCount > 0
223             || invalidImageCount > 0 || invalidAnchorRefCount > 0)
224     {
225       log("*** Failed ***");
226       System.exit(1);
227     }
228     log("*** Success ***");
229   }
230
231   /**
232    * @param s
233    */
234   static void log(String s)
235   {
236     System.out.println(s);
237   }
238
239   /**
240    * Reads the given html file and checks any href attibute values are either
241    * <ul>
242    * <li>a valid relative file path, or</li>
243    * <li>a valid absolute URL (if external link checking is enabled)</li>
244    * </ul>
245    * 
246    * @param htmlFile
247    * @param htmlFolder
248    *          the parent folder (for validation of relative paths)
249    */
250   private void checkHtmlFile(File htmlFile, File htmlFolder)
251           throws IOException
252   {
253     BufferedReader br = new BufferedReader(new FileReader(htmlFile));
254     String data = br.readLine();
255     int lineNo = 0;
256     while (data != null)
257     {
258       lineNo++;
259       String href = getAttribute(data, "href");
260       if (href != null)
261       {
262         String anchor = null;
263         int anchorPos = href.indexOf("#");
264         if (anchorPos != -1)
265         {
266           anchor = href.substring(anchorPos + 1);
267           href = href.substring(0, anchorPos);
268         }
269         boolean badLink = false;
270         if (href.startsWith("http"))
271         {
272           externalHrefCount++;
273           if (internetAvailable)
274           {
275             if (!connectToUrl(href))
276             {
277               badLink = true;
278               invalidExternalHrefCount++;
279             }
280           }
281         }
282         else
283         {
284           internalHrefCount++;
285           File hrefFile = href.equals("") ? htmlFile : new File(htmlFolder,
286                   href);
287           if (hrefFile != htmlFile && !fileExists(hrefFile, href))
288           {
289             badLink = true;
290             invalidInternalHrefCount++;
291           }
292           if (anchor != null)
293           {
294             anchorRefCount++;
295             if (!badLink)
296             {
297               if (!checkAnchorExists(hrefFile, anchor))
298               {
299                 log(String.format("Invalid anchor: %s at line %d of %s",
300                         anchor, lineNo, getPath(htmlFile)));
301                 invalidAnchorRefCount++;
302               }
303             }
304           }
305         }
306         if (badLink)
307         {
308           log(String.format("Invalid href %s at line %d of %s", href,
309                   lineNo, getPath(htmlFile)));
310         }
311       }
312       data = br.readLine();
313     }
314     br.close();
315   }
316
317   /**
318    * Performs a case-sensitive check that the href'd file exists
319    * 
320    * @param hrefFile
321    * @return
322    * @throws IOException
323    */
324   boolean fileExists(File hrefFile, String href) throws IOException
325   {
326     if (!hrefFile.exists())
327     {
328       return false;
329     }
330
331     /*
332      * On Mac or Windows, file.exists() is not case sensitive, so do an
333      * additional check with case sensitivity 
334      */
335     int slashPos = href.lastIndexOf(File.separator);
336     String expectedFileName = slashPos == -1 ? href : href
337             .substring(slashPos + 1);
338     String cp = hrefFile.getCanonicalPath();
339     slashPos = cp.lastIndexOf(File.separator);
340     String actualFileName = slashPos == -1 ? cp : cp
341             .substring(slashPos + 1);
342
343     return expectedFileName.equals(actualFileName);
344   }
345
346   /**
347    * Reads the file and checks for the presence of the given html anchor
348    * 
349    * @param hrefFile
350    * @param anchor
351    * @return true if anchor is found else false
352    */
353   private boolean checkAnchorExists(File hrefFile, String anchor)
354   {
355     String nameAnchor = "<a name=\"" + anchor + "\"";
356     String idAnchor = "<a id=\"" + anchor + "\"";
357     boolean found = false;
358     try
359     {
360       BufferedReader br = new BufferedReader(new FileReader(hrefFile));
361       BufferedLineReader blr = new BufferedLineReader(br, 3, this);
362       String data = blr.read();
363       while (data != null)
364       {
365         if (data.contains(nameAnchor) || data.contains(idAnchor))
366         {
367           found = true;
368           break;
369         }
370         data = blr.read();
371       }
372       br.close();
373     } catch (IOException e)
374     {
375       // ignore
376     }
377     return found;
378   }
379
380   /**
381    * Returns the part of the file path starting from /help/
382    * 
383    * @param helpFile
384    * @return
385    */
386   private String getPath(File helpFile)
387   {
388     String path = helpFile.getPath();
389     int helpPos = path.indexOf("/help/");
390     return helpPos == -1 ? path : path.substring(helpPos);
391   }
392
393   /**
394    * Returns true if the URL returns an input stream, or false if the URL
395    * returns an error code or we cannot connect to it (e.g. no internet
396    * available)
397    * 
398    * @param url
399    * @return
400    */
401   private boolean connectToUrl(String url)
402   {
403     try
404     {
405       URL u = new URL(url);
406       InputStream connection = u.openStream();
407       connection.close();
408       return true;
409     } catch (Throwable t)
410     {
411       return false;
412     }
413   }
414
415   /**
416    * Reads file help.jhm and checks that
417    * <ul>
418    * <li>each target attribute is in tocTargets</li>
419    * <li>each url attribute is a valid relative file link</li>
420    * </ul>
421    * 
422    * @param helpFolder
423    */
424   private Map<String, String> checkHelpMappings(File helpFolder)
425           throws IOException
426   {
427     Map<String, String> targets = new HashMap<String, String>();
428     BufferedReader br = new BufferedReader(new FileReader(new File(
429             helpFolder, HELP_JHM)));
430     String data = br.readLine();
431     int lineNo = 0;
432     while (data != null)
433     {
434       lineNo++;
435
436       /*
437        * record target, check for duplicates
438        */
439       String target = getAttribute(data, "target");
440       if (target != null)
441       {
442         mapCount++;
443         if (targets.containsKey(target))
444         {
445           log(String.format(
446                   "Duplicate target mapping to %s at line %d of %s",
447                   target, lineNo, HELP_JHM));
448         }
449         else
450         {
451           targetCount++;
452         }
453       }
454
455       /*
456        * validate url
457        */
458       String url = getAttribute(data, "url");
459       if (url != null)
460       {
461         targets.put(target, url);
462         int anchorPos = url.indexOf("#");
463         if (anchorPos != -1)
464         {
465           url = url.substring(0, anchorPos);
466         }
467         if (!new File(helpFolder, url).exists())
468         {
469           log(String.format("Invalid url path '%s' at line %d of %s", url,
470                   lineNo, HELP_JHM));
471           invalidMapUrlCount++;
472         }
473       }
474       data = br.readLine();
475     }
476     br.close();
477     return targets;
478   }
479
480   /**
481    * Reads file helpTOC.xml and reports any invalid targets
482    * 
483    * @param helpFolder
484    * @param tocTargets
485    * @param unusedTargets
486    *          used targets are removed from this map
487    * 
488    * @return
489    * @throws IOException
490    */
491   private void checkTableOfContents(File helpFolder,
492           Map<String, String> tocTargets, Map<String, String> unusedTargets)
493           throws IOException
494   {
495     BufferedReader br = new BufferedReader(new FileReader(new File(
496             helpFolder, HELP_TOC_XML)));
497     String data = br.readLine();
498     int lineNo = 0;
499     while (data != null)
500     {
501       lineNo++;
502       /*
503        * assuming no more than one "target" per line of file here
504        */
505       String target = getAttribute(data, "target");
506       if (target != null)
507       {
508         unusedTargets.remove(target);
509         if (!tocTargets.containsKey(target))
510         {
511           log(String.format("Invalid target '%s' at line %d of %s", target,
512                   lineNo, HELP_TOC_XML));
513           invalidTargetCount++;
514         }
515       }
516       data = br.readLine();
517     }
518     br.close();
519   }
520
521   /**
522    * Returns the value of an attribute if found in the data, else null
523    * 
524    * @param data
525    * @param attName
526    * @return
527    */
528   private static String getAttribute(String data, String attName)
529   {
530     /*
531      * make a partial attempt at ignoring within <!-- html comments -->
532      * (doesn't work if multi-line)
533      */
534     int commentStartPos = data.indexOf("<!--");
535     int commentEndPos = commentStartPos == -1 ? -1 : data.substring(
536             commentStartPos + 4).indexOf("-->");
537     String value = null;
538     String match = attName + "=\"";
539     int attPos = data.indexOf(match);
540     if (attPos > 0
541             && (commentStartPos == -1 || attPos < commentStartPos || attPos > commentEndPos))
542     {
543       data = data.substring(attPos + match.length());
544       value = data.substring(0, data.indexOf("\""));
545     }
546     return value;
547   }
548
549   /**
550    * Trim whitespace from concatenated lines but preserve one space for valid
551    * parsing
552    */
553   @Override
554   public String cleanLine(String l)
555   {
556     return l.trim() + " ";
557   }
558 }