View Javadoc
1   ////////////////////////////////////////////////////////////////////////////////
2   // checkstyle: Checks Java source code for adherence to a set of rules.
3   // Copyright (C) 2001-2017 the original author or authors.
4   //
5   // This library is free software; you can redistribute it and/or
6   // modify it under the terms of the GNU Lesser General Public
7   // License as published by the Free Software Foundation; either
8   // version 2.1 of the License, or (at your option) any later version.
9   //
10  // This library is distributed in the hope that it will be useful,
11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  // Lesser General Public License for more details.
14  //
15  // You should have received a copy of the GNU Lesser General Public
16  // License along with this library; if not, write to the Free Software
17  // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18  ////////////////////////////////////////////////////////////////////////////////
19  
20  package com.puppycrawl.tools.checkstyle.checks.javadoc;
21  
22  import java.io.File;
23  import java.io.IOException;
24  import java.util.Set;
25  import java.util.concurrent.ConcurrentHashMap;
26  
27  import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck;
28  import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
29  import com.puppycrawl.tools.checkstyle.api.FileText;
30  
31  /**
32   * Checks that all packages have a package documentation. See the documentation
33   * for more information.
34   * @author Oliver Burn
35   */
36  public class JavadocPackageCheck extends AbstractFileSetCheck {
37  
38      /**
39       * A key is pointing to the warning message text in "messages.properties"
40       * file.
41       */
42      public static final String MSG_LEGACY_PACKAGE_HTML = "javadoc.legacyPackageHtml";
43  
44      /**
45       * A key is pointing to the warning message text in "messages.properties"
46       * file.
47       */
48      public static final String MSG_PACKAGE_INFO = "javadoc.packageInfo";
49  
50      /** The directories checked. */
51      private final Set<File> directoriesChecked = ConcurrentHashMap.newKeySet();
52  
53      /** Indicates if allow legacy "package.html" file to be used. */
54      private boolean allowLegacy;
55  
56      /**
57       * Creates a new instance.
58       */
59      public JavadocPackageCheck() {
60          // java, not html!
61          // The rule is: Every JAVA file should have a package.html sibling
62          setFileExtensions("java");
63      }
64  
65      @Override
66      public void beginProcessing(String charset) {
67          super.beginProcessing(charset);
68          directoriesChecked.clear();
69      }
70  
71      @Override
72      protected void processFiltered(File file, FileText fileText) throws CheckstyleException {
73          // Check if already processed directory
74          final File dir;
75          try {
76              dir = file.getCanonicalFile().getParentFile();
77          }
78          catch (IOException ex) {
79              throw new CheckstyleException(
80                      "Exception while getting canonical path to file " + file.getPath(), ex);
81          }
82          final boolean isDirChecked = !directoriesChecked.add(dir);
83          if (!isDirChecked) {
84              // Check for the preferred file.
85              final File packageInfo = new File(dir, "package-info.java");
86              final File packageHtml = new File(dir, "package.html");
87  
88              if (packageInfo.exists()) {
89                  if (packageHtml.exists()) {
90                      log(0, MSG_LEGACY_PACKAGE_HTML);
91                  }
92              }
93              else if (!allowLegacy || !packageHtml.exists()) {
94                  log(0, MSG_PACKAGE_INFO);
95              }
96          }
97      }
98  
99      /**
100      * Indicates whether to allow support for the legacy <i>package.html</i>
101      * file.
102      * @param allowLegacy whether to allow support.
103      */
104     public void setAllowLegacy(boolean allowLegacy) {
105         this.allowLegacy = allowLegacy;
106     }
107 }