1 /*
   2  * Copyright (c) 2015, 2019, 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 
  26 package jdk.javadoc.internal.doclets.toolkit;
  27 
  28 import java.util.ArrayList;
  29 import java.util.Arrays;
  30 import java.util.Collection;
  31 import java.util.HashMap;
  32 import java.util.List;
  33 import java.util.Map;
  34 import java.util.SortedSet;
  35 import java.util.TreeSet;
  36 
  37 import javax.lang.model.element.AnnotationMirror;
  38 import javax.lang.model.element.Element;
  39 import javax.lang.model.element.ExecutableElement;
  40 import javax.lang.model.element.ModuleElement;
  41 import javax.lang.model.element.PackageElement;
  42 import javax.lang.model.element.TypeElement;
  43 import javax.lang.model.element.VariableElement;
  44 import javax.lang.model.type.TypeMirror;
  45 import javax.lang.model.util.Elements;
  46 import javax.tools.FileObject;
  47 import javax.tools.JavaFileManager.Location;
  48 
  49 import com.sun.source.tree.CompilationUnitTree;
  50 import com.sun.source.util.JavacTask;
  51 import com.sun.source.util.TreePath;
  52 import com.sun.tools.doclint.DocLint;
  53 import com.sun.tools.javac.api.BasicJavacTask;
  54 import com.sun.tools.javac.code.Attribute;
  55 import com.sun.tools.javac.code.Flags;
  56 import com.sun.tools.javac.code.Scope;
  57 import com.sun.tools.javac.code.Source.Feature;
  58 import com.sun.tools.javac.code.Symbol;
  59 import com.sun.tools.javac.code.Symbol.ClassSymbol;
  60 import com.sun.tools.javac.code.Symbol.MethodSymbol;
  61 import com.sun.tools.javac.code.Symbol.ModuleSymbol;
  62 import com.sun.tools.javac.code.Symbol.PackageSymbol;
  63 import com.sun.tools.javac.code.Symbol.VarSymbol;
  64 import com.sun.tools.javac.code.TypeTag;
  65 import com.sun.tools.javac.comp.AttrContext;
  66 import com.sun.tools.javac.comp.Env;
  67 import com.sun.tools.javac.model.JavacElements;
  68 import com.sun.tools.javac.model.JavacTypes;
  69 import com.sun.tools.javac.util.Names;
  70 
  71 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
  72 import jdk.javadoc.internal.tool.ToolEnvironment;
  73 import jdk.javadoc.internal.tool.DocEnvImpl;
  74 
  75 import static com.sun.tools.javac.code.Kinds.Kind.*;
  76 import static com.sun.tools.javac.code.Scope.LookupKind.NON_RECURSIVE;
  77 
  78 import static javax.lang.model.element.ElementKind.*;
  79 
  80 /**
  81  * A quarantine class to isolate all the workarounds and bridges to
  82  * a locality. This class should eventually disappear once all the
  83  * standard APIs support the needed interfaces.
  84  *
  85  *
  86  *  <p><b>This is NOT part of any supported API.
  87  *  If you write code that depends on this, you do so at your own risk.
  88  *  This code and its internal interfaces are subject to change or
  89  *  deletion without notice.</b>
  90  */
  91 public class WorkArounds {
  92 
  93     public final BaseConfiguration configuration;
  94     public final ToolEnvironment toolEnv;
  95     public final Utils utils;
  96 
  97     private DocLint doclint;
  98 
  99     public WorkArounds(BaseConfiguration configuration) {
 100         this.configuration = configuration;
 101         this.utils = this.configuration.utils;
 102         this.toolEnv = ((DocEnvImpl)this.configuration.docEnv).toolEnv;
 103     }
 104 
 105     Map<CompilationUnitTree, Boolean> shouldCheck = new HashMap<>();
 106     // TODO: fix this up correctly
 107     public void runDocLint(TreePath path) {
 108         CompilationUnitTree unit = path.getCompilationUnit();
 109         if (doclint != null && shouldCheck.computeIfAbsent(unit, doclint::shouldCheck)) {
 110             doclint.scan(path);
 111         }
 112     }
 113 
 114     // TODO: fix this up correctly
 115     public void initDocLint(Collection<String> opts, Collection<String> customTagNames) {
 116         ArrayList<String> doclintOpts = new ArrayList<>();
 117         boolean msgOptionSeen = false;
 118 
 119         for (String opt : opts) {
 120             if (opt.startsWith(DocLint.XMSGS_OPTION)) {
 121                 if (opt.equals(DocLint.XMSGS_CUSTOM_PREFIX + "none"))
 122                     return;
 123                 msgOptionSeen = true;
 124             }
 125             doclintOpts.add(opt);
 126         }
 127 
 128         if (!msgOptionSeen) {
 129             doclintOpts.add(DocLint.XMSGS_OPTION);
 130         }
 131 
 132         String sep = "";
 133         StringBuilder customTags = new StringBuilder();
 134         for (String customTag : customTagNames) {
 135             customTags.append(sep);
 136             customTags.append(customTag);
 137             sep = DocLint.SEPARATOR;
 138         }
 139         doclintOpts.add(DocLint.XCUSTOM_TAGS_PREFIX + customTags.toString());
 140         doclintOpts.add(DocLint.XHTML_VERSION_PREFIX + "html5");
 141 
 142         JavacTask t = BasicJavacTask.instance(toolEnv.context);
 143         doclint = new DocLint();
 144         doclint.init(t, doclintOpts.toArray(new String[doclintOpts.size()]), false);
 145     }
 146 
 147     // TODO: fix this up correctly
 148     public boolean haveDocLint() {
 149         return (doclint == null);
 150     }
 151 
 152     /*
 153      * TODO: This method exists because of a bug in javac which does not
 154      * handle "@deprecated tag in package-info.java", when this issue
 155      * is fixed this method and its uses must be jettisoned.
 156      */
 157     public boolean isDeprecated0(Element e) {
 158         if (!utils.getDeprecatedTrees(e).isEmpty()) {
 159             return true;
 160         }
 161         JavacTypes jctypes = ((DocEnvImpl)configuration.docEnv).toolEnv.typeutils;
 162         TypeMirror deprecatedType = utils.getDeprecatedType();
 163         for (AnnotationMirror anno : e.getAnnotationMirrors()) {
 164             if (jctypes.isSameType(anno.getAnnotationType().asElement().asType(), deprecatedType))
 165                 return true;
 166         }
 167         return false;
 168     }
 169 
 170     // TODO: fix jx.l.m add this method.
 171     public boolean isSynthesized(AnnotationMirror aDesc) {
 172         return ((Attribute)aDesc).isSynthesized();
 173     }
 174 
 175     // TODO: fix the caller
 176     public Object getConstValue(VariableElement ve) {
 177         return ((VarSymbol)ve).getConstValue();
 178     }
 179 
 180     // TODO: DocTrees: Trees.getPath(Element e) is slow a factor 4-5 times.
 181     public Map<Element, TreePath> getElementToTreePath() {
 182         return toolEnv.elementToTreePath;
 183     }
 184 
 185     // TODO: we need ElementUtils.getPackage to cope with input strings
 186     // to return the proper unnamedPackage for all supported releases.
 187     PackageElement getUnnamedPackage() {
 188         return (Feature.MODULES.allowedInSource(toolEnv.source))
 189                 ? toolEnv.syms.unnamedModule.unnamedPackage
 190                 : toolEnv.syms.noModule.unnamedPackage;
 191     }
 192 
 193     // TODO: implement in either jx.l.m API (preferred) or DocletEnvironment.
 194     FileObject getJavaFileObject(PackageElement packageElement) {
 195         return ((PackageSymbol)packageElement).sourcefile;
 196     }
 197 
 198     // TODO: needs to ported to jx.l.m.
 199     public TypeElement searchClass(TypeElement klass, String className) {
 200         TypeElement te;
 201 
 202         // search by qualified name in current module first
 203         ModuleElement me = utils.containingModule(klass);
 204         if (me != null) {
 205             te = configuration.docEnv.getElementUtils().getTypeElement(me, className);
 206             if (te != null) {
 207                 return te;
 208             }
 209         }
 210 
 211         // search inner classes
 212         for (TypeElement ite : utils.getClasses(klass)) {
 213             TypeElement innerClass = searchClass(ite, className);
 214             if (innerClass != null) {
 215                 return innerClass;
 216             }
 217         }
 218 
 219         // check in this package
 220         te = utils.findClassInPackageElement(utils.containingPackage(klass), className);
 221         if (te != null) {
 222             return te;
 223         }
 224 
 225         ClassSymbol tsym = (ClassSymbol)klass;
 226         // make sure that this symbol has been completed
 227         // TODO: do we need this anymore ?
 228         if (tsym.completer != null) {
 229             tsym.complete();
 230         }
 231 
 232         // search imports
 233         if (tsym.sourcefile != null) {
 234 
 235             //### This information is available only for source classes.
 236             Env<AttrContext> compenv = toolEnv.getEnv(tsym);
 237             if (compenv == null) {
 238                 return null;
 239             }
 240             Names names = tsym.name.table.names;
 241             Scope s = compenv.toplevel.namedImportScope;
 242             for (Symbol sym : s.getSymbolsByName(names.fromString(className))) {
 243                 if (sym.kind == TYP) {
 244                     return (TypeElement)sym;
 245                 }
 246             }
 247 
 248             s = compenv.toplevel.starImportScope;
 249             for (Symbol sym : s.getSymbolsByName(names.fromString(className))) {
 250                 if (sym.kind == TYP) {
 251                     return (TypeElement)sym;
 252                 }
 253             }
 254         }
 255 
 256         // finally, search by qualified name in all modules
 257         te = configuration.docEnv.getElementUtils().getTypeElement(className);
 258         if (te != null) {
 259             return te;
 260         }
 261 
 262         return null; // not found
 263     }
 264 
 265     // TODO:  need to re-implement this using j.l.m. correctly!, this has
 266     // implications on testInterface, the note here is that javac's supertype
 267     // does the right thing returning Parameters in scope.
 268     /**
 269      * Return the type containing the method that this method overrides.
 270      * It may be a <code>TypeElement</code> or a <code>TypeParameterElement</code>.
 271      * @param method target
 272      * @return a type
 273      */
 274     public TypeMirror overriddenType(ExecutableElement method) {
 275         if (utils.isStatic(method)) {
 276             return null;
 277         }
 278         MethodSymbol sym = (MethodSymbol)method;
 279         ClassSymbol origin = (ClassSymbol) sym.owner;
 280         for (com.sun.tools.javac.code.Type t = toolEnv.getTypes().supertype(origin.type);
 281                 t.hasTag(TypeTag.CLASS);
 282                 t = toolEnv.getTypes().supertype(t)) {
 283             ClassSymbol c = (ClassSymbol) t.tsym;
 284             for (com.sun.tools.javac.code.Symbol sym2 : c.members().getSymbolsByName(sym.name)) {
 285                 if (sym.overrides(sym2, origin, toolEnv.getTypes(), true)) {
 286                     // Ignore those methods that may be a simple override
 287                     // and allow the real API method to be found.
 288                     if (sym2.type.hasTag(TypeTag.METHOD) &&
 289                             utils.isSimpleOverride((MethodSymbol)sym2)) {
 290                         continue;
 291                     }
 292                     return t;
 293                 }
 294             }
 295         }
 296         return null;
 297     }
 298 
 299     // TODO: the method jx.l.m.Elements::overrides does not check
 300     // the return type, see JDK-8174840 until that is resolved,
 301     // use a  copy of the same method, with a return type check.
 302 
 303     // Note: the rider.overrides call in this method *must* be consistent
 304     // with the call in overrideType(....), the method above.
 305     public boolean overrides(ExecutableElement e1, ExecutableElement e2, TypeElement cls) {
 306         MethodSymbol rider = (MethodSymbol)e1;
 307         MethodSymbol ridee = (MethodSymbol)e2;
 308         ClassSymbol origin = (ClassSymbol)cls;
 309 
 310         return rider.name == ridee.name &&
 311 
 312                // not reflexive as per JLS
 313                rider != ridee &&
 314 
 315                // we don't care if ridee is static, though that wouldn't
 316                // compile
 317                !rider.isStatic() &&
 318 
 319                // Symbol.overrides assumes the following
 320                ridee.isMemberOf(origin, toolEnv.getTypes()) &&
 321 
 322                // check access, signatures and check return types
 323                rider.overrides(ridee, origin, toolEnv.getTypes(), true);
 324     }
 325 
 326     // TODO: jx.l.m ?
 327     public Location getLocationForModule(ModuleElement mdle) {
 328         ModuleSymbol msym = (ModuleSymbol)mdle;
 329         return msym.sourceLocation != null
 330                 ? msym.sourceLocation
 331                 : msym.classLocation;
 332     }
 333 
 334     //------------------Start of Serializable Implementation---------------------//
 335     private final static Map<TypeElement, NewSerializedForm> serializedForms = new HashMap<>();
 336 
 337     public SortedSet<VariableElement> getSerializableFields(Utils utils, TypeElement klass) {
 338         NewSerializedForm sf = serializedForms.get(klass);
 339         if (sf == null) {
 340             sf = new NewSerializedForm(utils, configuration.docEnv.getElementUtils(), klass);
 341             serializedForms.put(klass, sf);
 342         }
 343         return sf.fields;
 344     }
 345 
 346     public SortedSet<ExecutableElement>  getSerializationMethods(Utils utils, TypeElement klass) {
 347         NewSerializedForm sf = serializedForms.get(klass);
 348         if (sf == null) {
 349             sf = new NewSerializedForm(utils, configuration.docEnv.getElementUtils(), klass);
 350             serializedForms.put(klass, sf);
 351         }
 352         return sf.methods;
 353     }
 354 
 355     public boolean definesSerializableFields(Utils utils, TypeElement klass) {
 356         if (!utils.isSerializable(klass) || utils.isExternalizable(klass)) {
 357             return false;
 358         } else {
 359             NewSerializedForm sf = serializedForms.get(klass);
 360             if (sf == null) {
 361                 sf = new NewSerializedForm(utils, configuration.docEnv.getElementUtils(), klass);
 362                 serializedForms.put(klass, sf);
 363             }
 364             return sf.definesSerializableFields;
 365         }
 366     }
 367 
 368     /* TODO we need a clean port to jx.l.m
 369      * The serialized form is the specification of a class' serialization state.
 370      * <p>
 371      *
 372      * It consists of the following information:
 373      * <p>
 374      *
 375      * <pre>
 376      * 1. Whether class is Serializable or Externalizable.
 377      * 2. Javadoc for serialization methods.
 378      *    a. For Serializable, the optional readObject, writeObject,
 379      *       readResolve and writeReplace.
 380      *       serialData tag describes, in prose, the sequence and type
 381      *       of optional data written by writeObject.
 382      *    b. For Externalizable, writeExternal and readExternal.
 383      *       serialData tag describes, in prose, the sequence and type
 384      *       of optional data written by writeExternal.
 385      * 3. Javadoc for serialization data layout.
 386      *    a. For Serializable, the name,type and description
 387      *       of each Serializable fields.
 388      *    b. For Externalizable, data layout is described by 2(b).
 389      * </pre>
 390      *
 391      */
 392     static class NewSerializedForm {
 393 
 394         final Utils utils;
 395         final Elements elements;
 396 
 397         final SortedSet<ExecutableElement> methods;
 398 
 399         /* List of FieldDocImpl - Serializable fields.
 400          * Singleton list if class defines Serializable fields explicitly.
 401          * Otherwise, list of default serializable fields.
 402          * 0 length list for Externalizable.
 403          */
 404         final SortedSet<VariableElement> fields;
 405 
 406         /* True if class specifies serializable fields explicitly.
 407          * using special static member, serialPersistentFields.
 408          */
 409         boolean definesSerializableFields = false;
 410 
 411         // Specially treated field/method names defined by Serialization.
 412         private static final String SERIALIZABLE_FIELDS = "serialPersistentFields";
 413         private static final String READOBJECT = "readObject";
 414         private static final String WRITEOBJECT = "writeObject";
 415         private static final String READRESOLVE = "readResolve";
 416         private static final String WRITEREPLACE = "writeReplace";
 417         private static final String READOBJECTNODATA = "readObjectNoData";
 418 
 419         NewSerializedForm(Utils utils, Elements elements, TypeElement te) {
 420             this.utils = utils;
 421             this.elements = elements;
 422             methods = new TreeSet<>(utils.makeGeneralPurposeComparator());
 423             fields = new TreeSet<>(utils.makeGeneralPurposeComparator());
 424             if (utils.isExternalizable(te)) {
 425                 /* look up required public accessible methods,
 426                  *   writeExternal and readExternal.
 427                  */
 428                 String[] readExternalParamArr = {"java.io.ObjectInput"};
 429                 String[] writeExternalParamArr = {"java.io.ObjectOutput"};
 430 
 431                 ExecutableElement md = findMethod(te, "readExternal", Arrays.asList(readExternalParamArr));
 432                 if (md != null) {
 433                     methods.add(md);
 434                 }
 435                 md = findMethod((ClassSymbol) te, "writeExternal", Arrays.asList(writeExternalParamArr));
 436                 if (md != null) {
 437                     methods.add(md);
 438                 }
 439             } else if (utils.isSerializable(te)) {
 440                 VarSymbol dsf = getDefinedSerializableFields((ClassSymbol) te);
 441                 if (dsf != null) {
 442                     /* Define serializable fields with array of ObjectStreamField.
 443                      * Each ObjectStreamField should be documented by a
 444                      * serialField tag.
 445                      */
 446                     definesSerializableFields = true;
 447                     fields.add((VariableElement) dsf);
 448                 } else {
 449 
 450                     /* Calculate default Serializable fields as all
 451                      * non-transient, non-static fields.
 452                      * Fields should be documented by serial tag.
 453                      */
 454                     computeDefaultSerializableFields((ClassSymbol) te);
 455                 }
 456 
 457                 /* Check for optional customized readObject, writeObject,
 458                  * readResolve and writeReplace, which can all contain
 459                  * the serialData tag.        */
 460                 addMethodIfExist((ClassSymbol) te, READOBJECT);
 461                 addMethodIfExist((ClassSymbol) te, WRITEOBJECT);
 462                 addMethodIfExist((ClassSymbol) te, READRESOLVE);
 463                 addMethodIfExist((ClassSymbol) te, WRITEREPLACE);
 464                 addMethodIfExist((ClassSymbol) te, READOBJECTNODATA);
 465             }
 466         }
 467 
 468         private VarSymbol getDefinedSerializableFields(ClassSymbol def) {
 469             Names names = def.name.table.names;
 470 
 471             /* SERIALIZABLE_FIELDS can be private,
 472              */
 473             for (Symbol sym : def.members().getSymbolsByName(names.fromString(SERIALIZABLE_FIELDS))) {
 474                 if (sym.kind == VAR) {
 475                     VarSymbol f = (VarSymbol) sym;
 476                     if ((f.flags() & Flags.STATIC) != 0
 477                             && (f.flags() & Flags.PRIVATE) != 0) {
 478                         return f;
 479                     }
 480                 }
 481             }
 482             return null;
 483         }
 484 
 485         /*
 486          * Catalog Serializable method if it exists in current ClassSymbol.
 487          * Do not look for method in superclasses.
 488          *
 489          * Serialization requires these methods to be non-static.
 490          *
 491          * @param method should be an unqualified Serializable method
 492          *               name either READOBJECT, WRITEOBJECT, READRESOLVE
 493          *               or WRITEREPLACE.
 494          * @param visibility the visibility flag for the given method.
 495          */
 496         private void addMethodIfExist(ClassSymbol def, String methodName) {
 497             Names names = def.name.table.names;
 498 
 499             for (Symbol sym : def.members().getSymbolsByName(names.fromString(methodName))) {
 500                 if (sym.kind == MTH) {
 501                     MethodSymbol md = (MethodSymbol) sym;
 502                     if ((md.flags() & Flags.STATIC) == 0) {
 503                         /*
 504                          * WARNING: not robust if unqualifiedMethodName is overloaded
 505                          *          method. Signature checking could make more robust.
 506                          * READOBJECT takes a single parameter, java.io.ObjectInputStream.
 507                          * WRITEOBJECT takes a single parameter, java.io.ObjectOutputStream.
 508                          */
 509                         methods.add(md);
 510                     }
 511                 }
 512             }
 513         }
 514 
 515         /*
 516          * Compute default Serializable fields from all members of ClassSymbol.
 517          *
 518          * must walk over all members of ClassSymbol.
 519          */
 520         private void computeDefaultSerializableFields(ClassSymbol te) {
 521             for (Symbol sym : te.members().getSymbols(NON_RECURSIVE)) {
 522                 if (sym != null && sym.kind == VAR) {
 523                     VarSymbol f = (VarSymbol) sym;
 524                     if ((f.flags() & Flags.STATIC) == 0
 525                             && (f.flags() & Flags.TRANSIENT) == 0) {
 526                         //### No modifier filtering applied here.
 527                         //### Add to beginning.
 528                         //### Preserve order used by old 'javadoc'.
 529                         fields.add(f);
 530                     }
 531                 }
 532             }
 533         }
 534 
 535         /**
 536          * Find a method in this class scope. Search order: this class, interfaces, superclasses,
 537          * outerclasses. Note that this is not necessarily what the compiler would do!
 538          *
 539          * @param methodName the unqualified name to search for.
 540          * @param paramTypes the array of Strings for method parameter types.
 541          * @return the first MethodDocImpl which matches, null if not found.
 542          */
 543         public ExecutableElement findMethod(TypeElement te, String methodName,
 544                 List<String> paramTypes) {
 545             List<? extends Element> allMembers = this.elements.getAllMembers(te);
 546             loop:
 547             for (Element e : allMembers) {
 548                 if (e.getKind() != METHOD) {
 549                     continue;
 550                 }
 551                 ExecutableElement ee = (ExecutableElement) e;
 552                 if (!ee.getSimpleName().contentEquals(methodName)) {
 553                     continue;
 554                 }
 555                 List<? extends VariableElement> parameters = ee.getParameters();
 556                 if (paramTypes.size() != parameters.size()) {
 557                     continue;
 558                 }
 559                 for (int i = 0; i < parameters.size(); i++) {
 560                     VariableElement ve = parameters.get(i);
 561                     if (!ve.asType().toString().equals(paramTypes.get(i))) {
 562                         break loop;
 563                     }
 564                 }
 565                 return ee;
 566             }
 567             TypeElement encl = utils.getEnclosingTypeElement(te);
 568             if (encl == null) {
 569                 return null;
 570             }
 571             return findMethod(encl, methodName, paramTypes);
 572         }
 573     }
 574 
 575     // TODO: we need to eliminate this, as it is hacky.
 576     /**
 577      * Returns a representation of the package truncated to two levels.
 578      * For instance if the given package represents foo.bar.baz will return
 579      * a representation of foo.bar
 580      * @param pkg the PackageElement
 581      * @return an abbreviated PackageElement
 582      */
 583     public PackageElement getAbbreviatedPackageElement(PackageElement pkg) {
 584         String parsedPackageName = utils.parsePackageName(pkg);
 585         ModuleElement encl = (ModuleElement) pkg.getEnclosingElement();
 586         PackageElement abbrevPkg = encl == null
 587                 ? utils.elementUtils.getPackageElement(parsedPackageName)
 588                 : ((JavacElements) utils.elementUtils).getPackageElement(encl, parsedPackageName);
 589         return abbrevPkg;
 590     }
 591 }