1/* 2 * Copyright (c) 1997, 2016, 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.javadoc.main; 27 28import java.io.IOException; 29import java.util.Collection; 30import java.util.Locale; 31 32import javax.tools.JavaFileManager; 33import javax.tools.JavaFileObject; 34import javax.tools.StandardJavaFileManager; 35 36import com.sun.javadoc.*; 37import com.sun.tools.javac.tree.JCTree.JCClassDecl; 38import com.sun.tools.javac.util.List; 39import com.sun.tools.javac.util.ListBuffer; 40import com.sun.tools.javac.util.Position; 41 42/** 43 * This class holds the information from one run of javadoc. 44 * Particularly the packages, classes and options specified 45 * by the user. 46 * 47 * <p><b>This is NOT part of any supported API. 48 * If you write code that depends on this, you do so at your own risk. 49 * This code and its internal interfaces are subject to change or 50 * deletion without notice.</b> 51 * 52 * @since 1.2 53 * @author Robert Field 54 * @author Atul M Dambalkar 55 * @author Neal Gafter (rewrite) 56 */ 57@Deprecated 58public class RootDocImpl extends DocImpl implements RootDoc { 59 60 /** 61 * list of classes specified on the command line. 62 */ 63 private List<ClassDocImpl> cmdLineClasses; 64 65 /** 66 * list of packages specified on the command line. 67 */ 68 private List<PackageDocImpl> cmdLinePackages; 69 70 /** 71 * a collection of all options. 72 */ 73 private List<String[]> options; 74 75 /** 76 * Constructor used when reading source files. 77 * 78 * @param env the documentation environment, state for this javadoc run 79 * @param classes list of classes specified on the commandline 80 * @param packages list of package names specified on the commandline 81 * @param options list of options 82 */ 83 public RootDocImpl(DocEnv env, List<JCClassDecl> classes, List<String> packages, List<String[]> options) { 84 super(env, null); 85 this.options = options; 86 setPackages(env, packages); 87 setClasses(env, classes); 88 } 89 90 /** 91 * Constructor used when reading class files. 92 * 93 * @param env the documentation environment, state for this javadoc run 94 * @param classes list of class names specified on the commandline 95 * @param options list of options 96 */ 97 public RootDocImpl(DocEnv env, List<String> classes, List<String[]> options) { 98 super(env, null); 99 this.options = options; 100 cmdLinePackages = List.nil(); 101 ListBuffer<ClassDocImpl> classList = new ListBuffer<>(); 102 for (String className : classes) { 103 ClassDocImpl c = env.loadClass(className); 104 if (c == null) 105 env.error(null, "javadoc.class_not_found", className); 106 else 107 classList = classList.append(c); 108 } 109 cmdLineClasses = classList.toList(); 110 } 111 112 /** 113 * Initialize classes information. Those classes are input from 114 * command line. 115 * 116 * @param env the compilation environment 117 * @param classes a list of ClassDeclaration 118 */ 119 private void setClasses(DocEnv env, List<JCClassDecl> classes) { 120 ListBuffer<ClassDocImpl> result = new ListBuffer<>(); 121 for (JCClassDecl def : classes) { 122 //### Do we want modifier check here? 123 if (env.shouldDocument(def.sym)) { 124 ClassDocImpl cd = env.getClassDoc(def.sym); 125 if (cd != null) { 126 cd.isIncluded = true; 127 result.append(cd); 128 } //else System.out.println(" (classdoc is null)");//DEBUG 129 } //else System.out.println(" (env.shouldDocument() returned false)");//DEBUG 130 } 131 cmdLineClasses = result.toList(); 132 } 133 134 /** 135 * Initialize packages information. 136 * 137 * @param env the compilation environment 138 * @param packages a list of package names (String) 139 */ 140 private void setPackages(DocEnv env, List<String> packages) { 141 ListBuffer<PackageDocImpl> packlist = new ListBuffer<>(); 142 for (String name : packages) { 143 PackageDocImpl pkg = env.lookupPackage(name); 144 if (pkg != null) { 145 pkg.isIncluded = true; 146 packlist.append(pkg); 147 } else { 148 env.warning(null, "main.no_source_files_for_package", name); 149 } 150 } 151 cmdLinePackages = packlist.toList(); 152 } 153 154 /** 155 * Command line options. 156 * 157 * <pre> 158 * For example, given: 159 * javadoc -foo this that -bar other ... 160 * 161 * This method will return: 162 * options()[0][0] = "-foo" 163 * options()[0][1] = "this" 164 * options()[0][2] = "that" 165 * options()[1][0] = "-bar" 166 * options()[1][1] = "other" 167 * </pre> 168 * 169 * @return an array of arrays of String. 170 */ 171 public String[][] options() { 172 return options.toArray(new String[options.length()][]); 173 } 174 175 /** 176 * Packages specified on the command line. 177 */ 178 public PackageDoc[] specifiedPackages() { 179 return (PackageDoc[])cmdLinePackages 180 .toArray(new PackageDocImpl[cmdLinePackages.length()]); 181 } 182 183 /** 184 * Classes and interfaces specified on the command line. 185 */ 186 public ClassDoc[] specifiedClasses() { 187 ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<>(); 188 for (ClassDocImpl cd : cmdLineClasses) { 189 cd.addAllClasses(classesToDocument, true); 190 } 191 return (ClassDoc[])classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]); 192 } 193 194 /** 195 * Return all classes and interfaces (including those inside 196 * packages) to be documented. 197 */ 198 public ClassDoc[] classes() { 199 ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<>(); 200 for (ClassDocImpl cd : cmdLineClasses) { 201 cd.addAllClasses(classesToDocument, true); 202 } 203 for (PackageDocImpl pd : cmdLinePackages) { 204 pd.addAllClassesTo(classesToDocument); 205 } 206 return classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]); 207 } 208 209 /** 210 * Return a ClassDoc for the specified class/interface name 211 * 212 * @param qualifiedName qualified class name 213 * (i.e. includes package name). 214 * 215 * @return a ClassDocImpl holding the specified class, null if 216 * this class is not referenced. 217 */ 218 public ClassDoc classNamed(String qualifiedName) { 219 return env.lookupClass(qualifiedName); 220 } 221 222 /** 223 * Return a PackageDoc for the specified package name 224 * 225 * @param name package name 226 * 227 * @return a PackageDoc holding the specified package, null if 228 * this package is not referenced. 229 */ 230 public PackageDoc packageNamed(String name) { 231 return env.lookupPackage(name); 232 } 233 234 /** 235 * Return the name of this Doc item. 236 * 237 * @return the string <code>"*RootDocImpl*"</code>. 238 */ 239 public String name() { 240 return "*RootDocImpl*"; 241 } 242 243 /** 244 * Return the name of this Doc item. 245 * 246 * @return the string <code>"*RootDocImpl*"</code>. 247 */ 248 public String qualifiedName() { 249 return "*RootDocImpl*"; 250 } 251 252 /** 253 * Return true if this Doc is include in the active set. 254 * RootDocImpl isn't even a program entity so it is always false. 255 */ 256 public boolean isIncluded() { 257 return false; 258 } 259 260 /** 261 * Print error message, increment error count. 262 * 263 * @param msg message to print 264 */ 265 public void printError(String msg) { 266 env.printError(msg); 267 } 268 269 /** 270 * Print error message, increment error count. 271 * 272 * @param msg message to print 273 */ 274 public void printError(SourcePosition pos, String msg) { 275 env.printError(pos, msg); 276 } 277 278 /** 279 * Print warning message, increment warning count. 280 * 281 * @param msg message to print 282 */ 283 public void printWarning(String msg) { 284 env.printWarning(msg); 285 } 286 287 /** 288 * Print warning message, increment warning count. 289 * 290 * @param msg message to print 291 */ 292 public void printWarning(SourcePosition pos, String msg) { 293 env.printWarning(pos, msg); 294 } 295 296 /** 297 * Print a message. 298 * 299 * @param msg message to print 300 */ 301 public void printNotice(String msg) { 302 env.printNotice(msg); 303 } 304 305 /** 306 * Print a message. 307 * 308 * @param msg message to print 309 */ 310 public void printNotice(SourcePosition pos, String msg) { 311 env.printNotice(pos, msg); 312 } 313 314 /** 315 * Return the path of the overview file and null if it does not exist. 316 * @return the path of the overview file and null if it does not exist. 317 */ 318 private JavaFileObject getOverviewPath() { 319 for (String[] opt : options) { 320 if (opt[0].equals("-overview")) { 321 if (env.fileManager instanceof StandardJavaFileManager) { 322 StandardJavaFileManager fm = (StandardJavaFileManager) env.fileManager; 323 return fm.getJavaFileObjects(opt[1]).iterator().next(); 324 } 325 } 326 } 327 return null; 328 } 329 330 /** 331 * Do lazy initialization of "documentation" string. 332 */ 333 @Override 334 protected String documentation() { 335 if (documentation == null) { 336 JavaFileObject overviewPath = getOverviewPath(); 337 if (overviewPath == null) { 338 // no doc file to be had 339 documentation = ""; 340 } else { 341 // read from file 342 try { 343 documentation = readHTMLDocumentation( 344 overviewPath.openInputStream(), 345 overviewPath); 346 } catch (IOException exc) { 347 documentation = ""; 348 env.error(null, "javadoc.File_Read_Error", overviewPath.getName()); 349 } 350 } 351 } 352 return documentation; 353 } 354 355 /** 356 * Return the source position of the entity, or null if 357 * no position is available. 358 */ 359 @Override 360 public SourcePosition position() { 361 JavaFileObject path; 362 return ((path = getOverviewPath()) == null) ? 363 null : 364 SourcePositionImpl.make(path, Position.NOPOS, null); 365 } 366 367 /** 368 * Return the locale provided by the user or the default locale value. 369 */ 370 public Locale getLocale() { 371 return env.doclocale.locale; 372 } 373 374 /** 375 * Return the current file manager. 376 */ 377 public JavaFileManager getFileManager() { 378 return env.fileManager; 379 } 380 381 public void initDocLint(Collection<String> opts, Collection<String> customTagNames, 382 String htmlVersion) { 383 env.initDoclint(opts, customTagNames, htmlVersion); 384 } 385 386 public JavaScriptScanner initJavaScriptScanner(boolean allowScriptInComments) { 387 return env.initJavaScriptScanner(allowScriptInComments); 388 } 389 390 public boolean isFunctionalInterface(AnnotationDesc annotationDesc) { 391 return env.source.allowLambda() 392 && annotationDesc.annotationType().qualifiedName().equals( 393 env.syms.functionalInterfaceType.toString()); 394 } 395 396 public boolean showTagMessages() { 397 return env.showTagMessages(); 398 } 399} 400