duke@1: /*
xdono@117:  * Copyright 2003-2008 Sun Microsystems, Inc.  All Rights Reserved.
duke@1:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1:  *
duke@1:  * This code is free software; you can redistribute it and/or modify it
duke@1:  * under the terms of the GNU General Public License version 2 only, as
duke@1:  * published by the Free Software Foundation.  Sun designates this
duke@1:  * particular file as subject to the "Classpath" exception as provided
duke@1:  * by Sun in the LICENSE file that accompanied this code.
duke@1:  *
duke@1:  * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
duke@1:  * version 2 for more details (a copy is included in the LICENSE file that
duke@1:  * accompanied this code).
duke@1:  *
duke@1:  * You should have received a copy of the GNU General Public License version
duke@1:  * 2 along with this work; if not, write to the Free Software Foundation,
duke@1:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1:  *
duke@1:  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
duke@1:  * CA 95054 USA or visit www.sun.com if you need additional information or
duke@1:  * have any questions.
duke@1:  */
duke@1: 
duke@1: package com.sun.tools.doclets.internal.toolkit.builders;
duke@1: 
duke@1: import com.sun.tools.doclets.internal.toolkit.util.*;
duke@1: import com.sun.tools.doclets.internal.toolkit.*;
duke@1: import com.sun.javadoc.*;
duke@1: import java.util.*;
duke@1: import java.lang.reflect.*;
duke@1: 
duke@1: /**
duke@1:  * Builds the member summary.
duke@1:  *
duke@1:  * This code is not part of an API.
duke@1:  * It is implementation that is subject to change.
duke@1:  * Do not use it as an API
duke@1:  *
duke@1:  * @author Jamie Ho
duke@1:  * @since 1.5
duke@1:  */
duke@1: public class MemberSummaryBuilder extends AbstractMemberBuilder {
duke@1: 
duke@1:         /**
duke@1:          * The XML root for this builder.
duke@1:          */
duke@1:         public static final String NAME = "MemberSummary";
duke@1: 
duke@1:         /**
duke@1:          * The visible members for the given class.
duke@1:          */
duke@1:         private VisibleMemberMap[] visibleMemberMaps;
duke@1: 
duke@1:         /**
duke@1:          * The member summary writers for the given class.
duke@1:          */
duke@1:         private MemberSummaryWriter[] memberSummaryWriters;
duke@1: 
duke@1:         /**
duke@1:          * The type being documented.
duke@1:          */
duke@1:         private ClassDoc classDoc;
duke@1: 
duke@1:         private MemberSummaryBuilder(Configuration configuration) {
duke@1:                 super(configuration);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Construct a new MemberSummaryBuilder.
duke@1:          *
duke@1:          * @param classWriter   the writer for the class whose members are being
duke@1:          *                      summarized.
duke@1:          * @param configuration the current configuration of the doclet.
duke@1:          */
duke@1:         public static MemberSummaryBuilder getInstance(
duke@1:                 ClassWriter classWriter, Configuration configuration)
duke@1:         throws Exception {
duke@1:                 MemberSummaryBuilder builder = new MemberSummaryBuilder(configuration);
duke@1:                 builder.classDoc = classWriter.getClassDoc();
duke@1:                 builder.init(classWriter);
duke@1:                 return builder;
duke@1:         }
duke@1: 
duke@1:     /**
duke@1:      * Construct a new MemberSummaryBuilder.
duke@1:      *
duke@1:      * @param annotationTypeWriter the writer for the class whose members are
duke@1:      *                             being summarized.
duke@1:      * @param configuration the current configuration of the doclet.
duke@1:      */
duke@1:     public static MemberSummaryBuilder getInstance(
duke@1:         AnnotationTypeWriter annotationTypeWriter, Configuration configuration)
duke@1:     throws Exception {
duke@1:         MemberSummaryBuilder builder = new MemberSummaryBuilder(configuration);
duke@1:         builder.classDoc = annotationTypeWriter.getAnnotationTypeDoc();
duke@1:         builder.init(annotationTypeWriter);
duke@1:         return builder;
duke@1:     }
duke@1: 
duke@1:     private void init(Object writer) throws Exception {
duke@1:         visibleMemberMaps =
duke@1:             new VisibleMemberMap[VisibleMemberMap.NUM_MEMBER_TYPES];
duke@1:         for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
duke@1:             visibleMemberMaps[i] =
duke@1:                 new VisibleMemberMap(
duke@1:                     classDoc,
duke@1:                     i,
duke@1:                     configuration.nodeprecated);
duke@1:         }
duke@1:         memberSummaryWriters =
duke@1:             new MemberSummaryWriter[VisibleMemberMap.NUM_MEMBER_TYPES];
duke@1:         for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
duke@1:             if (classDoc.isAnnotationType()) {
duke@1:                 memberSummaryWriters[i] =
duke@1:                     visibleMemberMaps[i].noVisibleMembers()?
duke@1:                         null :
duke@1:                         configuration.getWriterFactory().getMemberSummaryWriter(
duke@1:                             (AnnotationTypeWriter) writer, i);
duke@1:             } else {
duke@1:                 memberSummaryWriters[i] =
duke@1:                     visibleMemberMaps[i].noVisibleMembers()?
duke@1:                         null :
duke@1:                         configuration.getWriterFactory().getMemberSummaryWriter(
duke@1:                             (ClassWriter) writer, i);
duke@1:             }
duke@1:         }
duke@1: 
duke@1:     }
duke@1: 
duke@1:         /**
duke@1:          * {@inheritDoc}
duke@1:          */
duke@1:         public String getName() {
duke@1:                 return NAME;
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Return the specified visible member map.
duke@1:          *
duke@1:          * @param type the type of visible member map to return.
duke@1:          * @return the specified visible member map.
duke@1:          * @throws ArrayIndexOutOfBoundsException when the type is invalid.
duke@1:          * @see VisibleMemberMap
duke@1:          */
duke@1:         public VisibleMemberMap getVisibleMemberMap(int type) {
duke@1:                 return visibleMemberMaps[type];
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Return the specified member summary writer.
duke@1:          *
duke@1:          * @param type the type of member summary writer to return.
duke@1:          * @return the specified member summary writer.
duke@1:          * @throws ArrayIndexOutOfBoundsException when the type is invalid.
duke@1:          * @see VisibleMemberMap
duke@1:          */
duke@1:         public MemberSummaryWriter getMemberSummaryWriter(int type) {
duke@1:                 return memberSummaryWriters[type];
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Returns a list of methods that will be documented for the given class.
duke@1:          * This information can be used for doclet specific documentation
duke@1:          * generation.
duke@1:          *
duke@1:          * @param classDoc the {@link ClassDoc} we want to check.
duke@1:          * @param type the type of members to return.
duke@1:          * @return a list of methods that will be documented.
duke@1:          * @see VisibleMemberMap
duke@1:          */
mcimadamore@184:         public List<ProgramElementDoc> members(int type) {
duke@1:                 return visibleMemberMaps[type].getLeafClassMembers(configuration);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * {@inheritDoc}
duke@1:          */
duke@1:         public void invokeMethod(
duke@1:                 String methodName,
mcimadamore@184:                 Class<?>[] paramClasses,
duke@1:                 Object[] params)
duke@1:                 throws Exception {
duke@1:                 if (DEBUG) {
duke@1:                         configuration.root.printError(
duke@1:                                 "DEBUG: " + this.getClass().getName() + "." + methodName);
duke@1:                 }
duke@1:                 Method method = this.getClass().getMethod(methodName, paramClasses);
duke@1:                 method.invoke(this, params);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Return true it there are any members to summarize.
duke@1:          *
duke@1:          * @return true if there are any members to summarize.
duke@1:          */
duke@1:         public boolean hasMembersToDocument() {
duke@1:         if (classDoc instanceof AnnotationTypeDoc) {
duke@1:             return ((AnnotationTypeDoc) classDoc).elements().length > 0;
duke@1:         }
duke@1:                 for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
duke@1:                         VisibleMemberMap members = visibleMemberMaps[i];
duke@1:                         if (!members.noVisibleMembers()) {
duke@1:                                 return true;
duke@1:                         }
duke@1:                 }
duke@1:                 return false;
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Build the summary for the enum constants.
duke@1:          */
duke@1:         public void buildEnumConstantsSummary() {
duke@1:                 buildSummary(
duke@1:                         memberSummaryWriters[VisibleMemberMap.ENUM_CONSTANTS],
duke@1:                         visibleMemberMaps[VisibleMemberMap.ENUM_CONSTANTS]);
duke@1:         }
duke@1: 
duke@1:     /**
duke@1:      * Build the summary for the optional members.
duke@1:      */
duke@1:     public void buildAnnotationTypeOptionalMemberSummary() {
duke@1:         buildSummary(
duke@1:             memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL],
duke@1:                 visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL]);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the summary for the optional members.
duke@1:      */
duke@1:     public void buildAnnotationTypeRequiredMemberSummary() {
duke@1:         buildSummary(
duke@1:             memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED],
duke@1:                 visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED]);
duke@1:     }
duke@1: 
duke@1:         /**
duke@1:          * Build the summary for the fields.
duke@1:          */
duke@1:         public void buildFieldsSummary() {
duke@1:                 buildSummary(
duke@1:                         memberSummaryWriters[VisibleMemberMap.FIELDS],
duke@1:                         visibleMemberMaps[VisibleMemberMap.FIELDS]);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Build the inherited summary for the fields.
duke@1:          */
duke@1:         public void buildFieldsInheritedSummary() {
duke@1:                 buildInheritedSummary(
duke@1:                         memberSummaryWriters[VisibleMemberMap.FIELDS],
duke@1:                         visibleMemberMaps[VisibleMemberMap.FIELDS]);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Build the summary for the nested classes.
duke@1:          */
duke@1:         public void buildNestedClassesSummary() {
duke@1:                 buildSummary(
duke@1:                         memberSummaryWriters[VisibleMemberMap.INNERCLASSES],
duke@1:                         visibleMemberMaps[VisibleMemberMap.INNERCLASSES]);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Build the inherited summary for the nested classes.
duke@1:          */
duke@1:         public void buildNestedClassesInheritedSummary() {
duke@1:                 buildInheritedSummary(
duke@1:                         memberSummaryWriters[VisibleMemberMap.INNERCLASSES],
duke@1:                         visibleMemberMaps[VisibleMemberMap.INNERCLASSES]);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Build the method summary.
duke@1:          */
duke@1:         public void buildMethodsSummary() {
duke@1:                 buildSummary(
duke@1:                         memberSummaryWriters[VisibleMemberMap.METHODS],
duke@1:                         visibleMemberMaps[VisibleMemberMap.METHODS]);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Build the inherited method summary.
duke@1:          */
duke@1:         public void buildMethodsInheritedSummary() {
duke@1:                 buildInheritedSummary(
duke@1:                         memberSummaryWriters[VisibleMemberMap.METHODS],
duke@1:                         visibleMemberMaps[VisibleMemberMap.METHODS]);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Build the constructor summary.
duke@1:          */
duke@1:         public void buildConstructorsSummary() {
duke@1:                 buildSummary(
duke@1:                         memberSummaryWriters[VisibleMemberMap.CONSTRUCTORS],
duke@1:                         visibleMemberMaps[VisibleMemberMap.CONSTRUCTORS]);
duke@1:         }
duke@1: 
duke@1:         /**
duke@1:          * Build the member summary for the given members.
duke@1:          *
duke@1:          * @param writer           the summary writer to write the output.
duke@1:          * @param visibleMemberMap the given members to summarize.
duke@1:          */
duke@1:         private void buildSummary(MemberSummaryWriter writer,
duke@1:             VisibleMemberMap visibleMemberMap) {
jjg@74:         List<ProgramElementDoc> members = new ArrayList<ProgramElementDoc>(visibleMemberMap.getLeafClassMembers(
duke@1:             configuration));
duke@1:         if (members.size() > 0) {
duke@1:             Collections.sort(members);
duke@1:             writer.writeMemberSummaryHeader(classDoc);
duke@1:             for (int i = 0; i < members.size(); i++) {
jjg@74:                 ProgramElementDoc member = members.get(i);
duke@1:                 Tag[] firstSentenceTags = member.firstSentenceTags();
duke@1:                 if (member instanceof MethodDoc && firstSentenceTags.length == 0) {
duke@1:                     //Inherit comments from overriden or implemented method if
duke@1:                     //necessary.
duke@1:                     DocFinder.Output inheritedDoc =
duke@1:                         DocFinder.search(new DocFinder.Input((MethodDoc) member));
duke@1:                     if (inheritedDoc.holder != null &&
duke@1:                             inheritedDoc.holder.firstSentenceTags().length > 0) {
duke@1:                         firstSentenceTags = inheritedDoc.holder.firstSentenceTags();
duke@1:                     }
duke@1:                 }
duke@1:                 writer.writeMemberSummary(classDoc, member, firstSentenceTags,
duke@1:                     i == 0, i == members.size() - 1);
duke@1:             }
duke@1:             writer.writeMemberSummaryFooter(classDoc);
duke@1:         }
duke@1:         }
duke@1: 
duke@1:     /**
duke@1:      * Build the inherited member summary for the given methods.
duke@1:      *
duke@1:      * @param writer           the writer for this member summary.
duke@1:      * @param visibleMemberMap the map for the members to document.
duke@1:      */
duke@1:         private void buildInheritedSummary(MemberSummaryWriter writer,
duke@1:             VisibleMemberMap visibleMemberMap) {
mcimadamore@184:         for (Iterator<ClassDoc> iter = visibleMemberMap.getVisibleClassesList().iterator();
duke@1:                 iter.hasNext();) {
mcimadamore@184:             ClassDoc inhclass = iter.next();
duke@1:             if (! (inhclass.isPublic() ||
duke@1:                 Util.isLinkable(inhclass, configuration))) {
duke@1:                 continue;
duke@1:             }
duke@1:             if (inhclass == classDoc) {
duke@1:                 continue;
duke@1:             }
jjg@74:             List<ProgramElementDoc> inhmembers = visibleMemberMap.getMembersFor(inhclass);
duke@1:             if (inhmembers.size() > 0) {
duke@1:                 Collections.sort(inhmembers);
duke@1:                 writer.writeInheritedMemberSummaryHeader(inhclass);
duke@1:                 for (int j = 0; j < inhmembers.size(); ++j) {
duke@1:                     writer.writeInheritedMemberSummary(
duke@1:                         inhclass.isPackagePrivate() &&
duke@1:                             ! Util.isLinkable(inhclass, configuration) ?
duke@1:                             classDoc : inhclass,
jjg@74:                         inhmembers.get(j),
duke@1:                         j == 0,
duke@1:                         j == inhmembers.size() - 1);
duke@1:                 }
duke@1:                 writer.writeInheritedMemberSummaryFooter(inhclass);
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: }