src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java

Print this page


   1 /*
   2  * Copyright (c) 1998, 2014, 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 com.sun.tools.doclets.internal.toolkit.util;
  27 
  28 import java.util.*;
  29 
  30 import com.sun.javadoc.*;
  31 import com.sun.tools.doclets.internal.toolkit.Configuration;

  32 


  33 /**
  34  * Build list of all the deprecated packages, classes, constructors, fields and methods.
  35  *
  36  *  <p><b>This is NOT part of any supported API.
  37  *  If you write code that depends on this, you do so at your own risk.
  38  *  This code and its internal interfaces are subject to change or
  39  *  deletion without notice.</b>
  40  *
  41  * @author Atul M Dambalkar
  42  */
  43 public class DeprecatedAPIListBuilder {
  44 
  45     public static final int NUM_TYPES = 12;
  46 
  47     public static final int PACKAGE = 0;
  48     public static final int INTERFACE = 1;
  49     public static final int CLASS = 2;
  50     public static final int ENUM = 3;
  51     public static final int EXCEPTION = 4;
  52     public static final int ERROR = 5;
  53     public static final int ANNOTATION_TYPE = 6;
  54     public static final int FIELD = 7;
  55     public static final int METHOD = 8;
  56     public static final int CONSTRUCTOR = 9;
  57     public static final int ENUM_CONSTANT = 10;
  58     public static final int ANNOTATION_TYPE_MEMBER = 11;
  59 
  60     /**
  61      * List of deprecated type Lists.
  62      */
  63     private List<List<Doc>> deprecatedLists;
  64     private final Configuration configuration;
  65     private final Utils utils;
  66 













  67     /**
  68      * Constructor.
  69      *
  70      * @param configuration the current configuration of the doclet
  71      */
  72     public DeprecatedAPIListBuilder(Configuration configuration) {
  73         this.configuration = configuration;
  74         this.utils = configuration.utils;
  75         deprecatedLists = new ArrayList<>();
  76         for (int i = 0; i < NUM_TYPES; i++) {
  77             deprecatedLists.add(i, new ArrayList<Doc>());

  78         }
  79         buildDeprecatedAPIInfo();
  80     }
  81 
  82     /**
  83      * Build the sorted list of all the deprecated APIs in this run.
  84      * Build separate lists for deprecated packages, classes, constructors,
  85      * methods and fields.
  86      *
  87      * @param configuration the current configuration of the doclet.
  88      */
  89     private void buildDeprecatedAPIInfo() {
  90         Set<PackageDoc> packages = configuration.packages;
  91         for (PackageDoc pkg : packages) {
  92             if (utils.isDeprecated(pkg)) {
  93                 getList(PACKAGE).add(pkg);

  94             }
  95         }
  96         for (ClassDoc cd : configuration.root.classes()) {
  97             if (utils.isDeprecated(cd)) {
  98                 if (cd.isOrdinaryClass()) {
  99                     getList(CLASS).add(cd);
 100                 } else if (cd.isInterface()) {
 101                     getList(INTERFACE).add(cd);
 102                 } else if (cd.isException()) {
 103                     getList(EXCEPTION).add(cd);
 104                 } else if (cd.isEnum()) {
 105                     getList(ENUM).add(cd);
 106                 } else if (cd.isError()) {
 107                     getList(ERROR).add(cd);
 108                 } else if (cd.isAnnotationType()) {
 109                     getList(ANNOTATION_TYPE).add(cd);



 110                 }










 111             }
 112             composeDeprecatedList(getList(FIELD), cd.fields());
 113             composeDeprecatedList(getList(METHOD), cd.methods());
 114             composeDeprecatedList(getList(CONSTRUCTOR), cd.constructors());
 115             if (cd.isEnum()) {
 116                 composeDeprecatedList(getList(ENUM_CONSTANT), cd.enumConstants());
 117             }
 118             if (cd.isAnnotationType()) {
 119                 composeDeprecatedList(getList(ANNOTATION_TYPE_MEMBER),
 120                                       ((AnnotationTypeDoc) cd).elements());






 121             }




 122         }
 123         sortDeprecatedLists();
 124     }

 125 
 126     /**
 127      * Add the members into a single list of deprecated members.
 128      *
 129      * @param list List of all the particular deprecated members, e.g. methods.
 130      * @param members members to be added in the list.
 131      */
 132     private void composeDeprecatedList(List<Doc> list, MemberDoc[] members) {
 133         for (MemberDoc member : members) {
 134             if (utils.isDeprecated(member)) {
 135                 list.add(member);
 136             }
 137         }
 138     }
 139 
 140     /**
 141      * Sort the deprecated lists for class kinds, fields, methods and
 142      * constructors.
 143      */
 144     private void sortDeprecatedLists() {
 145         for (int i = 0; i < NUM_TYPES; i++) {
 146             Collections.sort(getList(i));
 147         }
 148     }
 149 
 150     /**
 151      * Return the list of deprecated Doc objects of a given type.
 152      *
 153      * @param type the constant representing the type of list being returned.

 154      */
 155     public List<Doc> getList(int type) {
 156         return deprecatedLists.get(type);
 157     }
 158 
 159     /**
 160      * Return true if the list of a given type has size greater than 0.
 161      *
 162      * @param type the type of list being checked.
 163      */
 164     public boolean hasDocumentation(int type) {
 165         return (deprecatedLists.get(type)).size() > 0;
 166     }
 167 }
   1 /*
   2  * Copyright (c) 1998, 2016, 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.util;
  27 
  28 import java.util.*;
  29 
  30 import javax.lang.model.element.Element;
  31 import javax.lang.model.element.PackageElement;
  32 import javax.lang.model.element.TypeElement;
  33 
  34 import jdk.javadoc.internal.doclets.toolkit.Configuration;
  35 
  36 /**
  37  * Build list of all the deprecated packages, classes, constructors, fields and methods.
  38  *
  39  *  <p><b>This is NOT part of any supported API.
  40  *  If you write code that depends on this, you do so at your own risk.
  41  *  This code and its internal interfaces are subject to change or
  42  *  deletion without notice.</b>
  43  *
  44  * @author Atul M Dambalkar
  45  */
  46 public class DeprecatedAPIListBuilder {
















  47     /**
  48      * List of deprecated type Lists.
  49      */
  50     private final Map<DeprElementKind, SortedSet<Element>> deprecatedMap;
  51     private final Configuration configuration;
  52     private final Utils utils;
  53     public static enum DeprElementKind {
  54         PACKAGE,
  55         INTERFACE,
  56         CLASS,
  57         ENUM,
  58         EXCEPTION,              // no ElementKind mapping
  59         ERROR,                  // no ElementKind mapping
  60         ANNOTATION_TYPE,
  61         FIELD,
  62         METHOD,
  63         CONSTRUCTOR,
  64         ENUM_CONSTANT,
  65         ANNOTATION_TYPE_MEMBER // no ElementKind mapping
  66     };
  67     /**
  68      * Constructor.
  69      *
  70      * @param configuration the current configuration of the doclet
  71      */
  72     public DeprecatedAPIListBuilder(Configuration configuration) {
  73         this.configuration = configuration;
  74         this.utils = configuration.utils;
  75         deprecatedMap = new EnumMap<>(DeprElementKind.class);
  76         for (DeprElementKind kind : DeprElementKind.values()) {
  77             deprecatedMap.put(kind,
  78                     new TreeSet<>(utils.makeGeneralPurposeComparator()));
  79         }
  80         buildDeprecatedAPIInfo();
  81     }
  82 
  83     /**
  84      * Build the sorted list of all the deprecated APIs in this run.
  85      * Build separate lists for deprecated packages, classes, constructors,
  86      * methods and fields.
  87      *
  88      * @param configuration the current configuration of the doclet.
  89      */
  90     private void buildDeprecatedAPIInfo() {
  91         SortedSet<PackageElement> packages = configuration.packages;
  92         SortedSet<Element> pset = deprecatedMap.get(DeprElementKind.PACKAGE);
  93         for (Element pe : packages) {
  94             if (utils.isDeprecated(pe)) {
  95                 pset.add(pe);
  96             }
  97         }
  98         deprecatedMap.put(DeprElementKind.PACKAGE, pset);
  99         for (Element e : configuration.root.getIncludedClasses()) {
 100             TypeElement te = (TypeElement)e;
 101             SortedSet<Element> eset;
 102             if (utils.isDeprecated(e)) {
 103                 switch (e.getKind()) {
 104                     case ANNOTATION_TYPE:
 105                         eset = deprecatedMap.get(DeprElementKind.ANNOTATION_TYPE);
 106                         eset.add(e);
 107                         break;
 108                     case CLASS:
 109                         if (utils.isError(te)) {
 110                             eset = deprecatedMap.get(DeprElementKind.ERROR);
 111                         } else if (utils.isException(te)) {
 112                             eset = deprecatedMap.get(DeprElementKind.EXCEPTION);
 113                         } else {
 114                             eset = deprecatedMap.get(DeprElementKind.CLASS);
 115                         }
 116                         eset.add(e);
 117                         break;
 118                     case INTERFACE:
 119                         eset = deprecatedMap.get(DeprElementKind.INTERFACE);
 120                         eset.add(e);
 121                         break;
 122                     case ENUM:
 123                         eset = deprecatedMap.get(DeprElementKind.ENUM);
 124                         eset.add(e);
 125                         break;
 126                 }





 127             }
 128             composeDeprecatedList(deprecatedMap.get(DeprElementKind.FIELD),
 129                     utils.getFields(te));
 130             composeDeprecatedList(deprecatedMap.get(DeprElementKind.METHOD),
 131                     utils.getMethods(te));
 132             composeDeprecatedList(deprecatedMap.get(DeprElementKind.CONSTRUCTOR),
 133                     utils.getConstructors(te));
 134             if (utils.isEnum(e)) {
 135                 composeDeprecatedList(deprecatedMap.get(DeprElementKind.ENUM_CONSTANT),
 136                         utils.getEnumConstants(te));
 137             }
 138             if (utils.isAnnotationType(e)) {
 139                 composeDeprecatedList(deprecatedMap.get(DeprElementKind.ANNOTATION_TYPE_MEMBER),
 140                         utils.getAnnotationMembers(te));
 141 
 142             }

 143         }
 144     }
 145 
 146     /**
 147      * Add the members into a single list of deprecated members.
 148      *
 149      * @param list List of all the particular deprecated members, e.g. methods.
 150      * @param members members to be added in the list.
 151      */
 152     private void composeDeprecatedList(SortedSet<Element> sset, List<? extends Element> members) {
 153         for (Element member : members) {
 154             if (utils.isDeprecated(member)) {
 155                 sset.add(member);
 156             }
 157         }
 158     }
 159 
 160     /**
 161      * Return the list of deprecated elements of a given type.










 162      *
 163      * @param kind the DeprElementKind
 164      * @return
 165      */
 166     public SortedSet<Element> getSet(DeprElementKind kind) {
 167         return deprecatedMap.get(kind);
 168     }
 169 
 170     /**
 171      * Return true if the list of a given type has size greater than 0.
 172      *
 173      * @param type the type of list being checked.
 174      */
 175     public boolean hasDocumentation(DeprElementKind kind) {
 176         return !deprecatedMap.get(kind).isEmpty();
 177     }
 178 }