Env.java revision 2846:072008f47620
1/* 2 * Copyright (c) 2012, 2013, 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 // Utility classes 103 DocTrees trees; 104 Elements elements; 105 Types types; 106 107 // Types used when analysing doc comments. 108 TypeMirror java_lang_Error; 109 TypeMirror java_lang_RuntimeException; 110 TypeMirror java_lang_Throwable; 111 TypeMirror java_lang_Void; 112 113 /** The path for the declaration containing the comment currently being analyzed. */ 114 TreePath currPath; 115 /** The element for the declaration containing the comment currently being analyzed. */ 116 Element currElement; 117 /** The comment current being analyzed. */ 118 DocCommentTree currDocComment; 119 /** 120 * The access kind of the declaration containing the comment currently being analyzed. 121 * This is the minimum (most restrictive) access kind of the declaration itself 122 * and that of its containers. For example, a public method in a private class is 123 * noted as private. 124 */ 125 AccessKind currAccess; 126 /** The set of methods, if any, that the current declaration overrides. */ 127 Set<? extends ExecutableElement> currOverriddenMethods; 128 129 Env() { 130 messages = new Messages(this); 131 } 132 133 void init(JavacTask task) { 134 init(DocTrees.instance(task), task.getElements(), task.getTypes()); 135 } 136 137 void init(DocTrees trees, Elements elements, Types types) { 138 this.trees = trees; 139 this.elements = elements; 140 this.types = types; 141 } 142 143 void initTypes() { 144 if (java_lang_Error != null) 145 return ; 146 147 java_lang_Error = elements.getTypeElement("java.lang.Error").asType(); 148 java_lang_RuntimeException = elements.getTypeElement("java.lang.RuntimeException").asType(); 149 java_lang_Throwable = elements.getTypeElement("java.lang.Throwable").asType(); 150 java_lang_Void = elements.getTypeElement("java.lang.Void").asType(); 151 } 152 153 void setImplicitHeaders(int n) { 154 implicitHeaderLevel = n; 155 } 156 157 void setCustomTags(String cTags) { 158 customTags = new LinkedHashSet<>(); 159 for (String s : cTags.split(DocLint.SEPARATOR)) { 160 if (!s.isEmpty()) 161 customTags.add(s); 162 } 163 } 164 165 void setCheckPackages(String packages) { 166 includePackages = new HashSet<>(); 167 excludePackages = new HashSet<>(); 168 for (String pack : packages.split(DocLint.SEPARATOR)) { 169 boolean excluded = false; 170 if (pack.startsWith("-")) { 171 pack = pack.substring(1); 172 excluded = true; 173 } 174 if (pack.isEmpty()) 175 continue; 176 Pattern pattern = MatchingUtils.validImportStringToPattern(pack); 177 if (excluded) { 178 excludePackages.add(pattern); 179 } else { 180 includePackages.add(pattern); 181 } 182 } 183 } 184 185 static boolean validatePackages(String packages) { 186 for (String pack : packages.split(DocLint.SEPARATOR)) { 187 if (pack.startsWith("-")) { 188 pack = pack.substring(1); 189 } 190 if (!pack.isEmpty() && !MatchingUtils.isValidImportString(pack)) 191 return false; 192 } 193 return true; 194 } 195 196 /** Set the current declaration and its doc comment. */ 197 void setCurrent(TreePath path, DocCommentTree comment) { 198 currPath = path; 199 currDocComment = comment; 200 currElement = trees.getElement(currPath); 201 currOverriddenMethods = ((JavacTypes) types).getOverriddenMethods(currElement); 202 203 AccessKind ak = AccessKind.PUBLIC; 204 for (TreePath p = path; p != null; p = p.getParentPath()) { 205 Element e = trees.getElement(p); 206 if (e != null && e.getKind() != ElementKind.PACKAGE) { 207 ak = min(ak, AccessKind.of(e.getModifiers())); 208 } 209 } 210 currAccess = ak; 211 } 212 213 AccessKind getAccessKind() { 214 return currAccess; 215 } 216 217 long getPos(TreePath p) { 218 return ((JCTree) p.getLeaf()).pos; 219 } 220 221 long getStartPos(TreePath p) { 222 SourcePositions sp = trees.getSourcePositions(); 223 return sp.getStartPosition(p.getCompilationUnit(), p.getLeaf()); 224 } 225 226 private <T extends Comparable<T>> T min(T item1, T item2) { 227 return (item1 == null) ? item2 228 : (item2 == null) ? item1 229 : item1.compareTo(item2) <= 0 ? item1 : item2; 230 } 231} 232