1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/classes/com/sun/tools/doclets/formats/html/AbstractExecutableMemberWriter.java Wed Apr 27 01:34:52 2016 +0800 1.3 @@ -0,0 +1,310 @@ 1.4 +/* 1.5 + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 +package com.sun.tools.doclets.formats.html; 1.30 + 1.31 +import com.sun.javadoc.*; 1.32 +import com.sun.tools.doclets.formats.html.markup.*; 1.33 +import com.sun.tools.doclets.internal.toolkit.*; 1.34 +import com.sun.tools.doclets.internal.toolkit.util.*; 1.35 + 1.36 +/** 1.37 + * Print method and constructor info. 1.38 + * 1.39 + * <p><b>This is NOT part of any supported API. 1.40 + * If you write code that depends on this, you do so at your own risk. 1.41 + * This code and its internal interfaces are subject to change or 1.42 + * deletion without notice.</b> 1.43 + * 1.44 + * @author Robert Field 1.45 + * @author Atul M Dambalkar 1.46 + * @author Bhavesh Patel (Modified) 1.47 + */ 1.48 +public abstract class AbstractExecutableMemberWriter extends AbstractMemberWriter { 1.49 + 1.50 + public AbstractExecutableMemberWriter(SubWriterHolderWriter writer, 1.51 + ClassDoc classdoc) { 1.52 + super(writer, classdoc); 1.53 + } 1.54 + 1.55 + public AbstractExecutableMemberWriter(SubWriterHolderWriter writer) { 1.56 + super(writer); 1.57 + } 1.58 + 1.59 + /** 1.60 + * Add the type parameters for the executable member. 1.61 + * 1.62 + * @param member the member to write type parameters for. 1.63 + * @param htmltree the content tree to which the parameters will be added. 1.64 + * @return the display length required to write this information. 1.65 + */ 1.66 + protected void addTypeParameters(ExecutableMemberDoc member, Content htmltree) { 1.67 + Content typeParameters = getTypeParameters(member); 1.68 + if (!typeParameters.isEmpty()) { 1.69 + htmltree.addContent(typeParameters); 1.70 + htmltree.addContent(writer.getSpace()); 1.71 + } 1.72 + } 1.73 + 1.74 + /** 1.75 + * Get the type parameters for the executable member. 1.76 + * 1.77 + * @param member the member for which to get the type parameters. 1.78 + * @return the type parameters. 1.79 + */ 1.80 + protected Content getTypeParameters(ExecutableMemberDoc member) { 1.81 + LinkInfoImpl linkInfo = new LinkInfoImpl(configuration, 1.82 + LinkInfoImpl.Kind.MEMBER_TYPE_PARAMS, member); 1.83 + return writer.getTypeParameterLinks(linkInfo); 1.84 + } 1.85 + 1.86 + /** 1.87 + * {@inheritDoc} 1.88 + */ 1.89 + protected Content getDeprecatedLink(ProgramElementDoc member) { 1.90 + ExecutableMemberDoc emd = (ExecutableMemberDoc)member; 1.91 + return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, (MemberDoc) emd, 1.92 + emd.qualifiedName() + emd.flatSignature()); 1.93 + } 1.94 + 1.95 + /** 1.96 + * Add the summary link for the member. 1.97 + * 1.98 + * @param context the id of the context where the link will be printed 1.99 + * @param cd the classDoc that we should link to 1.100 + * @param member the member being linked to 1.101 + * @param tdSummary the content tree to which the link will be added 1.102 + */ 1.103 + protected void addSummaryLink(LinkInfoImpl.Kind context, ClassDoc cd, ProgramElementDoc member, 1.104 + Content tdSummary) { 1.105 + ExecutableMemberDoc emd = (ExecutableMemberDoc)member; 1.106 + String name = emd.name(); 1.107 + Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink, 1.108 + writer.getDocLink(context, cd, (MemberDoc) emd, 1.109 + name, false)); 1.110 + Content code = HtmlTree.CODE(memberLink); 1.111 + addParameters(emd, false, code, name.length() - 1); 1.112 + tdSummary.addContent(code); 1.113 + } 1.114 + 1.115 + /** 1.116 + * Add the inherited summary link for the member. 1.117 + * 1.118 + * @param cd the classDoc that we should link to 1.119 + * @param member the member being linked to 1.120 + * @param linksTree the content tree to which the link will be added 1.121 + */ 1.122 + protected void addInheritedSummaryLink(ClassDoc cd, 1.123 + ProgramElementDoc member, Content linksTree) { 1.124 + linksTree.addContent( 1.125 + writer.getDocLink(LinkInfoImpl.Kind.MEMBER, cd, (MemberDoc) member, 1.126 + member.name(), false)); 1.127 + } 1.128 + 1.129 + /** 1.130 + * Add the parameter for the executable member. 1.131 + * 1.132 + * @param member the member to write parameter for. 1.133 + * @param param the parameter that needs to be written. 1.134 + * @param isVarArg true if this is a link to var arg. 1.135 + * @param tree the content tree to which the parameter information will be added. 1.136 + */ 1.137 + protected void addParam(ExecutableMemberDoc member, Parameter param, 1.138 + boolean isVarArg, Content tree) { 1.139 + if (param.type() != null) { 1.140 + Content link = writer.getLink(new LinkInfoImpl( 1.141 + configuration, LinkInfoImpl.Kind.EXECUTABLE_MEMBER_PARAM, 1.142 + param.type()).varargs(isVarArg)); 1.143 + tree.addContent(link); 1.144 + } 1.145 + if(param.name().length() > 0) { 1.146 + tree.addContent(writer.getSpace()); 1.147 + tree.addContent(param.name()); 1.148 + } 1.149 + } 1.150 + 1.151 + /** 1.152 + * Add the receiver annotations information. 1.153 + * 1.154 + * @param member the member to write receiver annotations for. 1.155 + * @param rcvrType the receiver type. 1.156 + * @param descList list of annotation description. 1.157 + * @param tree the content tree to which the information will be added. 1.158 + */ 1.159 + protected void addReceiverAnnotations(ExecutableMemberDoc member, Type rcvrType, 1.160 + AnnotationDesc[] descList, Content tree) { 1.161 + writer.addReceiverAnnotationInfo(member, descList, tree); 1.162 + tree.addContent(writer.getSpace()); 1.163 + tree.addContent(rcvrType.typeName()); 1.164 + LinkInfoImpl linkInfo = new LinkInfoImpl(configuration, 1.165 + LinkInfoImpl.Kind.CLASS_SIGNATURE, rcvrType); 1.166 + tree.addContent(writer.getTypeParameterLinks(linkInfo)); 1.167 + tree.addContent(writer.getSpace()); 1.168 + tree.addContent("this"); 1.169 + } 1.170 + 1.171 + 1.172 + /** 1.173 + * Add all the parameters for the executable member. 1.174 + * 1.175 + * @param member the member to write parameters for. 1.176 + * @param htmltree the content tree to which the parameters information will be added. 1.177 + */ 1.178 + protected void addParameters(ExecutableMemberDoc member, Content htmltree, int indentSize) { 1.179 + addParameters(member, true, htmltree, indentSize); 1.180 + } 1.181 + 1.182 + /** 1.183 + * Add all the parameters for the executable member. 1.184 + * 1.185 + * @param member the member to write parameters for. 1.186 + * @param includeAnnotations true if annotation information needs to be added. 1.187 + * @param htmltree the content tree to which the parameters information will be added. 1.188 + */ 1.189 + protected void addParameters(ExecutableMemberDoc member, 1.190 + boolean includeAnnotations, Content htmltree, int indentSize) { 1.191 + htmltree.addContent("("); 1.192 + String sep = ""; 1.193 + Parameter[] params = member.parameters(); 1.194 + String indent = makeSpace(indentSize + 1); 1.195 + Type rcvrType = member.receiverType(); 1.196 + if (includeAnnotations && rcvrType instanceof AnnotatedType) { 1.197 + AnnotationDesc[] descList = rcvrType.asAnnotatedType().annotations(); 1.198 + if (descList.length > 0) { 1.199 + addReceiverAnnotations(member, rcvrType, descList, htmltree); 1.200 + sep = "," + DocletConstants.NL + indent; 1.201 + } 1.202 + } 1.203 + int paramstart; 1.204 + for (paramstart = 0; paramstart < params.length; paramstart++) { 1.205 + htmltree.addContent(sep); 1.206 + Parameter param = params[paramstart]; 1.207 + if (!param.name().startsWith("this$")) { 1.208 + if (includeAnnotations) { 1.209 + boolean foundAnnotations = 1.210 + writer.addAnnotationInfo(indent.length(), 1.211 + member, param, htmltree); 1.212 + if (foundAnnotations) { 1.213 + htmltree.addContent(DocletConstants.NL); 1.214 + htmltree.addContent(indent); 1.215 + } 1.216 + } 1.217 + addParam(member, param, 1.218 + (paramstart == params.length - 1) && member.isVarArgs(), htmltree); 1.219 + break; 1.220 + } 1.221 + } 1.222 + 1.223 + for (int i = paramstart + 1; i < params.length; i++) { 1.224 + htmltree.addContent(","); 1.225 + htmltree.addContent(DocletConstants.NL); 1.226 + htmltree.addContent(indent); 1.227 + if (includeAnnotations) { 1.228 + boolean foundAnnotations = 1.229 + writer.addAnnotationInfo(indent.length(), member, params[i], 1.230 + htmltree); 1.231 + if (foundAnnotations) { 1.232 + htmltree.addContent(DocletConstants.NL); 1.233 + htmltree.addContent(indent); 1.234 + } 1.235 + } 1.236 + addParam(member, params[i], (i == params.length - 1) && member.isVarArgs(), 1.237 + htmltree); 1.238 + } 1.239 + htmltree.addContent(")"); 1.240 + } 1.241 + 1.242 + /** 1.243 + * Add exceptions for the executable member. 1.244 + * 1.245 + * @param member the member to write exceptions for. 1.246 + * @param htmltree the content tree to which the exceptions information will be added. 1.247 + */ 1.248 + protected void addExceptions(ExecutableMemberDoc member, Content htmltree, int indentSize) { 1.249 + Type[] exceptions = member.thrownExceptionTypes(); 1.250 + if (exceptions.length > 0) { 1.251 + LinkInfoImpl memberTypeParam = new LinkInfoImpl(configuration, 1.252 + LinkInfoImpl.Kind.MEMBER, member); 1.253 + String indent = makeSpace(indentSize + 1 - 7); 1.254 + htmltree.addContent(DocletConstants.NL); 1.255 + htmltree.addContent(indent); 1.256 + htmltree.addContent("throws "); 1.257 + indent = makeSpace(indentSize + 1); 1.258 + Content link = writer.getLink(new LinkInfoImpl(configuration, 1.259 + LinkInfoImpl.Kind.MEMBER, exceptions[0])); 1.260 + htmltree.addContent(link); 1.261 + for(int i = 1; i < exceptions.length; i++) { 1.262 + htmltree.addContent(","); 1.263 + htmltree.addContent(DocletConstants.NL); 1.264 + htmltree.addContent(indent); 1.265 + Content exceptionLink = writer.getLink(new LinkInfoImpl( 1.266 + configuration, LinkInfoImpl.Kind.MEMBER, exceptions[i])); 1.267 + htmltree.addContent(exceptionLink); 1.268 + } 1.269 + } 1.270 + } 1.271 + 1.272 + protected ClassDoc implementsMethodInIntfac(MethodDoc method, 1.273 + ClassDoc[] intfacs) { 1.274 + for (int i = 0; i < intfacs.length; i++) { 1.275 + MethodDoc[] methods = intfacs[i].methods(); 1.276 + if (methods.length > 0) { 1.277 + for (int j = 0; j < methods.length; j++) { 1.278 + if (methods[j].name().equals(method.name()) && 1.279 + methods[j].signature().equals(method.signature())) { 1.280 + return intfacs[i]; 1.281 + } 1.282 + } 1.283 + } 1.284 + } 1.285 + return null; 1.286 + } 1.287 + 1.288 + /** 1.289 + * For backward compatibility, include an anchor using the erasures of the 1.290 + * parameters. NOTE: We won't need this method anymore after we fix 1.291 + * see tags so that they use the type instead of the erasure. 1.292 + * 1.293 + * @param emd the ExecutableMemberDoc to anchor to. 1.294 + * @return the 1.4.x style anchor for the ExecutableMemberDoc. 1.295 + */ 1.296 + protected String getErasureAnchor(ExecutableMemberDoc emd) { 1.297 + StringBuilder buf = new StringBuilder(emd.name() + "("); 1.298 + Parameter[] params = emd.parameters(); 1.299 + boolean foundTypeVariable = false; 1.300 + for (int i = 0; i < params.length; i++) { 1.301 + if (i > 0) { 1.302 + buf.append(","); 1.303 + } 1.304 + Type t = params[i].type(); 1.305 + foundTypeVariable = foundTypeVariable || t.asTypeVariable() != null; 1.306 + buf.append(t.isPrimitive() ? 1.307 + t.typeName() : t.asClassDoc().qualifiedName()); 1.308 + buf.append(t.dimension()); 1.309 + } 1.310 + buf.append(")"); 1.311 + return foundTypeVariable ? writer.getName(buf.toString()) : null; 1.312 + } 1.313 +}