1 /*
   2  * Copyright (c) 2003, 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.formats.html;
  27 
  28 import java.util.ArrayList;
  29 import java.util.List;
  30 
  31 import javax.lang.model.element.AnnotationMirror;
  32 import javax.lang.model.element.Element;
  33 import javax.lang.model.element.TypeElement;
  34 import javax.lang.model.type.DeclaredType;
  35 import javax.lang.model.type.TypeMirror;
  36 
  37 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
  38 import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
  39 import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
  40 import jdk.javadoc.internal.doclets.toolkit.Content;
  41 import jdk.javadoc.internal.doclets.toolkit.Resources;
  42 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
  43 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
  44 import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
  45 import jdk.javadoc.internal.doclets.toolkit.util.links.LinkFactory;
  46 import jdk.javadoc.internal.doclets.toolkit.util.links.LinkInfo;
  47 
  48 /**
  49  * A factory that returns a link given the information about it.
  50  *
  51  *  <p><b>This is NOT part of any supported API.
  52  *  If you write code that depends on this, you do so at your own risk.
  53  *  This code and its internal interfaces are subject to change or
  54  *  deletion without notice.</b>
  55  *
  56  * @author Jamie Ho
  57  */
  58 public class LinkFactoryImpl extends LinkFactory {
  59 
  60     private final HtmlDocletWriter m_writer;
  61     private final DocPaths docPaths;
  62 
  63     public LinkFactoryImpl(HtmlDocletWriter writer) {
  64         super(writer.configuration.utils);
  65         m_writer = writer;
  66         docPaths = writer.configuration.docPaths;
  67     }
  68 
  69     /**
  70      * {@inheritDoc}
  71      */
  72     @Override
  73     protected Content newContent() {
  74         return new ContentBuilder();
  75     }
  76 
  77     /**
  78      * {@inheritDoc}
  79      */
  80     @Override
  81     protected Content getClassLink(LinkInfo linkInfo) {
  82         BaseConfiguration configuration = m_writer.configuration;
  83         LinkInfoImpl classLinkInfo = (LinkInfoImpl) linkInfo;
  84         boolean noLabel = linkInfo.label == null || linkInfo.label.isEmpty();
  85         TypeElement typeElement = classLinkInfo.typeElement;
  86         // Create a tool tip if we are linking to a class or interface.  Don't
  87         // create one if we are linking to a member.
  88         String title = "";
  89         if (classLinkInfo.where == null || classLinkInfo.where.length() == 0) {
  90             boolean isTypeLink = classLinkInfo.type != null &&
  91                      utils.isTypeVariable(utils.getComponentType(classLinkInfo.type));
  92             title = getClassToolTip(typeElement, isTypeLink);
  93         }
  94         Content label = classLinkInfo.getClassLinkLabel(configuration);
  95 
  96         Content link = new ContentBuilder();
  97         if (utils.isIncluded(typeElement)) {
  98             if (configuration.isGeneratedDoc(typeElement)) {
  99                 DocPath filename = getPath(classLinkInfo);
 100                 if (linkInfo.linkToSelf ||
 101                                 !(docPaths.forName(typeElement)).equals(m_writer.filename)) {
 102                         link.add(m_writer.links.createLink(
 103                                 filename.fragment(classLinkInfo.where),
 104                                 label,
 105                                 classLinkInfo.isStrong,
 106                                 title,
 107                                 classLinkInfo.target));
 108                         if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
 109                             link.add(getTypeParameterLinks(linkInfo));
 110                         }
 111                         return link;
 112                 }
 113             }
 114         } else {
 115             Content crossLink = m_writer.getCrossClassLink(
 116                 typeElement, classLinkInfo.where,
 117                 label, classLinkInfo.isStrong, true);
 118             if (crossLink != null) {
 119                 link.add(crossLink);
 120                 if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
 121                     link.add(getTypeParameterLinks(linkInfo));
 122                 }
 123                 return link;
 124             }
 125         }
 126         // Can't link so just write label.
 127         link.add(label);
 128         if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
 129             link.add(getTypeParameterLinks(linkInfo));
 130         }
 131         return link;
 132     }
 133 
 134     /**
 135      * {@inheritDoc}
 136      */
 137     @Override
 138     protected Content getTypeParameterLinks(LinkInfo linkInfo, boolean isClassLabel) {
 139         Content links = newContent();
 140         List<TypeMirror> vars = new ArrayList<>();
 141         TypeMirror ctype = linkInfo.type != null
 142                 ? utils.getComponentType(linkInfo.type)
 143                 : null;
 144         if (linkInfo.executableElement != null) {
 145             linkInfo.executableElement.getTypeParameters().stream().forEach((t) -> {
 146                 vars.add(t.asType());
 147             });
 148         } else if (linkInfo.type != null && utils.isDeclaredType(linkInfo.type)) {
 149             ((DeclaredType)linkInfo.type).getTypeArguments().stream().forEach(vars::add);
 150         } else if (ctype != null && utils.isDeclaredType(ctype)) {
 151             ((DeclaredType)ctype).getTypeArguments().stream().forEach(vars::add);
 152         } else if (linkInfo.typeElement != null) {
 153             linkInfo.typeElement.getTypeParameters().stream().forEach((t) -> {
 154                 vars.add(t.asType());
 155             });
 156         } else {
 157             // Nothing to document.
 158             return links;
 159         }
 160         if (((linkInfo.includeTypeInClassLinkLabel && isClassLabel)
 161                 || (linkInfo.includeTypeAsSepLink && !isClassLabel)) && !vars.isEmpty()) {
 162             links.add("<");
 163             boolean many = false;
 164             for (TypeMirror t : vars) {
 165                 if (many) {
 166                     links.add(",");
 167                     links.add(Entity.ZERO_WIDTH_SPACE);
 168                     if (((LinkInfoImpl) linkInfo).getContext() == LinkInfoImpl.Kind.MEMBER_TYPE_PARAMS) {
 169                         links.add(DocletConstants.NL);
 170                     }
 171                 }
 172                 links.add(getTypeParameterLink(linkInfo, t));
 173                 many = true;
 174             }
 175             links.add(">");
 176         }
 177         return links;
 178     }
 179 
 180     /**
 181      * Returns a link to the given type parameter.
 182      *
 183      * @param linkInfo     the information about the link to construct
 184      * @param typeParam the type parameter to link to
 185      * @return the link
 186      */
 187     protected Content getTypeParameterLink(LinkInfo linkInfo, TypeMirror typeParam) {
 188         LinkInfoImpl typeLinkInfo = new LinkInfoImpl(m_writer.configuration,
 189                 ((LinkInfoImpl) linkInfo).getContext(), typeParam);
 190         typeLinkInfo.excludeTypeBounds = linkInfo.excludeTypeBounds;
 191         typeLinkInfo.excludeTypeParameterLinks = linkInfo.excludeTypeParameterLinks;
 192         typeLinkInfo.linkToSelf = linkInfo.linkToSelf;
 193         return getLink(typeLinkInfo);
 194     }
 195 
 196     @Override
 197     public Content getTypeAnnotationLinks(LinkInfo linkInfo) {
 198         ContentBuilder links = new ContentBuilder();
 199         List<? extends AnnotationMirror> annotations;
 200         if (utils.isAnnotated(linkInfo.type)) {
 201             annotations = linkInfo.type.getAnnotationMirrors();
 202         } else if (utils.isTypeVariable(linkInfo.type)) {
 203             // TODO: use the context for now, and special case for Receiver_Types,
 204             // which takes the default case.
 205             switch (((LinkInfoImpl)linkInfo).context) {
 206                 case MEMBER_TYPE_PARAMS:
 207                 case EXECUTABLE_MEMBER_PARAM:
 208                 case CLASS_SIGNATURE:
 209                     Element element = utils.typeUtils.asElement(linkInfo.type);
 210                     annotations = element.getAnnotationMirrors();
 211                     break;
 212                 default:
 213                     annotations = linkInfo.type.getAnnotationMirrors();
 214                     break;
 215             }
 216 
 217         } else {
 218             return links;
 219         }
 220 
 221         if (annotations.isEmpty())
 222             return links;
 223 
 224         List<Content> annos = m_writer.getAnnotations(annotations, false);
 225 
 226         boolean isFirst = true;
 227         for (Content anno : annos) {
 228             if (!isFirst) {
 229                 links.add(" ");
 230             }
 231             links.add(anno);
 232             isFirst = false;
 233         }
 234         if (!annos.isEmpty()) {
 235             links.add(" ");
 236         }
 237 
 238         return links;
 239     }
 240 
 241     /**
 242      * Given a class, return the appropriate tool tip.
 243      *
 244      * @param typeElement the class to get the tool tip for.
 245      * @return the tool tip for the appropriate class.
 246      */
 247     private String getClassToolTip(TypeElement typeElement, boolean isTypeLink) {
 248         Resources resources = m_writer.configuration.getResources();
 249         if (isTypeLink) {
 250             return resources.getText("doclet.Href_Type_Param_Title",
 251                     utils.getSimpleName(typeElement));
 252         } else if (utils.isInterface(typeElement)){
 253             return resources.getText("doclet.Href_Interface_Title",
 254                 utils.getPackageName(utils.containingPackage(typeElement)));
 255         } else if (utils.isAnnotationType(typeElement)) {
 256             return resources.getText("doclet.Href_Annotation_Title",
 257                 utils.getPackageName(utils.containingPackage(typeElement)));
 258         } else if (utils.isEnum(typeElement)) {
 259             return resources.getText("doclet.Href_Enum_Title",
 260                 utils.getPackageName(utils.containingPackage(typeElement)));
 261         } else {
 262             return resources.getText("doclet.Href_Class_Title",
 263                 utils.getPackageName(utils.containingPackage(typeElement)));
 264         }
 265     }
 266 
 267     /**
 268      * Return path to the given file name in the given package. So if the name
 269      * passed is "Object.html" and the name of the package is "java.lang", and
 270      * if the relative path is "../.." then returned string will be
 271      * "../../java/lang/Object.html"
 272      *
 273      * @param linkInfo the information about the link.
 274      */
 275     private DocPath getPath(LinkInfoImpl linkInfo) {
 276         if (linkInfo.context == LinkInfoImpl.Kind.PACKAGE_FRAME) {
 277             //Not really necessary to do this but we want to be consistent
 278             //with 1.4.2 output.
 279             return docPaths.forName(linkInfo.typeElement);
 280         }
 281         return m_writer.pathToRoot.resolve(docPaths.forClass(linkInfo.typeElement));
 282     }
 283 }