1 /* 2 * Copyright (c) 1997, 2021, 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.formats.html; 27 28 import com.sun.source.doctree.DeprecatedTree; 29 import java.util.List; 30 import java.util.ListIterator; 31 32 import javax.lang.model.element.Element; 33 34 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 35 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 36 import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode; 37 import jdk.javadoc.internal.doclets.toolkit.Content; 38 import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder; 39 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; 40 import jdk.javadoc.internal.doclets.toolkit.util.DocPath; 41 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; 42 43 /** 44 * Generate File to list all the deprecated classes and class members with the 45 * appropriate links. 46 * 47 * <p><b>This is NOT part of any supported API. 48 * If you write code that depends on this, you do so at your own risk. 49 * This code and its internal interfaces are subject to change or 50 * deletion without notice.</b> 51 */ 52 public class DeprecatedListWriter extends SummaryListWriter<DeprecatedAPIListBuilder> { 53 54 private final static String TERMINALLY_DEPRECATED_KEY = "doclet.Terminally_Deprecated_Elements"; 55 56 /** 57 * Constructor. 58 * 59 * @param configuration the configuration for this doclet 60 * @param filename the file to be generated 61 */ DeprecatedListWriter(HtmlConfiguration configuration, DocPath filename)62 public DeprecatedListWriter(HtmlConfiguration configuration, DocPath filename) { 63 super(configuration, filename, PageMode.DEPRECATED, "deprecated elements", 64 configuration.contents.deprecatedAPI, "doclet.Window_Deprecated_List"); 65 } 66 67 /** 68 * Get list of all the deprecated classes and members in all the Packages 69 * specified on the command line. 70 * Then instantiate DeprecatedListWriter and generate File. 71 * 72 * @param configuration the current configuration of the doclet. 73 * @throws DocFileIOException if there is a problem writing the deprecated list 74 */ generate(HtmlConfiguration configuration)75 public static void generate(HtmlConfiguration configuration) throws DocFileIOException { 76 if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) { 77 DocPath filename = DocPaths.DEPRECATED_LIST; 78 DeprecatedListWriter depr = new DeprecatedListWriter(configuration, filename); 79 depr.generateSummaryListFile(configuration.deprecatedAPIListBuilder); 80 } 81 } 82 83 @Override addExtraSection(DeprecatedAPIListBuilder list, Content content)84 protected void addExtraSection(DeprecatedAPIListBuilder list, Content content) { 85 if (list.releases.size() > 1) { 86 content.add(HtmlTree.SPAN(contents.getContent("doclet.Deprecated_Tabs_Intro")) 87 .addStyle(HtmlStyle.helpNote)); 88 } 89 addSummaryAPI(list.getForRemoval(), HtmlIds.FOR_REMOVAL, 90 TERMINALLY_DEPRECATED_KEY, "doclet.Element", content); 91 } 92 93 @Override addExtraIndexLink(DeprecatedAPIListBuilder list, Content target)94 protected void addExtraIndexLink(DeprecatedAPIListBuilder list, Content target) { 95 if (!list.getForRemoval().isEmpty()) { 96 addIndexLink(HtmlIds.FOR_REMOVAL, "doclet.Terminally_Deprecated", target); 97 } 98 } 99 100 @Override addComments(Element e, Content desc)101 protected void addComments(Element e, Content desc) { 102 List<? extends DeprecatedTree> tags = utils.getDeprecatedTrees(e); 103 if (!tags.isEmpty()) { 104 addInlineDeprecatedComment(e, tags.get(0), desc); 105 } else { 106 desc.add(HtmlTree.EMPTY); 107 } 108 } 109 110 @Override addTableTabs(Table table, String headingKey)111 protected void addTableTabs(Table table, String headingKey) { 112 List<String> releases = configuration.deprecatedAPIListBuilder.releases; 113 if (!releases.isEmpty()) { 114 table.setDefaultTab(getTableCaption(headingKey)).setAlwaysShowDefaultTab(true); 115 ListIterator<String> it = releases.listIterator(releases.size()); 116 while (it.hasPrevious()) { 117 String release = it.previous(); 118 Content tab = TERMINALLY_DEPRECATED_KEY.equals(headingKey) 119 ? contents.getContent("doclet.Terminally_Deprecated_In_Release", release) 120 : contents.getContent("doclet.Deprecated_In_Release", release); 121 table.addTab(tab, 122 element -> release.equals(utils.getDeprecatedSince(element))); 123 } 124 getMainBodyScript().append(table.getScript()); 125 } 126 } 127 128 @Override getTableCaption(String headingKey)129 protected Content getTableCaption(String headingKey) { 130 Content caption = contents.getContent(headingKey); 131 return TERMINALLY_DEPRECATED_KEY.equals(headingKey) 132 ? caption : contents.getContent("doclet.Deprecated_Elements", caption); 133 } 134 } 135