Env.java revision 2880:e00e00b022e9
1/* 2 * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package com.sun.tools.doclint; 27 28 29import java.util.Arrays; 30import java.util.HashSet; 31import java.util.LinkedHashSet; 32import java.util.List; 33import java.util.Set; 34import java.util.regex.Pattern; 35 36import javax.lang.model.element.Element; 37import javax.lang.model.element.ElementKind; 38import javax.lang.model.element.ExecutableElement; 39import javax.lang.model.element.Modifier; 40import javax.lang.model.type.TypeMirror; 41import javax.lang.model.util.Elements; 42import javax.lang.model.util.Types; 43import javax.tools.Diagnostic.Kind; 44 45import com.sun.source.doctree.DocCommentTree; 46import com.sun.source.util.DocTrees; 47import com.sun.source.util.JavacTask; 48import com.sun.source.util.SourcePositions; 49import com.sun.source.util.TreePath; 50import com.sun.tools.javac.model.JavacTypes; 51import com.sun.tools.javac.tree.JCTree; 52import com.sun.tools.javac.util.MatchingUtils; 53import com.sun.tools.javac.util.StringUtils; 54 55/** 56 * Utility container for current execution environment, 57 * providing the current declaration and its doc comment. 58 * 59 * <p><b>This is NOT part of any supported API. 60 * If you write code that depends on this, you do so at your own 61 * risk. This code and its internal interfaces are subject to change 62 * or deletion without notice.</b></p> 63 */ 64public class Env { 65 /** 66 * Access kinds for declarations. 67 */ 68 public enum AccessKind { 69 PRIVATE, 70 PACKAGE, 71 PROTECTED, 72 PUBLIC; 73 74 static boolean accepts(String opt) { 75 for (AccessKind g: values()) 76 if (opt.equals(StringUtils.toLowerCase(g.name()))) return true; 77 return false; 78 } 79 80 static AccessKind of(Set<Modifier> mods) { 81 if (mods.contains(Modifier.PUBLIC)) 82 return AccessKind.PUBLIC; 83 else if (mods.contains(Modifier.PROTECTED)) 84 return AccessKind.PROTECTED; 85 else if (mods.contains(Modifier.PRIVATE)) 86 return AccessKind.PRIVATE; 87 else 88 return AccessKind.PACKAGE; 89 } 90 } 91 92 /** Message handler. */ 93 final Messages messages; 94 95 int implicitHeaderLevel = 0; 96 97 Set<String> customTags; 98 99 Set<Pattern> includePackages; 100 Set<Pattern> excludePackages; 101 102 HtmlVersion htmlVersion = HtmlVersion.HTML4; 103 104 // Utility classes 105 DocTrees trees; 106 Elements elements; 107 Types types; 108 109 // Types used when analysing doc comments. 110 TypeMirror java_lang_Error; 111 TypeMirror java_lang_RuntimeException; 112 TypeMirror java_lang_Throwable; 113 TypeMirror java_lang_Void; 114 115 /** The path for the declaration containing the comment currently being analyzed. */ 116 TreePath currPath; 117 /** The element for the declaration containing the comment currently being analyzed. */ 118 Element currElement; 119 /** The comment current being analyzed. */ 120 DocCommentTree currDocComment; 121 /** 122 * The access kind of the declaration containing the comment currently being analyzed. 123 * This is the minimum (most restrictive) access kind of the declaration itself 124 * and that of its containers. For example, a public method in a private class is 125 * noted as private. 126 */ 127 AccessKind currAccess; 128 /** The set of methods, if any, that the current declaration overrides. */ 129 Set<? extends ExecutableElement> currOverriddenMethods; 130 131 Env() { 132 messages = new Messages(this); 133 } 134 135 void init(JavacTask task) { 136 init(DocTrees.instance(task), task.getElements(), task.getTypes()); 137 } 138 139 void init(DocTrees trees, Elements elements, Types types) { 140 this.trees = trees; 141 this.elements = elements; 142 this.types = types; 143 } 144 145 void initTypes() { 146 if (java_lang_Error != null) 147 return ; 148 149 java_lang_Error = elements.getTypeElement("java.lang.Error").asType(); 150 java_lang_RuntimeException = elements.getTypeElement("java.lang.RuntimeException").asType(); 151 java_lang_Throwable = elements.getTypeElement("java.lang.Throwable").asType(); 152 java_lang_Void = elements.getTypeElement("java.lang.Void").asType(); 153 } 154 155 void setImplicitHeaders(int n) { 156 implicitHeaderLevel = n; 157 } 158 159 void setCustomTags(String cTags) { 160 customTags = new LinkedHashSet<>(); 161 for (String s : cTags.split(DocLint.SEPARATOR)) { 162 if (!s.isEmpty()) 163 customTags.add(s); 164 } 165 } 166 167 void setCheckPackages(String packages) { 168 includePackages = new HashSet<>(); 169 excludePackages = new HashSet<>(); 170 for (String pack : packages.split(DocLint.SEPARATOR)) { 171 boolean excluded = false; 172 if (pack.startsWith("-")) { 173 pack = pack.substring(1); 174 excluded = true; 175 } 176 if (pack.isEmpty()) 177 continue; 178 Pattern pattern = MatchingUtils.validImportStringToPattern(pack); 179 if (excluded) { 180 excludePackages.add(pattern); 181 } else { 182 includePackages.add(pattern); 183 } 184 } 185 } 186 187 static boolean validatePackages(String packages) { 188 for (String pack : packages.split(DocLint.SEPARATOR)) { 189 if (pack.startsWith("-")) { 190 pack = pack.substring(1); 191 } 192 if (!pack.isEmpty() && !MatchingUtils.isValidImportString(pack)) 193 return false; 194 } 195 return true; 196 } 197 198 void setHtmlVersion(HtmlVersion version) { 199 htmlVersion = version; 200 } 201 202 /** Set the current declaration and its doc comment. */ 203 void setCurrent(TreePath path, DocCommentTree comment) { 204 currPath = path; 205 currDocComment = comment; 206 currElement = trees.getElement(currPath); 207 currOverriddenMethods = ((JavacTypes) types).getOverriddenMethods(currElement); 208 209 AccessKind ak = AccessKind.PUBLIC; 210 for (TreePath p = path; p != null; p = p.getParentPath()) { 211 Element e = trees.getElement(p); 212 if (e != null && e.getKind() != ElementKind.PACKAGE) { 213 ak = min(ak, AccessKind.of(e.getModifiers())); 214 } 215 } 216 currAccess = ak; 217 } 218 219 AccessKind getAccessKind() { 220 return currAccess; 221 } 222 223 long getPos(TreePath p) { 224 return ((JCTree) p.getLeaf()).pos; 225 } 226 227 long getStartPos(TreePath p) { 228 SourcePositions sp = trees.getSourcePositions(); 229 return sp.getStartPosition(p.getCompilationUnit(), p.getLeaf()); 230 } 231 232 private <T extends Comparable<T>> T min(T item1, T item2) { 233 return (item1 == null) ? item2 234 : (item2 == null) ? item1 235 : item1.compareTo(item2) <= 0 ? item1 : item2; 236 } 237} 238