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        REMOVAL,
56        MODULE,
57        PACKAGE,
58        INTERFACE,
59        CLASS,
60        ENUM,
61        EXCEPTION,              // no ElementKind mapping
62        ERROR,                  // no ElementKind mapping
63        ANNOTATION_TYPE,
64        FIELD,
65        METHOD,
66        CONSTRUCTOR,
67        ENUM_CONSTANT,
68        ANNOTATION_TYPE_MEMBER // no ElementKind mapping
69    };
70    /**
71     * Constructor.
72     *
73     * @param configuration the current configuration of the doclet
74     */
75    public DeprecatedAPIListBuilder(Configuration configuration) {
76        this.configuration = configuration;
77        this.utils = configuration.utils;
78        deprecatedMap = new EnumMap<>(DeprElementKind.class);
79        for (DeprElementKind kind : DeprElementKind.values()) {
80            deprecatedMap.put(kind,
81                    new TreeSet<>(utils.makeGeneralPurposeComparator()));
82        }
83        buildDeprecatedAPIInfo();
84    }
85
86    /**
87     * Build the sorted list of all the deprecated APIs in this run.
88     * Build separate lists for deprecated modules, packages, classes, constructors,
89     * methods and fields.
90     *
91     * @param configuration the current configuration of the doclet.
92     */
93    private void buildDeprecatedAPIInfo() {
94        SortedSet<Element> rset = deprecatedMap.get(DeprElementKind.REMOVAL);
95        SortedSet<ModuleElement> modules = configuration.modules;
96        SortedSet<Element> mset = deprecatedMap.get(DeprElementKind.MODULE);
97        for (Element me : modules) {
98            if (utils.isDeprecatedForRemoval(me)) {
99                rset.add(me);
100            }
101            if (utils.isDeprecated(me)) {
102                mset.add(me);
103            }
104        }
105        SortedSet<PackageElement> packages = configuration.packages;
106        SortedSet<Element> pset = deprecatedMap.get(DeprElementKind.PACKAGE);
107        for (Element pe : packages) {
108            if (utils.isDeprecatedForRemoval(pe)) {
109                rset.add(pe);
110            }
111            if (utils.isDeprecated(pe)) {
112                pset.add(pe);
113            }
114        }
115        for (Element e : configuration.getIncludedTypeElements()) {
116            TypeElement te = (TypeElement)e;
117            SortedSet<Element> eset;
118            if (utils.isDeprecatedForRemoval(e)) {
119                rset.add(e);
120            }
121            if (utils.isDeprecated(e)) {
122                switch (e.getKind()) {
123                    case ANNOTATION_TYPE:
124                        eset = deprecatedMap.get(DeprElementKind.ANNOTATION_TYPE);
125                        eset.add(e);
126                        break;
127                    case CLASS:
128                        if (utils.isError(te)) {
129                            eset = deprecatedMap.get(DeprElementKind.ERROR);
130                        } else if (utils.isException(te)) {
131                            eset = deprecatedMap.get(DeprElementKind.EXCEPTION);
132                        } else {
133                            eset = deprecatedMap.get(DeprElementKind.CLASS);
134                        }
135                        eset.add(e);
136                        break;
137                    case INTERFACE:
138                        eset = deprecatedMap.get(DeprElementKind.INTERFACE);
139                        eset.add(e);
140                        break;
141                    case ENUM:
142                        eset = deprecatedMap.get(DeprElementKind.ENUM);
143                        eset.add(e);
144                        break;
145                }
146            }
147            composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.FIELD),
148                    utils.getFields(te));
149            composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.METHOD),
150                    utils.getMethods(te));
151            composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.CONSTRUCTOR),
152                    utils.getConstructors(te));
153            if (utils.isEnum(e)) {
154                composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.ENUM_CONSTANT),
155                        utils.getEnumConstants(te));
156            }
157            if (utils.isAnnotationType(e)) {
158                composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.ANNOTATION_TYPE_MEMBER),
159                        utils.getAnnotationMembers(te));
160
161            }
162        }
163    }
164
165    /**
166     * Add the members into a single list of deprecated members.
167     *
168     * @param rset set of elements deprecated for removal.
169     * @param sset set of deprecated elements.
170     * @param list List of all the particular deprecated members, e.g. methods.
171     * @param members members to be added in the list.
172     */
173    private void composeDeprecatedList(SortedSet<Element> rset, SortedSet<Element> sset, List<? extends Element> members) {
174        for (Element member : members) {
175            if (utils.isDeprecatedForRemoval(member)) {
176                rset.add(member);
177            }
178            if (utils.isDeprecated(member)) {
179                sset.add(member);
180            }
181        }
182    }
183
184    /**
185     * Return the list of deprecated elements of a given type.
186     *
187     * @param kind the DeprElementKind
188     * @return
189     */
190    public SortedSet<Element> getSet(DeprElementKind kind) {
191        return deprecatedMap.get(kind);
192    }
193
194    /**
195     * Return true if the list of a given type has size greater than 0.
196     *
197     * @param type the type of list being checked.
198     */
199    public boolean hasDocumentation(DeprElementKind kind) {
200        return !deprecatedMap.get(kind).isEmpty();
201    }
202}
203