DeprecatedAPIListBuilder.java revision 3793:5a2b9f22ba5d 
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
26package jdk.javadoc.internal.doclets.toolkit.util;
27
28import java.util.*;
29
30import javax.lang.model.element.Element;
31import javax.lang.model.element.ModuleElement;
32import javax.lang.model.element.PackageElement;
33import javax.lang.model.element.TypeElement;
34
35import jdk.javadoc.internal.doclets.toolkit.Configuration;
36
37/**
38 * Build list of all the deprecated packages, classes, constructors, fields and methods.
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 * @author Atul M Dambalkar
46 */
47public class DeprecatedAPIListBuilder {
48    /**
49     * List of deprecated type Lists.
50     */
51    private final Map<DeprElementKind, SortedSet<Element>> deprecatedMap;
52    private final Configuration configuration;
53    private final Utils utils;
54    public static enum DeprElementKind {
55        MODULE,
56        PACKAGE,
57        INTERFACE,
58        CLASS,
59        ENUM,
60        EXCEPTION,              // no ElementKind mapping
61        ERROR,                  // no ElementKind mapping
62        ANNOTATION_TYPE,
63        FIELD,
64        METHOD,
65        CONSTRUCTOR,
66        ENUM_CONSTANT,
67        ANNOTATION_TYPE_MEMBER // no ElementKind mapping
68    };
69    /**
70     * Constructor.
71     *
72     * @param configuration the current configuration of the doclet
73     */
74    public DeprecatedAPIListBuilder(Configuration configuration) {
75        this.configuration = configuration;
76        this.utils = configuration.utils;
77        deprecatedMap = new EnumMap<>(DeprElementKind.class);
78        for (DeprElementKind kind : DeprElementKind.values()) {
79            deprecatedMap.put(kind,
80                    new TreeSet<>(utils.makeGeneralPurposeComparator()));
81        }
82        buildDeprecatedAPIInfo();
83    }
84
85    /**
86     * Build the sorted list of all the deprecated APIs in this run.
87     * Build separate lists for deprecated modules, packages, classes, constructors,
88     * methods and fields.
89     *
90     * @param configuration the current configuration of the doclet.
91     */
92    private void buildDeprecatedAPIInfo() {
93        SortedSet<ModuleElement> modules = configuration.modules;
94        SortedSet<Element> mset = deprecatedMap.get(DeprElementKind.MODULE);
95        for (Element me : modules) {
96            if (utils.isDeprecated(me)) {
97                mset.add(me);
98            }
99        }
100        SortedSet<PackageElement> packages = configuration.packages;
101        SortedSet<Element> pset = deprecatedMap.get(DeprElementKind.PACKAGE);
102        for (Element pe : packages) {
103            if (utils.isDeprecated(pe)) {
104                pset.add(pe);
105            }
106        }
107        for (Element e : configuration.getIncludedTypeElements()) {
108            TypeElement te = (TypeElement)e;
109            SortedSet<Element> eset;
110            if (utils.isDeprecated(e)) {
111                switch (e.getKind()) {
112                    case ANNOTATION_TYPE:
113                        eset = deprecatedMap.get(DeprElementKind.ANNOTATION_TYPE);
114                        eset.add(e);
115                        break;
116                    case CLASS:
117                        if (utils.isError(te)) {
118                            eset = deprecatedMap.get(DeprElementKind.ERROR);
119                        } else if (utils.isException(te)) {
120                            eset = deprecatedMap.get(DeprElementKind.EXCEPTION);
121                        } else {
122                            eset = deprecatedMap.get(DeprElementKind.CLASS);
123                        }
124                        eset.add(e);
125                        break;
126                    case INTERFACE:
127                        eset = deprecatedMap.get(DeprElementKind.INTERFACE);
128                        eset.add(e);
129                        break;
130                    case ENUM:
131                        eset = deprecatedMap.get(DeprElementKind.ENUM);
132                        eset.add(e);
133                        break;
134                }
135            }
136            composeDeprecatedList(deprecatedMap.get(DeprElementKind.FIELD),
137                    utils.getFields(te));
138            composeDeprecatedList(deprecatedMap.get(DeprElementKind.METHOD),
139                    utils.getMethods(te));
140            composeDeprecatedList(deprecatedMap.get(DeprElementKind.CONSTRUCTOR),
141                    utils.getConstructors(te));
142            if (utils.isEnum(e)) {
143                composeDeprecatedList(deprecatedMap.get(DeprElementKind.ENUM_CONSTANT),
144                        utils.getEnumConstants(te));
145            }
146            if (utils.isAnnotationType(e)) {
147                composeDeprecatedList(deprecatedMap.get(DeprElementKind.ANNOTATION_TYPE_MEMBER),
148                        utils.getAnnotationMembers(te));
149
150            }
151        }
152    }
153
154    /**
155     * Add the members into a single list of deprecated members.
156     *
157     * @param list List of all the particular deprecated members, e.g. methods.
158     * @param members members to be added in the list.
159     */
160    private void composeDeprecatedList(SortedSet<Element> sset, List<? extends Element> members) {
161        for (Element member : members) {
162            if (utils.isDeprecated(member)) {
163                sset.add(member);
164            }
165        }
166    }
167
168    /**
169     * Return the list of deprecated elements of a given type.
170     *
171     * @param kind the DeprElementKind
172     * @return
173     */
174    public SortedSet<Element> getSet(DeprElementKind kind) {
175        return deprecatedMap.get(kind);
176    }
177
178    /**
179     * Return true if the list of a given type has size greater than 0.
180     *
181     * @param type the type of list being checked.
182     */
183    public boolean hasDocumentation(DeprElementKind kind) {
184        return !deprecatedMap.get(kind).isEmpty();
185    }
186}
187