DeprecatedListWriter.java revision 3233:b5d08bc0d224 
1/*
2 * Copyright (c) 1997, 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.formats.html;
27
28import java.io.*;
29import java.util.ArrayList;
30import java.util.EnumMap;
31import java.util.List;
32
33import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
34import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
35import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
36import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
37import jdk.javadoc.internal.doclets.toolkit.Content;
38import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder;
39import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
40import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
41import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException;
42
43import static jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder.*;
44
45/**
46 * Generate File to list all the deprecated classes and class members with the
47 * appropriate links.
48 *
49 *  <p><b>This is NOT part of any supported API.
50 *  If you write code that depends on this, you do so at your own risk.
51 *  This code and its internal interfaces are subject to change or
52 *  deletion without notice.</b>
53 *
54 * @see java.util.List
55 * @author Atul M Dambalkar
56 * @author Bhavesh Patel (Modified)
57 */
58public class DeprecatedListWriter extends SubWriterHolderWriter {
59
60    private String getAnchorName(DeprElementKind kind) {
61        switch (kind) {
62            case PACKAGE:
63                return "package";
64            case INTERFACE:
65                return "interface";
66            case CLASS:
67                return "class";
68            case ENUM:
69                return "enum";
70            case EXCEPTION:
71                return "exception";
72            case ERROR:
73                return "error";
74            case ANNOTATION_TYPE:
75                return "annotation.type";
76            case FIELD:
77                return "field";
78            case METHOD:
79                return "method";
80            case CONSTRUCTOR:
81                return "constructor";
82            case ENUM_CONSTANT:
83                return "enum.constant";
84            case ANNOTATION_TYPE_MEMBER:
85                return "annotation.type.member";
86            default:
87                throw new AssertionError("unknown kind: " + kind);
88        }
89    }
90
91    private String getHeadingKey(DeprElementKind kind) {
92        switch (kind) {
93            case PACKAGE:
94                return "doclet.Deprecated_Packages";
95            case INTERFACE:
96                return "doclet.Deprecated_Interfaces";
97            case CLASS:
98                return "doclet.Deprecated_Classes";
99            case ENUM:
100                return "doclet.Deprecated_Enums";
101            case EXCEPTION:
102                return "doclet.Deprecated_Exceptions";
103            case ERROR:
104                return "doclet.Deprecated_Errors";
105            case ANNOTATION_TYPE:
106                return "doclet.Deprecated_Annotation_Types";
107            case FIELD:
108                return "doclet.Deprecated_Fields";
109            case METHOD:
110                return "doclet.Deprecated_Methods";
111            case CONSTRUCTOR:
112                return "doclet.Deprecated_Constructors";
113            case ENUM_CONSTANT:
114                return "doclet.Deprecated_Enum_Constants";
115            case ANNOTATION_TYPE_MEMBER:
116                return "doclet.Deprecated_Annotation_Type_Members";
117            default:
118                throw new AssertionError("unknown kind: " + kind);
119        }
120    }
121
122    private String getSummaryKey(DeprElementKind kind) {
123        switch (kind) {
124            case PACKAGE:
125                return "doclet.deprecated_packages";
126            case INTERFACE:
127                return "doclet.deprecated_interfaces";
128            case CLASS:
129                return "doclet.deprecated_classes";
130            case ENUM:
131                return "doclet.deprecated_enums";
132            case EXCEPTION:
133                return "doclet.deprecated_exceptions";
134            case ERROR:
135                return "doclet.deprecated_errors";
136            case ANNOTATION_TYPE:
137                return "doclet.deprecated_annotation_types";
138            case FIELD:
139                return "doclet.deprecated_fields";
140            case METHOD:
141                return "doclet.deprecated_methods";
142            case CONSTRUCTOR:
143                return "doclet.deprecated_constructors";
144            case ENUM_CONSTANT:
145                return "doclet.deprecated_enum_constants";
146            case ANNOTATION_TYPE_MEMBER:
147                return "doclet.deprecated_annotation_type_members";
148            default:
149                throw new AssertionError("unknown kind: " + kind);
150        }
151    }
152
153    private String getHeaderKey(DeprElementKind kind) {
154        switch (kind) {
155            case PACKAGE:
156                return "doclet.Package";
157            case INTERFACE:
158                return "doclet.Interface";
159            case CLASS:
160                return "doclet.Class";
161            case ENUM:
162                return "doclet.Enum";
163            case EXCEPTION:
164                return "doclet.Exceptions";
165            case ERROR:
166                return "doclet.Errors";
167            case ANNOTATION_TYPE:
168                return "doclet.AnnotationType";
169            case FIELD:
170                return "doclet.Field";
171            case METHOD:
172                return "doclet.Method";
173            case CONSTRUCTOR:
174                return "doclet.Constructor";
175            case ENUM_CONSTANT:
176                return "doclet.Enum_Constant";
177            case ANNOTATION_TYPE_MEMBER:
178                return "doclet.Annotation_Type_Member";
179            default:
180                throw new AssertionError("unknown kind: " + kind);
181        }
182    }
183
184    private EnumMap<DeprElementKind, AbstractMemberWriter> writerMap;
185
186    private ConfigurationImpl configuration;
187
188    /**
189     * Constructor.
190     *
191     * @param filename the file to be generated.
192     */
193
194    public DeprecatedListWriter(ConfigurationImpl configuration,
195                                DocPath filename) throws IOException {
196        super(configuration, filename);
197        this.configuration = configuration;
198        NestedClassWriterImpl classW = new NestedClassWriterImpl(this);
199        writerMap = new EnumMap<>(DeprElementKind.class);
200        for (DeprElementKind kind : DeprElementKind.values()) {
201            switch (kind) {
202                case PACKAGE:
203                case INTERFACE:
204                case CLASS:
205                case ENUM:
206                case EXCEPTION:
207                case ERROR:
208                case ANNOTATION_TYPE:
209                    writerMap.put(kind, classW);
210                    break;
211                case FIELD:
212                    writerMap.put(kind, new FieldWriterImpl(this));
213                    break;
214                case METHOD:
215                    writerMap.put(kind, new MethodWriterImpl(this));
216                    break;
217                case CONSTRUCTOR:
218                    writerMap.put(kind, new ConstructorWriterImpl(this));
219                    break;
220                case ENUM_CONSTANT:
221                    writerMap.put(kind, new EnumConstantWriterImpl(this));
222                    break;
223                case ANNOTATION_TYPE_MEMBER:
224                    writerMap.put(kind, new AnnotationTypeOptionalMemberWriterImpl(this, null));
225                    break;
226                default:
227                   throw new AssertionError("unknown kind: " + kind);
228            }
229        }
230    }
231
232    /**
233     * Get list of all the deprecated classes and members in all the Packages
234     * specified on the Command Line.
235     * Then instantiate DeprecatedListWriter and generate File.
236     *
237     * @param configuration the current configuration of the doclet.
238     */
239    public static void generate(ConfigurationImpl configuration) {
240        DocPath filename = DocPaths.DEPRECATED_LIST;
241        try {
242            DeprecatedListWriter depr =
243                   new DeprecatedListWriter(configuration, filename);
244            depr.generateDeprecatedListFile(
245                   new DeprecatedAPIListBuilder(configuration));
246            depr.close();
247        } catch (IOException exc) {
248            configuration.standardmessage.error(
249                        "doclet.exception_encountered",
250                        exc.toString(), filename);
251            throw new DocletAbortException(exc);
252        }
253    }
254
255    /**
256     * Generate the deprecated API list.
257     *
258     * @param deprapi list of deprecated API built already.
259     */
260    protected void generateDeprecatedListFile(DeprecatedAPIListBuilder deprapi)
261            throws IOException {
262        HtmlTree body = getHeader();
263        HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN))
264                ? HtmlTree.MAIN()
265                : body;
266        htmlTree.addContent(getContentsList(deprapi));
267        String memberTableSummary;
268        HtmlTree div = new HtmlTree(HtmlTag.DIV);
269        div.addStyle(HtmlStyle.contentContainer);
270        for (DeprElementKind kind : DeprElementKind.values()) {
271            if (deprapi.hasDocumentation(kind)) {
272                addAnchor(deprapi, kind, div);
273                memberTableSummary =
274                        configuration.getText("doclet.Member_Table_Summary",
275                        configuration.getText(getHeadingKey(kind)),
276                        configuration.getText(getSummaryKey(kind)));
277                List<String> memberTableHeader = new ArrayList<>();
278                memberTableHeader.add(configuration.getText("doclet.0_and_1",
279                        configuration.getText(getHeaderKey(kind)),
280                        configuration.getText("doclet.Description")));
281                if (kind == DeprElementKind.PACKAGE)
282                    addPackageDeprecatedAPI(deprapi.getSet(kind),
283                            getHeadingKey(kind), memberTableSummary, memberTableHeader, div);
284                else
285                    writerMap.get(kind).addDeprecatedAPI(deprapi.getSet(kind),
286                            getHeadingKey(kind), memberTableSummary, memberTableHeader, div);
287            }
288        }
289        if (configuration.allowTag(HtmlTag.MAIN)) {
290            htmlTree.addContent(div);
291            body.addContent(htmlTree);
292        } else {
293            body.addContent(div);
294        }
295        htmlTree = (configuration.allowTag(HtmlTag.FOOTER))
296                ? HtmlTree.FOOTER()
297                : body;
298        addNavLinks(false, htmlTree);
299        addBottom(htmlTree);
300        if (configuration.allowTag(HtmlTag.FOOTER)) {
301            body.addContent(htmlTree);
302        }
303        printHtmlDocument(null, true, body);
304    }
305
306    /**
307     * Add the index link.
308     *
309     * @param builder the deprecated list builder
310     * @param type the type of list being documented
311     * @param contentTree the content tree to which the index link will be added
312     */
313    private void addIndexLink(DeprecatedAPIListBuilder builder,
314            DeprElementKind kind, Content contentTree) {
315        if (builder.hasDocumentation(kind)) {
316            Content li = HtmlTree.LI(getHyperLink(getAnchorName(kind),
317                    getResource(getHeadingKey(kind))));
318            contentTree.addContent(li);
319        }
320    }
321
322    /**
323     * Get the contents list.
324     *
325     * @param deprapi the deprecated list builder
326     * @return a content tree for the contents list
327     */
328    public Content getContentsList(DeprecatedAPIListBuilder deprapi) {
329        Content headContent = getResource("doclet.Deprecated_API");
330        Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,
331                HtmlStyle.title, headContent);
332        Content div = HtmlTree.DIV(HtmlStyle.header, heading);
333        Content headingContent = getResource("doclet.Contents");
334        div.addContent(HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, true,
335                headingContent));
336        Content ul = new HtmlTree(HtmlTag.UL);
337        for (DeprElementKind kind : DeprElementKind.values()) {
338            addIndexLink(deprapi, kind, ul);
339        }
340        div.addContent(ul);
341        return div;
342    }
343
344    /**
345     * Add the anchor.
346     *
347     * @param builder the deprecated list builder
348     * @param type the type of list being documented
349     * @param htmlTree the content tree to which the anchor will be added
350     */
351    private void addAnchor(DeprecatedAPIListBuilder builder, DeprElementKind kind, Content htmlTree) {
352        if (builder.hasDocumentation(kind)) {
353            htmlTree.addContent(getMarkerAnchor(getAnchorName(kind)));
354        }
355    }
356
357    /**
358     * Get the header for the deprecated API Listing.
359     *
360     * @return a content tree for the header
361     */
362    public HtmlTree getHeader() {
363        String title = configuration.getText("doclet.Window_Deprecated_List");
364        HtmlTree bodyTree = getBody(true, getWindowTitle(title));
365        HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER))
366                ? HtmlTree.HEADER()
367                : bodyTree;
368        addTop(htmlTree);
369        addNavLinks(true, htmlTree);
370        if (configuration.allowTag(HtmlTag.HEADER)) {
371            bodyTree.addContent(htmlTree);
372        }
373        return bodyTree;
374    }
375
376    /**
377     * Get the deprecated label.
378     *
379     * @return a content tree for the deprecated label
380     */
381    protected Content getNavLinkDeprecated() {
382        Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, deprecatedLabel);
383        return li;
384    }
385}
386