1 /*
   2  * Copyright (c) 2003, 2017, 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.formats.html;
  27 
  28 import javax.lang.model.element.ExecutableElement;
  29 import javax.lang.model.element.TypeElement;
  30 import javax.lang.model.type.TypeMirror;
  31 
  32 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
  33 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
  34 import jdk.javadoc.internal.doclets.toolkit.Content;
  35 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
  36 import jdk.javadoc.internal.doclets.toolkit.util.links.LinkInfo;
  37 
  38 
  39 /**
  40  *  <p><b>This is NOT part of any supported API.
  41  *  If you write code that depends on this, you do so at your own risk.
  42  *  This code and its internal interfaces are subject to change or
  43  *  deletion without notice.</b>
  44  */
  45 public class LinkInfoImpl extends LinkInfo {
  46 
  47     public enum Kind {
  48         DEFAULT,
  49 
  50         /**
  51          * Indicate that the link appears in a class list.
  52          */
  53         ALL_CLASSES_FRAME,
  54 
  55         /**
  56          * Indicate that the link appears in a class documentation.
  57          */
  58         CLASS,
  59 
  60         /**
  61          * Indicate that the link appears in member documentation.
  62          */
  63         MEMBER,
  64 
  65         /**
  66          * Indicate that the link appears in class use documentation.
  67          */
  68         CLASS_USE,
  69 
  70         /**
  71          * Indicate that the link appears in index documentation.
  72          */
  73         INDEX,
  74 
  75         /**
  76          * Indicate that the link appears in constant value summary.
  77          */
  78         CONSTANT_SUMMARY,
  79 
  80         /**
  81          * Indicate that the link appears in serialized form documentation.
  82          */
  83         SERIALIZED_FORM,
  84 
  85         /**
  86          * Indicate that the link appears in serial member documentation.
  87          */
  88         SERIAL_MEMBER,
  89 
  90         /**
  91          * Indicate that the link appears in package documentation.
  92          */
  93         PACKAGE,
  94 
  95         /**
  96          * Indicate that the link appears in see tag documentation.
  97          */
  98         SEE_TAG,
  99 
 100         /**
 101          * Indicate that the link appears in value tag documentation.
 102          */
 103         VALUE_TAG,
 104 
 105         /**
 106          * Indicate that the link appears in tree documentation.
 107          */
 108         TREE,
 109 
 110         /**
 111          * Indicate that the link appears in a class list.
 112          */
 113         PACKAGE_FRAME,
 114 
 115         /**
 116          * The header in the class documentation.
 117          */
 118         CLASS_HEADER,
 119 
 120         /**
 121          * The signature in the class documentation.
 122          */
 123         CLASS_SIGNATURE,
 124 
 125         /**
 126          * The return type of a method.
 127          */
 128         RETURN_TYPE,
 129 
 130         /**
 131          * The return type of a method in a member summary.
 132          */
 133         SUMMARY_RETURN_TYPE,
 134 
 135         /**
 136          * The type of a method/constructor parameter.
 137          */
 138         EXECUTABLE_MEMBER_PARAM,
 139 
 140         /**
 141          * Super interface links.
 142          */
 143         SUPER_INTERFACES,
 144 
 145         /**
 146          * Implemented interface links.
 147          */
 148         IMPLEMENTED_INTERFACES,
 149 
 150         /**
 151          * Implemented class links.
 152          */
 153         IMPLEMENTED_CLASSES,
 154 
 155         /**
 156          * Subinterface links.
 157          */
 158         SUBINTERFACES,
 159 
 160         /**
 161          * Subclasses links.
 162          */
 163         SUBCLASSES,
 164 
 165         /**
 166          * The signature in the class documentation (implements/extends portion).
 167          */
 168         CLASS_SIGNATURE_PARENT_NAME,
 169 
 170         /**
 171          * The header for method documentation copied from parent.
 172          */
 173         EXECUTABLE_ELEMENT_COPY,
 174 
 175         /**
 176          * Method "specified by" link.
 177          */
 178         METHOD_SPECIFIED_BY,
 179 
 180         /**
 181          * Method "overrides" link.
 182          */
 183         METHOD_OVERRIDES,
 184 
 185         /**
 186          * Annotation link.
 187          */
 188         ANNOTATION,
 189 
 190         /**
 191          * The header for field documentation copied from parent.
 192          */
 193         VARIABLE_ELEMENT_COPY,
 194 
 195         /**
 196          * The parent nodes in the class tree.
 197          */
 198         CLASS_TREE_PARENT,
 199 
 200         /**
 201          * The type parameters of a method or constructor.
 202          */
 203         MEMBER_TYPE_PARAMS,
 204 
 205         /**
 206          * Indicate that the link appears in class use documentation.
 207          */
 208         CLASS_USE_HEADER,
 209 
 210         /**
 211          * The header for property documentation copied from parent.
 212          */
 213         PROPERTY_COPY,
 214 
 215         /**
 216          * A receiver type
 217          */
 218         RECEIVER_TYPE
 219     }
 220 
 221     public final HtmlConfiguration configuration;
 222 
 223     /**
 224      * The location of the link.
 225      */
 226     public Kind context = Kind.DEFAULT;
 227 
 228     /**
 229      * The value of the marker #.
 230      */
 231     public String where = "";
 232 
 233     /**
 234      * The value of the target.
 235      */
 236     public String target = "";
 237     public  final Utils utils;
 238     /**
 239      * Construct a LinkInfo object.
 240      *
 241      * @param configuration the configuration data for the doclet
 242      * @param context    the context of the link.
 243      * @param ee   the member to link to.
 244      */
 245     public LinkInfoImpl(HtmlConfiguration configuration, Kind context, ExecutableElement ee) {
 246         this.configuration = configuration;
 247         this.utils = configuration.utils;
 248         this.executableElement = ee;
 249         setContext(context);
 250     }
 251 
 252     /**
 253      * {@inheritDoc}
 254      */
 255     @Override
 256     protected Content newContent() {
 257         return new ContentBuilder();
 258     }
 259 
 260     /**
 261      * Construct a LinkInfo object.
 262      *
 263      * @param configuration the configuration data for the doclet
 264      * @param context    the context of the link.
 265      * @param typeElement   the class to link to.
 266      */
 267     public LinkInfoImpl(HtmlConfiguration configuration, Kind context, TypeElement typeElement) {
 268         this.configuration = configuration;
 269         this.utils = configuration.utils;
 270         this.typeElement = typeElement;
 271         setContext(context);
 272     }
 273 
 274     /**
 275      * Construct a LinkInfo object.
 276      *
 277      * @param configuration the configuration data for the doclet
 278      * @param context    the context of the link.
 279      * @param type       the class to link to.
 280      */
 281     public LinkInfoImpl(HtmlConfiguration configuration, Kind context, TypeMirror type) {
 282         this.configuration = configuration;
 283         this.utils = configuration.utils;
 284         this.type = type;
 285         setContext(context);
 286     }
 287 
 288     /**
 289      * Set the label for the link.
 290      * @param label plain-text label for the link
 291      */
 292     public LinkInfoImpl label(CharSequence label) {
 293         this.label = new StringContent(label);
 294         return this;
 295     }
 296 
 297     /**
 298      * Set the label for the link.
 299      */
 300     public LinkInfoImpl label(Content label) {
 301         this.label = label;
 302         return this;
 303     }
 304 
 305     /**
 306      * Set whether or not the link should be strong.
 307      */
 308     public LinkInfoImpl strong(boolean strong) {
 309         this.isStrong = strong;
 310         return this;
 311     }
 312 
 313     /**
 314      * Set the target to be used for the link.
 315      * @param target the target name.
 316      */
 317     public LinkInfoImpl target(String target) {
 318         this.target = target;
 319         return this;
 320     }
 321 
 322     /**
 323      * Set whether or not this is a link to a varargs parameter.
 324      */
 325     public LinkInfoImpl varargs(boolean varargs) {
 326         this.isVarArg = varargs;
 327         return this;
 328     }
 329 
 330     /**
 331      * Set the fragment specifier for the link.
 332      */
 333     public LinkInfoImpl where(String where) {
 334         this.where = where;
 335         return this;
 336      }
 337 
 338     /**
 339      * {@inheritDoc}
 340      */
 341     public Kind getContext() {
 342         return context;
 343     }
 344 
 345     /**
 346      * {@inheritDoc}
 347      *
 348      * This method sets the link attributes to the appropriate values
 349      * based on the context.
 350      *
 351      * @param c the context id to set.
 352      */
 353     public final void setContext(Kind c) {
 354         //NOTE:  Put context specific link code here.
 355         switch (c) {
 356             case ALL_CLASSES_FRAME:
 357             case PACKAGE_FRAME:
 358             case IMPLEMENTED_CLASSES:
 359             case SUBCLASSES:
 360             case EXECUTABLE_ELEMENT_COPY:
 361             case VARIABLE_ELEMENT_COPY:
 362             case PROPERTY_COPY:
 363             case CLASS_USE_HEADER:
 364                 includeTypeInClassLinkLabel = false;
 365                 break;
 366 
 367             case ANNOTATION:
 368                 excludeTypeParameterLinks = true;
 369                 excludeTypeBounds = true;
 370                 break;
 371 
 372             case IMPLEMENTED_INTERFACES:
 373             case SUPER_INTERFACES:
 374             case SUBINTERFACES:
 375             case CLASS_TREE_PARENT:
 376             case TREE:
 377             case CLASS_SIGNATURE_PARENT_NAME:
 378                 excludeTypeParameterLinks = true;
 379                 excludeTypeBounds = true;
 380                 includeTypeInClassLinkLabel = false;
 381                 includeTypeAsSepLink = true;
 382                 break;
 383 
 384             case PACKAGE:
 385             case CLASS_USE:
 386             case CLASS_HEADER:
 387             case CLASS_SIGNATURE:
 388             case RECEIVER_TYPE:
 389                 excludeTypeParameterLinks = true;
 390                 includeTypeAsSepLink = true;
 391                 includeTypeInClassLinkLabel = false;
 392                 break;
 393 
 394             case MEMBER_TYPE_PARAMS:
 395                 includeTypeAsSepLink = true;
 396                 includeTypeInClassLinkLabel = false;
 397                 break;
 398 
 399             case RETURN_TYPE:
 400             case SUMMARY_RETURN_TYPE:
 401                 excludeTypeBounds = true;
 402                 break;
 403             case EXECUTABLE_MEMBER_PARAM:
 404                 excludeTypeBounds = true;
 405                 break;
 406         }
 407         context = c;
 408         if (type != null &&
 409             utils.isTypeVariable(type) &&
 410             utils.isExecutableElement(utils.asTypeElement(type).getEnclosingElement())) {
 411                 excludeTypeParameterLinks = true;
 412         }
 413     }
 414 
 415     /**
 416      * Return true if this link is linkable and false if we can't link to the
 417      * desired place.
 418      *
 419      * @return true if this link is linkable and false if we can't link to the
 420      * desired place.
 421      */
 422     @Override
 423     public boolean isLinkable() {
 424         return configuration.utils.isLinkable(typeElement);
 425     }
 426 
 427     @Override
 428     public String toString() {
 429         return "LinkInfoImpl{" +
 430                 "context=" + context +
 431                 ", where=" + where +
 432                 ", target=" + target +
 433                 super.toString() + '}';
 434     }
 435 }