stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8250768: javac should be adapted to changes in JEP 12

Browse Source 
Reviewed-by: mcimadamore, erikj, jjg, ihse
This commit is contained in:
Jan Lahoda 2021-01-11 10:10:47 +00:00
parent 18a37f9453
commit 235488215b
133 changed files with 3109 additions and 1080 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
make/CompileInterimLangtools.gmk
View File

@ -1,5 +1,5 @@
#
# Copyright (c) 2014, 2020, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2014, 2021, Oracle and/or its affiliates. All rights reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -49,8 +49,8 @@ TARGETS += $(patsubst %, $(BUILDTOOLS_OUTPUTDIR)/gensrc/%/module-info.java, \
$(INTERIM_LANGTOOLS_MODULES))
$(eval $(call SetupCopyFiles, COPY_PREVIEW_FEATURES, \
FILES := $(TOPDIR)/src/java.base/share/classes/jdk/internal/PreviewFeature.java, \
DEST := $(BUILDTOOLS_OUTPUTDIR)/gensrc/java.base.interim/jdk/internal/, \
FILES := $(TOPDIR)/src/java.base/share/classes/jdk/internal/javac/PreviewFeature.java, \
DEST := $(BUILDTOOLS_OUTPUTDIR)/gensrc/java.base.interim/jdk/internal/javac/, \
))
TARGETS += $(COPY_PREVIEW_FEATURES)
@ -81,8 +81,8 @@ define SetupInterimModule
--module-path $(BUILDTOOLS_OUTPUTDIR)/interim_langtools_modules \
$$(INTERIM_LANGTOOLS_ADD_EXPORTS) \
--patch-module java.base=$(BUILDTOOLS_OUTPUTDIR)/gensrc/java.base.interim \
--add-exports java.base/jdk.internal=java.compiler.interim \
--add-exports java.base/jdk.internal=jdk.compiler.interim, \
--add-exports java.base/jdk.internal.javac=java.compiler.interim \
--add-exports java.base/jdk.internal.javac=jdk.compiler.interim, \
))
$1_DEPS_INTERIM := $$(addsuffix .interim, $$(filter \

1
make/Docs.gmk
View File

@ -89,7 +89,6 @@ JAVADOC_TAGS := \
-tag see \
-taglet build.tools.taglet.ExtLink \
-taglet build.tools.taglet.Incubating \
-taglet build.tools.taglet.Preview \
-tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
$(CUSTOM_JAVADOC_TAGS) \
#

3
make/autoconf/spec.gmk.in
View File

@ -658,6 +658,8 @@ INTERIM_LANGTOOLS_ADD_EXPORTS := \
--add-exports java.base/jdk.internal.jmod=jdk.compiler.interim \
--add-exports java.base/jdk.internal.misc=jdk.compiler.interim \
--add-exports java.base/sun.invoke.util=jdk.compiler.interim \
--add-exports java.base/jdk.internal.javac=java.compiler.interim \
--add-exports java.base/jdk.internal.javac=jdk.compiler.interim \
#
INTERIM_LANGTOOLS_MODULES_COMMA := $(strip $(subst $(SPACE),$(COMMA),$(strip \
$(INTERIM_LANGTOOLS_MODULES))))
@ -665,6 +667,7 @@ INTERIM_LANGTOOLS_ARGS := \
--limit-modules java.base,jdk.zipfs,$(INTERIM_LANGTOOLS_MODULES_COMMA) \
--add-modules $(INTERIM_LANGTOOLS_MODULES_COMMA) \
--module-path $(BUILDTOOLS_OUTPUTDIR)/interim_langtools_modules \
--patch-module java.base=$(BUILDTOOLS_OUTPUTDIR)/gensrc/java.base.interim \
$(INTERIM_LANGTOOLS_ADD_EXPORTS) \
#
JAVAC_MAIN_CLASS = -m jdk.compiler.interim/com.sun.tools.javac.Main

79
make/jdk/src/classes/build/tools/taglet/Preview.java
View File

@ -1,79 +0,0 @@
/*
* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package build.tools.taglet;
import java.util.Arrays;
import java.util.EnumSet;
import java.util.List;
import java.util.Set;
import java.util.function.Predicate;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.TextTree;
import com.sun.source.doctree.UnknownInlineTagTree;
import jdk.javadoc.doclet.Taglet;
import static jdk.javadoc.doclet.Taglet.Location.*;
/**
* An block tag to insert a standard warning about a preview API.
*/
public class Preview implements Taglet {
/** Returns the set of locations in which a taglet may be used. */
@Override
public Set<Location> getAllowedLocations() {
return EnumSet.of(MODULE, PACKAGE, TYPE, CONSTRUCTOR, METHOD, FIELD);
}
@Override
public boolean isInlineTag() {
return true;
}
@Override
public String getName() {
return "preview";
}
@Override
public String toString(List<? extends DocTree> tags, Element elem) {
UnknownInlineTagTree previewTag = (UnknownInlineTagTree) tags.get(0);
List<? extends DocTree> previewContent = previewTag.getContent();
String previewText = ((TextTree) previewContent.get(0)).getBody();
String[] summaryAndDetails = previewText.split("\n\r?\n\r?");
String summary = summaryAndDetails[0];
String details = summaryAndDetails.length > 1 ? summaryAndDetails[1] : summaryAndDetails[0];
StackTraceElement[] stackTrace = new Exception().getStackTrace();
Predicate<StackTraceElement> isSummary =
el -> el.getClassName().endsWith("HtmlDocletWriter") &&
el.getMethodName().equals("addSummaryComment");
if (Arrays.stream(stackTrace).anyMatch(isSummary)) {
return "<div style=\"display:inline-block; font-weight:bold\">" + summary + "</div><br>";
}
return "<div style=\"border: 1px solid red; border-radius: 5px; padding: 5px; display:inline-block; font-size: larger\">" + details + "</div><br>";
}
}

18
make/langtools/src/classes/build/tools/symbolgenerator/CreateSymbols.java
View File

@ -1112,20 +1112,32 @@ public class CreateSymbols {
private Annotation createAnnotation(List<CPInfo> constantPool, AnnotationDescription desc) {
String annotationType = desc.annotationType;
Map<String, Object> values = desc.values;
if (PREVIEW_FEATURE_ANNOTATION.equals(annotationType)) {
if (PREVIEW_FEATURE_ANNOTATION_NEW.equals(annotationType)) {
//the non-public PreviewFeature annotation will not be available in ct.sym,
//replace with purely synthetic javac-internal annotation:
annotationType = PREVIEW_FEATURE_ANNOTATION_INTERNAL;
}
if (PREVIEW_FEATURE_ANNOTATION_OLD.equals(annotationType)) {
//the non-public PreviewFeature annotation will not be available in ct.sym,
//replace with purely synthetic javac-internal annotation:
annotationType = PREVIEW_FEATURE_ANNOTATION_INTERNAL;
values = new HashMap<>(values);
Boolean essentialAPI = (Boolean) values.remove("essentialAPI");
values.put("reflective", essentialAPI != null && !essentialAPI);
}
return new Annotation(null,
addString(constantPool, annotationType),
createElementPairs(constantPool, desc.values));
createElementPairs(constantPool, values));
}
//where:
private static final String PREVIEW_FEATURE_ANNOTATION =
private static final String PREVIEW_FEATURE_ANNOTATION_OLD =
"Ljdk/internal/PreviewFeature;";
private static final String PREVIEW_FEATURE_ANNOTATION_NEW =
"Ljdk/internal/javac/PreviewFeature;";
private static final String PREVIEW_FEATURE_ANNOTATION_INTERNAL =
"Ljdk/internal/PreviewFeature+Annotation;";

5
make/modules/jdk.compiler/Gendata.gmk
View File

@ -1,5 +1,5 @@
#
# Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -44,7 +44,7 @@ CT_MODULESOURCEPATH := $(call GetModuleSrcPath)
CT_DATA_DESCRIPTION += $(TOPDIR)/make/data/symbols/symbols
COMPILECREATESYMBOLS_ADD_EXPORTS := \
--add-exports java.base/jdk.internal=java.compiler.interim,jdk.compiler.interim \
--add-exports java.base/jdk.internal.javac=java.compiler.interim,jdk.compiler.interim \
--add-exports jdk.compiler.interim/com.sun.tools.javac.api=ALL-UNNAMED \
--add-exports jdk.compiler.interim/com.sun.tools.javac.code=ALL-UNNAMED \
--add-exports jdk.compiler.interim/com.sun.tools.javac.util=ALL-UNNAMED \
@ -60,7 +60,6 @@ $(eval $(call SetupJavaCompilation, COMPILE_CREATE_SYMBOLS, \
DISABLED_WARNINGS := options, \
JAVAC_FLAGS := \
$(INTERIM_LANGTOOLS_ARGS) \
--patch-module java.base=$(BUILDTOOLS_OUTPUTDIR)/gensrc/java.base.interim \
$(COMPILECREATESYMBOLS_ADD_EXPORTS), \
))

3
make/modules/jdk.javadoc/Gendata.gmk
View File

@ -1,5 +1,5 @@
#
# Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -58,7 +58,6 @@ $(eval $(call SetupJavaCompilation, COMPILE_CREATE_SYMBOLS, \
DISABLED_WARNINGS := options, \
JAVAC_FLAGS := \
$(INTERIM_LANGTOOLS_ARGS) \
--patch-module java.base=$(BUILDTOOLS_OUTPUTDIR)/gensrc/java.base.interim \
$(COMPILECREATESYMBOLS_ADD_EXPORTS), \
))

20
src/java.base/share/classes/java/lang/Class.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1994, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -4387,13 +4387,6 @@ public final class Class<T> implements java.io.Serializable,
public native boolean isHidden();
/**
* {@preview Associated with sealed classes, a preview feature of the Java language.
*
* This method is associated with <i>sealed classes</i>, a preview
* feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent
* features of the Java language.}
*
* Returns an array containing {@code Class} objects representing the
* direct subinterfaces or subclasses permitted to extend or
* implement this class or interface if it is sealed. The order of such elements
@ -4429,7 +4422,7 @@ public final class Class<T> implements java.io.Serializable,
* @jls 9.1 Interface Declarations
* @since 15
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SEALED_CLASSES, essentialAPI=false)
@jdk.internal.javac.PreviewFeature(feature=jdk.internal.javac.PreviewFeature.Feature.SEALED_CLASSES, reflective=true)
@CallerSensitive
public Class<?>[] getPermittedSubclasses() {
Class<?>[] subClasses;
@ -4469,13 +4462,6 @@ public final class Class<T> implements java.io.Serializable,
}
/**
* {@preview Associated with sealed classes, a preview feature of the Java language.
*
* This method is associated with <i>sealed classes</i>, a preview
* feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent
* features of the Java language.}
*
* Returns {@code true} if and only if this {@code Class} object represents
* a sealed class or interface. If this {@code Class} object represents a
* primitive type, {@code void}, or an array type, this method returns
@ -4489,7 +4475,7 @@ public final class Class<T> implements java.io.Serializable,
* @jls 9.1 Interface Declarations
* @since 15
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SEALED_CLASSES, essentialAPI=false)
@jdk.internal.javac.PreviewFeature(feature=jdk.internal.javac.PreviewFeature.Feature.SEALED_CLASSES, reflective=true)
@SuppressWarnings("preview")
public boolean isSealed() {
if (isArray() || isPrimitive()) {

8
src/java.base/share/classes/jdk/internal/PreviewFeature.java → src/java.base/share/classes/jdk/internal/javac/PreviewFeature.java
View File

@ -23,7 +23,7 @@
* questions.
*/
package jdk.internal;
package jdk.internal.javac;
import java.lang.annotation.*;
@ -51,7 +51,7 @@ public @interface PreviewFeature {
*/
public Feature feature();
public boolean essentialAPI() default false;
public boolean reflective() default false;
public enum Feature {
// 8242284:
@ -68,6 +68,10 @@ public @interface PreviewFeature {
// necessary for PreviewFeature in JDK 16 to declare the enum constant.
RECORDS,
SEALED_CLASSES,
/**
* A key for testing.
*/
TEST,
;
}
}

5
src/java.base/share/classes/module-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2014, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2014, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -138,10 +138,9 @@ module java.base {
jdk.incubator.foreign;
exports com.sun.security.ntlm to
java.security.sasl;
exports jdk.internal to // for @HotSpotIntrinsicCandidate
exports jdk.internal.javac to
java.compiler,
jdk.compiler,
jdk.incubator.vector,
jdk.jshell;
exports jdk.internal.access to
java.desktop,

24
src/java.compiler/share/classes/javax/lang/model/element/Modifier.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -66,33 +66,19 @@ public enum Modifier {
/** The modifier {@code static} */ STATIC,
/**
* {@preview Associated with sealed classes, a preview feature of the Java language.
*
* This enum constant is associated with <i>sealed classes</i>, a preview
* feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent
* features of the Java language.}
*
* The modifier {@code sealed}
* @since 15
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SEALED_CLASSES,
essentialAPI=false)
@jdk.internal.javac.PreviewFeature(feature=jdk.internal.javac.PreviewFeature.Feature.SEALED_CLASSES,
reflective=true)
SEALED,
/**
* {@preview Associated with sealed classes, a preview feature of the Java language.
*
* This enum constant is associated with <i>sealed classes</i>, a preview
* feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent
* features of the Java language.}
*
* The modifier {@code non-sealed}
* @since 15
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SEALED_CLASSES,
essentialAPI=false)
@jdk.internal.javac.PreviewFeature(feature=jdk.internal.javac.PreviewFeature.Feature.SEALED_CLASSES,
reflective=true)
NON_SEALED {
public String toString() {
return "non-sealed";

12
src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -199,12 +199,6 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
}
/**
* {@preview Associated with sealed classes, a preview feature of the Java language.
*
* This method is associated with <i>sealed classes</i>, a preview
* feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent
* features of the Java language.}
* Returns the permitted classes of this class or interface
* element in declaration order.
*
@ -215,8 +209,8 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
*
* @since 15
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SEALED_CLASSES,
essentialAPI=false)
@jdk.internal.javac.PreviewFeature(feature=jdk.internal.javac.PreviewFeature.Feature.SEALED_CLASSES,
reflective=true)
default List<? extends TypeMirror> getPermittedSubclasses() {
return List.of();
}

13
src/jdk.compiler/share/classes/com/sun/source/tree/ClassTree.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -87,13 +87,6 @@ public interface ClassTree extends StatementTree {
List<? extends Tree> getImplementsClause();
/**
* {@preview Associated with sealed classes, a preview feature of the Java language.
*
* This method is associated with <i>sealed classes</i>, a preview
* feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent
* features of the Java language.}
*
* Returns the subclasses permitted by this type declaration.
*
* @implSpec this implementation returns an empty list
@ -102,8 +95,8 @@ public interface ClassTree extends StatementTree {
*
* @since 15
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SEALED_CLASSES,
essentialAPI=false)
@jdk.internal.javac.PreviewFeature(feature=jdk.internal.javac.PreviewFeature.Feature.SEALED_CLASSES,
reflective=true)
default List<? extends Tree> getPermitsClause() {
return List.of();
}

6
src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTaskPool.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -44,6 +44,7 @@ import javax.tools.Diagnostic;
import javax.tools.DiagnosticListener;
import javax.tools.JavaFileManager;
import javax.tools.JavaFileObject;
import javax.tools.StandardLocation;
import com.sun.source.tree.ClassTree;
import com.sun.source.tree.CompilationUnitTree;
@ -251,6 +252,9 @@ public class JavacTaskPool {
}
void clear() {
//when patching modules (esp. java.base), it may be impossible to
//clear the symbols read from the patch path:
polluted |= get(JavaFileManager.class).hasLocation(StandardLocation.PATCH_MODULE_PATH);
drop(Arguments.argsKey);
drop(DiagnosticListener.class);
drop(Log.outKey);

6
src/jdk.compiler/share/classes/com/sun/tools/javac/code/Flags.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -337,7 +337,7 @@ public class Flags {
/**
* Flag to indicate the API element in question is for a preview API.
*/
public static final long PREVIEW_ESSENTIAL_API = 1L<<58; //any Symbol kind
public static final long PREVIEW_REFLECTIVE = 1L<<58; //any Symbol kind
/**
* Flag to indicate the given variable is a match binding variable.
@ -509,7 +509,7 @@ public class Flags {
ANONCONSTR_BASED(Flags.ANONCONSTR_BASED),
NAME_FILLED(Flags.NAME_FILLED),
PREVIEW_API(Flags.PREVIEW_API),
PREVIEW_ESSENTIAL_API(Flags.PREVIEW_ESSENTIAL_API),
PREVIEW_REFLECTIVE(Flags.PREVIEW_REFLECTIVE),
MATCH_BINDING(Flags.MATCH_BINDING),
MATCH_BINDING_TO_OUTER(Flags.MATCH_BINDING_TO_OUTER),
RECORD(Flags.RECORD),

52
src/jdk.compiler/share/classes/com/sun/tools/javac/code/Preview.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -42,8 +42,13 @@ import com.sun.tools.javac.util.Options;
import javax.tools.JavaFileObject;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
import static com.sun.tools.javac.code.Flags.RECORD;
import static com.sun.tools.javac.code.Flags.SEALED;
import static com.sun.tools.javac.code.Flags.NON_SEALED;
import static com.sun.tools.javac.main.Option.PREVIEW;
/**
@ -70,6 +75,7 @@ public class Preview {
/** a mapping from classfile numbers to Java SE versions */
private final Map<Integer, Source> majorVersionToSource;
private final Set<JavaFileObject> sourcesWithPreviewFeatures = new HashSet<>();
private final Lint lint;
private final Log log;
@ -90,8 +96,9 @@ public class Preview {
enabled = options.isSet(PREVIEW);
log = Log.instance(context);
lint = Lint.instance(context);
Source source = Source.instance(context);
this.previewHandler =
new MandatoryWarningHandler(log, lint.isEnabled(LintCategory.PREVIEW), true, "preview", LintCategory.PREVIEW);
new MandatoryWarningHandler(log, source, lint.isEnabled(LintCategory.PREVIEW), true, "preview", LintCategory.PREVIEW);
forcePreview = options.isSet("forcePreview");
majorVersionToSource = initMajorVersionToSourceMap();
}
@ -128,6 +135,7 @@ public class Preview {
Assert.check(isEnabled());
Assert.check(isPreview(feature));
if (!lint.isSuppressed(LintCategory.PREVIEW)) {
sourcesWithPreviewFeatures.add(log.currentSourceFile());
previewHandler.report(pos, feature.isPlural() ?
Warnings.PreviewFeatureUsePlural(feature.nameFragment()) :
Warnings.PreviewFeatureUse(feature.nameFragment()));
@ -141,16 +149,25 @@ public class Preview {
*/
public void warnPreview(JavaFileObject classfile, int majorVersion) {
Assert.check(isEnabled());
if (!lint.isSuppressed(LintCategory.PREVIEW)) {
previewHandler.report(null,
if (lint.isEnabled(LintCategory.PREVIEW)) {
sourcesWithPreviewFeatures.add(log.currentSourceFile());
log.mandatoryWarning(LintCategory.PREVIEW, null,
Warnings.PreviewFeatureUseClassfile(classfile, majorVersionToSource.get(majorVersion).name));
}
}
public void markUsesPreview(DiagnosticPosition pos) {
sourcesWithPreviewFeatures.add(log.currentSourceFile());
}
public void reportPreviewWarning(DiagnosticPosition pos, Warning warnKey) {
previewHandler.report(pos, warnKey);
}
public boolean usesPreview(JavaFileObject file) {
return sourcesWithPreviewFeatures.contains(file);
}
/**
* Are preview features enabled?
* @return true, if preview features are enabled.
@ -165,12 +182,14 @@ public class Preview {
* @return true, if given feature is a preview feature.
*/
public boolean isPreview(Feature feature) {
if (feature == Feature.SEALED_CLASSES)
return true;
//Note: this is a backdoor which allows to optionally treat all features as 'preview' (for testing).
//When real preview features will be added, this method can be implemented to return 'true'
//for those selected features, and 'false' for all the others.
return forcePreview;
return switch (feature) {
case SEALED_CLASSES -> true;
//Note: this is a backdoor which allows to optionally treat all features as 'preview' (for testing).
//When real preview features will be added, this method can be implemented to return 'true'
//for those selected features, and 'false' for all the others.
default -> forcePreview;
};
}
/**
@ -197,6 +216,19 @@ public class Preview {
return Errors.PreviewFeatureDisabledClassfile(classfile, majorVersionToSource.get(majorVersion).name);
}
/**
* Check whether the given symbol has been declared using
* a preview language feature.
*
* @param sym Symbol to check
* @return true iff sym has been declared using a preview language feature
*/
public boolean declaredUsingPreviewFeature(Symbol sym) {
return ((sym.flags() & RECORD) != 0 && isPreview(Feature.RECORDS)) ||
((sym.flags() & SEALED) != 0 && isPreview(Feature.SEALED_CLASSES)) ||
((sym.flags() & NON_SEALED) != 0 && isPreview(Feature.SEALED_CLASSES));
}
/**
* Report any deferred diagnostics.
*/

2
src/jdk.compiler/share/classes/com/sun/tools/javac/code/Symtab.java
View File

@ -581,7 +581,7 @@ public class Symtab {
lambdaMetafactory = enterClass("java.lang.invoke.LambdaMetafactory");
stringConcatFactory = enterClass("java.lang.invoke.StringConcatFactory");
functionalInterfaceType = enterClass("java.lang.FunctionalInterface");
previewFeatureType = enterClass("jdk.internal.PreviewFeature");
previewFeatureType = enterClass("jdk.internal.javac.PreviewFeature");
previewFeatureInternalType = enterSyntheticAnnotation("jdk.internal.PreviewFeature+Annotation");
typeDescriptorType = enterClass("java.lang.invoke.TypeDescriptor");
recordType = enterClass("java.lang.Record");

4
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Annotate.java
View File

@ -373,8 +373,8 @@ public class Annotate {
if (!c.type.isErroneous()
&& types.isSameType(c.type, syms.previewFeatureType)) {
toAnnotate.flags_field |= Flags.PREVIEW_API;
if (isAttributeTrue(c.member(names.essentialAPI))) {
toAnnotate.flags_field |= Flags.PREVIEW_ESSENTIAL_API;
if (isAttributeTrue(c.member(names.reflective))) {
toAnnotate.flags_field |= Flags.PREVIEW_REFLECTIVE;
}
}
}

4
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -4482,7 +4482,7 @@ public class Attr extends JCTree.Visitor {
chk.checkDeprecated(tree.pos(), env.info.scope.owner, sym);
chk.checkSunAPI(tree.pos(), sym);
chk.checkProfile(tree.pos(), sym);
chk.checkPreview(tree.pos(), sym);
chk.checkPreview(tree.pos(), env.info.scope.owner, sym);
}
// If symbol is a variable, check that its type and

47
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -148,13 +148,13 @@ public class Check {
boolean verboseUnchecked = lint.isEnabled(LintCategory.UNCHECKED);
boolean enforceMandatoryWarnings = true;
deprecationHandler = new MandatoryWarningHandler(log, verboseDeprecated,
deprecationHandler = new MandatoryWarningHandler(log, null, verboseDeprecated,
enforceMandatoryWarnings, "deprecated", LintCategory.DEPRECATION);
removalHandler = new MandatoryWarningHandler(log, verboseRemoval,
removalHandler = new MandatoryWarningHandler(log, null, verboseRemoval,
enforceMandatoryWarnings, "removal", LintCategory.REMOVAL);
uncheckedHandler = new MandatoryWarningHandler(log, verboseUnchecked,
uncheckedHandler = new MandatoryWarningHandler(log, null, verboseUnchecked,
enforceMandatoryWarnings, "unchecked", LintCategory.UNCHECKED);
sunApiHandler = new MandatoryWarningHandler(log, false,
sunApiHandler = new MandatoryWarningHandler(log, null, false,
enforceMandatoryWarnings, "sunapi", null);
deferredLintHandler = DeferredLintHandler.instance(context);
@ -239,21 +239,22 @@ public class Check {
}
}
/** Warn about deprecated symbol.
/** Log a preview warning.
* @param pos Position to be used for error reporting.
* @param sym The deprecated symbol.
* @param msg A Warning describing the problem.
*/
void warnPreview(DiagnosticPosition pos, Symbol sym) {
warnPreview(pos, Warnings.IsPreview(sym));
public void warnPreviewAPI(DiagnosticPosition pos, Warning warnKey) {
if (!lint.isSuppressed(LintCategory.PREVIEW))
preview.reportPreviewWarning(pos, warnKey);
}
/** Log a preview warning.
* @param pos Position to be used for error reporting.
* @param msg A Warning describing the problem.
*/
public void warnPreview(DiagnosticPosition pos, Warning warnKey) {
public void warnDeclaredUsingPreview(DiagnosticPosition pos, Symbol sym) {
if (!lint.isSuppressed(LintCategory.PREVIEW))
preview.reportPreviewWarning(pos, warnKey);
preview.reportPreviewWarning(pos, Warnings.DeclaredUsingPreview(kindName(sym), sym));
}
/** Warn about unchecked operation.
@ -3545,12 +3546,26 @@ public class Check {
}
}
void checkPreview(DiagnosticPosition pos, Symbol s) {
if ((s.flags() & PREVIEW_API) != 0) {
if ((s.flags() & PREVIEW_ESSENTIAL_API) != 0 && !preview.isEnabled()) {
log.error(pos, Errors.IsPreview(s));
void checkPreview(DiagnosticPosition pos, Symbol other, Symbol s) {
if ((s.flags() & PREVIEW_API) != 0 && s.packge().modle != other.packge().modle) {
if ((s.flags() & PREVIEW_REFLECTIVE) == 0) {
if (!preview.isEnabled()) {
log.error(pos, Errors.IsPreview(s));
} else {
preview.markUsesPreview(pos);
deferredLintHandler.report(() -> warnPreviewAPI(pos, Warnings.IsPreview(s)));
}
} else {
deferredLintHandler.report(() -> warnPreview(pos, s));
deferredLintHandler.report(() -> warnPreviewAPI(pos, Warnings.IsPreviewReflective(s)));
}
}
if (preview.declaredUsingPreviewFeature(s)) {
if (preview.isEnabled()) {
//for preview disabled do presumably so not need to do anything?
//If "s" is compiled from source, then there was an error for it already;
//if "s" is from classfile, there already was an error for the classfile.
preview.markUsesPreview(pos);
deferredLintHandler.report(() -> warnDeclaredUsingPreview(pos, s));
}
}
}

3
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Modules.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2009, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -1138,6 +1138,7 @@ public class Modules extends JCTree.Visitor {
public void visitRequires(JCRequires tree) {
if (tree.directive != null && allModules().contains(tree.directive.module)) {
chk.checkDeprecated(tree.moduleName.pos(), msym, tree.directive.module);
chk.checkPreview(tree.moduleName.pos(), msym, tree.directive.module);
chk.checkModuleRequires(tree.moduleName.pos(), tree.directive);
msym.directives = msym.directives.prepend(tree.directive);
}

6
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Resolve.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -2896,7 +2896,7 @@ public class Resolve {
typeargtypes, allowBoxing,
useVarargs);
chk.checkDeprecated(pos, env.info.scope.owner, sym);
chk.checkPreview(pos, sym);
chk.checkPreview(pos, env.info.scope.owner, sym);
return sym;
}
@ -2961,7 +2961,7 @@ public class Resolve {
boolean useVarargs) {
Symbol sym = findDiamond(env, site, argtypes, typeargtypes, allowBoxing, useVarargs);
chk.checkDeprecated(pos, env.info.scope.owner, sym);
chk.checkPreview(pos, sym);
chk.checkPreview(pos, env.info.scope.owner, sym);
return sym;
}

6
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/TypeEnter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -114,6 +114,7 @@ public class TypeEnter implements Completer {
private final Lint lint;
private final TypeEnvs typeEnvs;
private final Dependencies dependencies;
private final Preview preview;
public static TypeEnter instance(Context context) {
TypeEnter instance = context.get(typeEnterKey);
@ -141,6 +142,7 @@ public class TypeEnter implements Completer {
lint = Lint.instance(context);
typeEnvs = TypeEnvs.instance(context);
dependencies = Dependencies.instance(context);
preview = Preview.instance(context);
Source source = Source.instance(context);
allowTypeAnnos = Feature.TYPE_ANNOTATIONS.allowedInSource(source);
allowDeprecationOnImport = Feature.DEPRECATION_ON_IMPORT.allowedInSource(source);
@ -1462,7 +1464,7 @@ public class TypeEnter implements Completer {
setFlagIfAttributeTrue(a, sym, names.forRemoval, DEPRECATED_REMOVAL);
} else if (a.annotationType.type == syms.previewFeatureType) {
sym.flags_field |= Flags.PREVIEW_API;
setFlagIfAttributeTrue(a, sym, names.essentialAPI, PREVIEW_ESSENTIAL_API);
setFlagIfAttributeTrue(a, sym, names.reflective, Flags.PREVIEW_REFLECTIVE);
}
}
}

6
src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/ClassReader.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -1439,7 +1439,7 @@ public class ClassReader {
}
} else if (proxy.type.tsym.flatName() == syms.previewFeatureInternalType.tsym.flatName()) {
sym.flags_field |= PREVIEW_API;
setFlagIfAttributeTrue(proxy, sym, names.essentialAPI, PREVIEW_ESSENTIAL_API);
setFlagIfAttributeTrue(proxy, sym, names.reflective, PREVIEW_REFLECTIVE);
} else {
if (proxy.type.tsym == syms.annotationTargetType.tsym) {
target = proxy;
@ -1450,7 +1450,7 @@ public class ClassReader {
setFlagIfAttributeTrue(proxy, sym, names.forRemoval, DEPRECATED_REMOVAL);
} else if (proxy.type.tsym == syms.previewFeatureType.tsym) {
sym.flags_field |= PREVIEW_API;
setFlagIfAttributeTrue(proxy, sym, names.essentialAPI, PREVIEW_ESSENTIAL_API);
setFlagIfAttributeTrue(proxy, sym, names.reflective, PREVIEW_REFLECTIVE);
}
proxies.append(proxy);
}

4
src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/ClassWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -1632,7 +1632,7 @@ public class ClassWriter extends ClassFile {
acount += writeExtraAttributes(c);
poolbuf.appendInt(JAVA_MAGIC);
if (preview.isEnabled()) {
if (preview.isEnabled() && preview.usesPreview(c.sourcefile)) {
poolbuf.appendChar(ClassFile.PREVIEW_MINOR_VERSION);
} else {
poolbuf.appendChar(target.minorVersion);

36
src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties
View File

@ -1,5 +1,5 @@
#
# Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -1632,24 +1632,26 @@ compiler.note.unchecked.filename.additional=\
compiler.note.unchecked.plural.additional=\
Some input files additionally use unchecked or unsafe operations.
# 0: file name
# 0: file name, 1: source
compiler.note.preview.filename=\
{0} uses preview language features.
{0} uses preview features of Java SE {1}.
# 0: source
compiler.note.preview.plural=\
Some input files use preview language features.
Some input files use preview features of Java SE {0}.
# The following string may appear after one of the above deprecation
# messages.
compiler.note.preview.recompile=\
Recompile with -Xlint:preview for details.
# 0: file name
# 0: file name, 1: source
compiler.note.preview.filename.additional=\
{0} has additional uses of preview language features.
{0} has additional uses of preview features of Java SE {1}.
# 0: source
compiler.note.preview.plural.additional=\
Some input files additionally use preview language features.
Some input files additionally use preview features of Java SE {0}.
# Notes related to annotation processing
@ -1783,11 +1785,16 @@ compiler.warn.has.been.deprecated.for.removal=\
# 0: symbol
compiler.warn.is.preview=\
{0} is an API that is part of a preview feature
{0} is a preview API and may be removed in a future release.
# 0: symbol
compiler.err.is.preview=\
{0} is an API that is part of a preview feature
{0} is a preview API and is disabled by default.\n\
(use --enable-preview to enable preview APIs)
# 0: symbol
compiler.warn.is.preview.reflective=\
{0} is a reflective preview API and may be removed in a future release.
# 0: symbol
compiler.warn.has.been.deprecated.module=\
@ -2863,8 +2870,8 @@ compiler.err.preview.feature.disabled.plural=\
# 0: file object (classfile), 1: string (expected version)
compiler.err.preview.feature.disabled.classfile=\
classfile for {0} uses preview features of Java SE {1}.\n\
(use --enable-preview to allow loading of classfiles which contain preview features)
class file for {0} uses preview features of Java SE {1}.\n\
(use --enable-preview to allow loading of class files which contain preview features)
# 0: message segment (feature)
compiler.warn.preview.feature.use=\
@ -2876,7 +2883,7 @@ compiler.warn.preview.feature.use.plural=\
# 0: file object (classfile), 1: string (expected version)
compiler.warn.preview.feature.use.classfile=\
classfile for {0} uses preview features of Java SE {1}.
class file for {0} uses preview features of Java SE {1}.
compiler.misc.feature.modules=\
@ -3741,6 +3748,9 @@ compiler.err.preview.not.latest=\
compiler.err.preview.without.source.or.release=\
--enable-preview must be used with either -source or --release
# 0: kind name, 1: symbol
compiler.warn.declared.using.preview=\
{0} {1} is declared using a preview feature, which may be removed in a future release.
compiler.warn.attempt.to.synchronize.on.instance.of.value.based.class=\
attempt to synchronize on an instance of a value-based class

22
src/jdk.compiler/share/classes/com/sun/tools/javac/util/MandatoryWarningHandler.java
View File

@ -31,6 +31,7 @@ import java.util.Set;
import javax.tools.JavaFileObject;
import com.sun.tools.javac.code.Lint.LintCategory;
import com.sun.tools.javac.code.Source;
import com.sun.tools.javac.util.JCDiagnostic.DiagnosticPosition;
import com.sun.tools.javac.util.JCDiagnostic.Note;
import com.sun.tools.javac.util.JCDiagnostic.Warning;
@ -111,10 +112,11 @@ public class MandatoryWarningHandler {
* the messages that may be generated.
* @param lc An associated lint category for the warnings, or null if none.
*/
public MandatoryWarningHandler(Log log, boolean verbose,
public MandatoryWarningHandler(Log log, Source source, boolean verbose,
boolean enforceMandatory, String prefix,
LintCategory lc) {
this.log = log;
this.source = source;
this.verbose = verbose;
this.prefix = prefix;
this.enforceMandatory = enforceMandatory;
@ -173,10 +175,19 @@ public class MandatoryWarningHandler {
*/
public void reportDeferredDiagnostic() {
if (deferredDiagnosticKind != null) {
if (deferredDiagnosticArg == null)
logMandatoryNote(deferredDiagnosticSource, deferredDiagnosticKind.getKey(prefix));
else
logMandatoryNote(deferredDiagnosticSource, deferredDiagnosticKind.getKey(prefix), deferredDiagnosticArg);
if (deferredDiagnosticArg == null) {
if (source != null) {
logMandatoryNote(deferredDiagnosticSource, deferredDiagnosticKind.getKey(prefix), source);
} else {
logMandatoryNote(deferredDiagnosticSource, deferredDiagnosticKind.getKey(prefix));
}
} else {
if (source != null) {
logMandatoryNote(deferredDiagnosticSource, deferredDiagnosticKind.getKey(prefix), deferredDiagnosticArg, source);
} else {
logMandatoryNote(deferredDiagnosticSource, deferredDiagnosticKind.getKey(prefix), deferredDiagnosticArg);
}
}
if (!verbose)
logMandatoryNote(deferredDiagnosticSource, prefix + ".recompile");
@ -187,6 +198,7 @@ public class MandatoryWarningHandler {
* The log to which to report warnings.
*/
private final Log log;
private final Source source;
/**
* Whether or not to report individual warnings, or simply to report a

6
src/jdk.compiler/share/classes/com/sun/tools/javac/util/Names.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -86,7 +86,7 @@ public class Names {
public final Name error;
public final Name finalize;
public final Name forRemoval;
public final Name essentialAPI;
public final Name reflective;
public final Name getClass;
public final Name hasNext;
public final Name hashCode;
@ -259,7 +259,7 @@ public class Names {
error = fromString("<error>");
finalize = fromString("finalize");
forRemoval = fromString("forRemoval");
essentialAPI = fromString("essentialAPI");
reflective = fromString("reflective");
getClass = fromString("getClass");
hasNext = fromString("hasNext");
hashCode = fromString("hashCode");

8
src/jdk.compiler/share/classes/com/sun/tools/javac/util/RawDiagnosticFormatter.java
View File

@ -28,10 +28,12 @@ package com.sun.tools.javac.util;
import java.util.Collection;
import java.util.EnumSet;
import java.util.Locale;
import java.util.Set;
import javax.tools.JavaFileObject;
import com.sun.tools.javac.api.DiagnosticFormatter.Configuration.*;
import com.sun.tools.javac.api.Formattable;
import com.sun.tools.javac.code.Source;
import com.sun.tools.javac.file.PathFileObject;
import com.sun.tools.javac.tree.JCTree.*;
@ -160,11 +162,17 @@ public final class RawDiagnosticFormatter extends AbstractDiagnosticFormatter {
s = ((PathFileObject) arg).getShortName();
} else if (arg instanceof Tag) {
s = "compiler.misc.tree.tag." + StringUtils.toLowerCase(((Tag) arg).name());
} else if (arg instanceof Source && arg == Source.DEFAULT &&
CODES_NEEDING_SOURCE_NORMALIZATION.contains(diag.getCode())) {
s = "DEFAULT";
} else {
s = super.formatArgument(diag, arg, null);
}
return (arg instanceof JCDiagnostic) ? "(" + s + ")" : s;
}
//where:
private static final Set<String> CODES_NEEDING_SOURCE_NORMALIZATION = Set.of(
"compiler.note.preview.filename", "compiler.note.preview.plural");
@Override
protected String localize(Locale l, String key, Object... args) {

19
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -49,6 +49,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
import static jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl.Kind.EXECUTABLE_MEMBER_PARAM;
import static jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl.Kind.MEMBER;
import static jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl.Kind.MEMBER_DEPRECATED_PREVIEW;
import static jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl.Kind.MEMBER_TYPE_PARAMS;
import static jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl.Kind.RECEIVER_TYPE;
import static jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl.Kind.THROWS_TYPE;
@ -84,20 +85,20 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
}
@Override
protected Content getDeprecatedLink(Element member) {
Content deprecatedLinkContent = new ContentBuilder();
deprecatedLinkContent.add(utils.getFullyQualifiedName(member));
protected Content getSummaryLink(Element member) {
Content content = new ContentBuilder();
content.add(utils.getFullyQualifiedName(member));
if (!utils.isConstructor(member)) {
deprecatedLinkContent.add(".");
deprecatedLinkContent.add(member.getSimpleName());
content.add(".");
content.add(member.getSimpleName());
}
String signature = utils.flatSignature((ExecutableElement) member, typeElement);
if (signature.length() > 2) {
deprecatedLinkContent.add(Entity.ZERO_WIDTH_SPACE);
content.add(Entity.ZERO_WIDTH_SPACE);
}
deprecatedLinkContent.add(signature);
content.add(signature);
return writer.getDocLink(MEMBER, utils.getEnclosingTypeElement(member), member, deprecatedLinkContent);
return writer.getDocLink(MEMBER_DEPRECATED_PREVIEW, utils.getEnclosingTypeElement(member), member, content);
}
/**

16
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -172,13 +172,13 @@ public abstract class AbstractMemberWriter implements MemberSummaryWriter, Membe
Element member, Content linksTree);
/**
* Returns the deprecated link.
* Returns a link for summary (deprecated, preview) pages.
*
* @param member the member being linked to
*
* @return a content tree representing the link
*/
protected abstract Content getDeprecatedLink(Element member);
protected abstract Content getSummaryLink(Element member);
/**
* Adds the modifier and type for the member in the member summary.
@ -271,6 +271,16 @@ public abstract class AbstractMemberWriter implements MemberSummaryWriter, Membe
}
}
/**
* Add the preview information for the given member.
*
* @param member the member being documented.
* @param contentTree the content tree to which the preview information will be added.
*/
protected void addPreviewInfo(Element member, Content contentTree) {
writer.addPreviewInfo(member, contentTree);
}
protected String name(Element member) {
return utils.getSimpleName(member);
}

11
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesIndexWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -27,9 +27,11 @@ package jdk.javadoc.internal.doclets.formats.html;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
import javax.lang.model.element.TypeElement;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.DeprecatedTree;
import jdk.javadoc.internal.doclets.formats.html.markup.BodyContents;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
@ -44,6 +46,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
import jdk.javadoc.internal.doclets.toolkit.util.Utils.ElementFlag;
/**
* Generate the file with list of all the classes in this run.
@ -154,7 +157,11 @@ public class AllClassesIndexWriter extends HtmlDocletWriter {
Content classLink = getLink(new LinkInfoImpl(
configuration, LinkInfoImpl.Kind.INDEX, klass));
ContentBuilder description = new ContentBuilder();
if (utils.isDeprecated(klass)) {
Set<ElementFlag> flags = utils.elementFlags(klass);
if (flags.contains(ElementFlag.PREVIEW)) {
description.add(contents.previewPhrase);
addSummaryComment(klass, description);
} else if (flags.contains(ElementFlag.DEPRECATED)) {
description.add(getDeprecatedPhrase(klass));
List<? extends DeprecatedTree> tags = utils.getDeprecatedTrees(klass);
if (!tags.isEmpty()) {

11
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -130,6 +130,11 @@ public class AnnotationTypeRequiredMemberWriterImpl extends AbstractMemberWriter
addDeprecatedInfo(member, annotationDocTree);
}
@Override
public void addPreview(Element member, Content contentTree) {
addPreviewInfo(member, contentTree);
}
@Override
public void addComments(Element member, Content annotationDocTree) {
addComment(member, annotationDocTree);
@ -201,9 +206,9 @@ public class AnnotationTypeRequiredMemberWriterImpl extends AbstractMemberWriter
}
@Override
protected Content getDeprecatedLink(Element member) {
protected Content getSummaryLink(Element member) {
String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName();
return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name);
return writer.getDocLink(LinkInfoImpl.Kind.MEMBER_DEPRECATED_PREVIEW, member, name);
}
protected Comment selectComment(Comment c1, Comment c2) {

5
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -440,7 +440,8 @@ public class ClassUseWriter extends SubWriterHolderWriter {
contents.moduleLabel);
Content classLinkContent = getLink(new LinkInfoImpl(
configuration, LinkInfoImpl.Kind.CLASS_USE_HEADER, typeElement)
.label(resources.getText("doclet.Class")));
.label(resources.getText("doclet.Class"))
.skipPreview(true));
return super.getNavBar(pageMode, element)
.setNavLinkModule(mdleLinkContent)
.setNavLinkClass(classLinkContent);

31
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -43,6 +43,7 @@ import javax.lang.model.util.SimpleElementVisitor8;
import com.sun.source.doctree.DeprecatedTree;
import com.sun.source.doctree.DocTree;
import javax.lang.model.element.ElementKind;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlAttr;
@ -86,6 +87,9 @@ public class ClassWriterImpl extends SubWriterHolderWriter implements ClassWrite
"java.lang.constant.ConstantDesc",
"java.io.Serializable");
private static final Set<String> previewModifiers
= Set.of("sealed", "non-sealed");
protected final TypeElement typeElement;
protected final ClassTree classtree;
@ -188,15 +192,34 @@ public class ClassWriterImpl extends SubWriterHolderWriter implements ClassWrite
@Override @SuppressWarnings("preview")
public void addClassSignature(String modifiers, Content classInfoTree) {
ContentBuilder mods = new ContentBuilder();
String sep = null;
for (String modifiersPart : modifiers.split(" ")) {
if (sep != null) {
mods.add(sep);
}
if (previewModifiers.contains(modifiersPart)) {
mods.add(modifiersPart);
mods.add(HtmlTree.SUP(links.createLink(getPreviewSectionAnchor(typeElement),
contents.previewMark)));
} else {
mods.add(modifiersPart);
}
sep = " ";
}
if (modifiers.endsWith(" ")) {
mods.add(" ");
}
classInfoTree.add(new HtmlTree(TagName.HR));
classInfoTree.add(new Signatures.TypeSignature(typeElement, this)
.setModifiers(new StringContent(modifiers))
.setModifiers(mods)
.toContent());
}
@Override
public void addClassDescription(Content classInfoTree) {
addPreviewInfo(classInfoTree);
if (!options.noComment()) {
// generate documentation for the class.
if (!utils.getFullBody(typeElement).isEmpty()) {
@ -205,6 +228,10 @@ public class ClassWriterImpl extends SubWriterHolderWriter implements ClassWrite
}
}
private void addPreviewInfo(Content classInfoTree) {
addPreviewInfo(typeElement, classInfoTree);
}
@Override
public void addClassTagInfo(Content classInfoTree) {
if (!options.noComment()) {

7
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -142,6 +142,11 @@ public class ConstructorWriterImpl extends AbstractExecutableMemberWriter
addDeprecatedInfo(constructor, constructorDocTree);
}
@Override
public void addPreview(ExecutableElement constructor, Content constructorDocTree) {
addPreviewInfo(constructor, constructorDocTree);
}
@Override
public void addComments(ExecutableElement constructor, Content constructorDocTree) {
addComment(constructor, constructorDocTree);

10
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -151,6 +151,10 @@ public class Contents {
public final Content package_;
public final Content packagesLabel;
public final Content parameters;
public final Content previewAPI;
public final Content previewLabel;
public final Content previewMark;
public final Content previewPhrase;
public final Content properties;
public final Content propertyLabel;
public final Content propertyDetailsLabel;
@ -294,6 +298,10 @@ public class Contents {
package_ = getContent("doclet.package");
packagesLabel = getContent("doclet.Packages");
parameters = getContent("doclet.Parameters");
previewAPI = getContent("doclet.Preview_API");
previewLabel = getContent("doclet.Preview_Label");
previewMark = getContent("doclet.Preview_Mark");
previewPhrase = getContent("doclet.Preview");
properties = getContent("doclet.Properties");
propertyLabel = getContent("doclet.Property");
propertyDetailsLabel = getContent("doclet.Property_Detail");

371
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -26,31 +26,16 @@
package jdk.javadoc.internal.doclets.formats.html;
import com.sun.source.doctree.DeprecatedTree;
import jdk.javadoc.internal.doclets.formats.html.markup.Table;
import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader;
import java.util.EnumMap;
import java.util.List;
import java.util.SortedSet;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder.DeprElementKind;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
/**
* Generate File to list all the deprecated classes and class members with the
@ -63,157 +48,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
*
* @see java.util.List
*/
public class DeprecatedListWriter extends SubWriterHolderWriter {
private String getAnchorName(DeprElementKind kind) {
switch (kind) {
case REMOVAL:
return "forRemoval";
case MODULE:
return "module";
case PACKAGE:
return "package";
case INTERFACE:
return "interface";
case CLASS:
return "class";
case ENUM:
return "enum.class";
case EXCEPTION:
return "exception";
case ERROR:
return "error";
case ANNOTATION_TYPE:
return "annotation.interface";
case FIELD:
return "field";
case METHOD:
return "method";
case CONSTRUCTOR:
return "constructor";
case ENUM_CONSTANT:
return "enum.constant";
case ANNOTATION_TYPE_MEMBER:
return "annotation.interface.member";
case RECORD_CLASS:
return "record.class";
default:
throw new AssertionError("unknown kind: " + kind);
}
}
private String getHeadingKey(DeprElementKind kind) {
switch (kind) {
case REMOVAL:
return "doclet.For_Removal";
case MODULE:
return "doclet.Modules";
case PACKAGE:
return "doclet.Packages";
case INTERFACE:
return "doclet.Interfaces";
case CLASS:
return "doclet.Classes";
case ENUM:
return "doclet.Enums";
case EXCEPTION:
return "doclet.Exceptions";
case ERROR:
return "doclet.Errors";
case ANNOTATION_TYPE:
return "doclet.Annotation_Types";
case RECORD_CLASS:
return "doclet.RecordClasses";
case FIELD:
return "doclet.Fields";
case METHOD:
return "doclet.Methods";
case CONSTRUCTOR:
return "doclet.Constructors";
case ENUM_CONSTANT:
return "doclet.Enum_Constants";
case ANNOTATION_TYPE_MEMBER:
return "doclet.Annotation_Type_Members";
default:
throw new AssertionError("unknown kind: " + kind);
}
}
private String getSummaryKey(DeprElementKind kind) {
switch (kind) {
case REMOVAL:
return "doclet.for_removal";
case MODULE:
return "doclet.modules";
case PACKAGE:
return "doclet.packages";
case INTERFACE:
return "doclet.interfaces";
case CLASS:
return "doclet.classes";
case ENUM:
return "doclet.enums";
case EXCEPTION:
return "doclet.exceptions";
case ERROR:
return "doclet.errors";
case ANNOTATION_TYPE:
return "doclet.annotation_types";
case RECORD_CLASS:
return "doclet.record_classes";
case FIELD:
return "doclet.fields";
case METHOD:
return "doclet.methods";
case CONSTRUCTOR:
return "doclet.constructors";
case ENUM_CONSTANT:
return "doclet.enum_constants";
case ANNOTATION_TYPE_MEMBER:
return "doclet.annotation_type_members";
default:
throw new AssertionError("unknown kind: " + kind);
}
}
private String getHeaderKey(DeprElementKind kind) {
switch (kind) {
case REMOVAL:
return "doclet.Element";
case MODULE:
return "doclet.Module";
case PACKAGE:
return "doclet.Package";
case INTERFACE:
return "doclet.Interface";
case CLASS:
return "doclet.Class";
case ENUM:
return "doclet.Enum";
case EXCEPTION:
return "doclet.Exceptions";
case ERROR:
return "doclet.Errors";
case ANNOTATION_TYPE:
return "doclet.AnnotationType";
case RECORD_CLASS:
return "doclet.RecordClass";
case FIELD:
return "doclet.Field";
case METHOD:
return "doclet.Method";
case CONSTRUCTOR:
return "doclet.Constructor";
case ENUM_CONSTANT:
return "doclet.Enum_Constant";
case ANNOTATION_TYPE_MEMBER:
return "doclet.Annotation_Type_Member";
default:
throw new AssertionError("unknown kind: " + kind);
}
}
private EnumMap<DeprElementKind, AbstractMemberWriter> writerMap;
public class DeprecatedListWriter extends SummaryListWriter<DeprecatedAPIListBuilder> {
/**
* Constructor.
@ -223,42 +58,8 @@ public class DeprecatedListWriter extends SubWriterHolderWriter {
*/
public DeprecatedListWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename);
NestedClassWriterImpl classW = new NestedClassWriterImpl(this);
writerMap = new EnumMap<>(DeprElementKind.class);
for (DeprElementKind kind : DeprElementKind.values()) {
switch (kind) {
case REMOVAL:
case MODULE:
case PACKAGE:
case INTERFACE:
case CLASS:
case ENUM:
case EXCEPTION:
case ERROR:
case ANNOTATION_TYPE:
case RECORD_CLASS:
writerMap.put(kind, classW);
break;
case FIELD:
writerMap.put(kind, new FieldWriterImpl(this));
break;
case METHOD:
writerMap.put(kind, new MethodWriterImpl(this));
break;
case CONSTRUCTOR:
writerMap.put(kind, new ConstructorWriterImpl(this));
break;
case ENUM_CONSTANT:
writerMap.put(kind, new EnumConstantWriterImpl(this));
break;
case ANNOTATION_TYPE_MEMBER:
writerMap.put(kind, new AnnotationTypeOptionalMemberWriterImpl(this, null));
break;
default:
throw new AssertionError("unknown kind: " + kind);
}
}
super(configuration, filename, PageMode.DEPRECATED, "deprecated elements",
configuration.contents.deprecatedAPI, "doclet.Window_Deprecated_List");
}
/**
@ -273,162 +74,30 @@ public class DeprecatedListWriter extends SubWriterHolderWriter {
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
DocPath filename = DocPaths.DEPRECATED_LIST;
DeprecatedListWriter depr = new DeprecatedListWriter(configuration, filename);
depr.generateDeprecatedListFile(configuration.deprecatedAPIListBuilder);
depr.generateSummaryListFile(configuration.deprecatedAPIListBuilder);
}
}
/**
* Generate the deprecated API list.
*
* @param deprAPI list of deprecated API built already.
* @throws DocFileIOException if there is a problem writing the deprecated list
*/
protected void generateDeprecatedListFile(DeprecatedAPIListBuilder deprAPI)
throws DocFileIOException {
HtmlTree body = getHeader();
bodyContents.addMainContent(getContentsList(deprAPI));
Content content = new ContentBuilder();
for (DeprElementKind kind : DeprElementKind.values()) {
if (deprAPI.hasDocumentation(kind)) {
TableHeader memberTableHeader = new TableHeader(
contents.getContent(getHeaderKey(kind)), contents.descriptionLabel);
addDeprecatedAPI(deprAPI.getSet(kind), getAnchorName(kind),
getHeadingKey(kind), memberTableHeader, content);
}
}
bodyContents.addMainContent(content);
bodyContents.setFooter(getFooter());
String description = "deprecated elements";
body.add(bodyContents);
printHtmlDocument(null, description, body);
@Override
protected void addExtraSection(DeprecatedAPIListBuilder list, Content content) {
addSummaryAPI(list.getForRemoval(), "forRemoval",
"doclet.For_Removal", "doclet.Element", content);
}
if (!deprAPI.isEmpty() && configuration.mainIndex != null) {
configuration.mainIndex.add(IndexItem.of(IndexItem.Category.TAGS,
resources.getText("doclet.Deprecated_API"), path));
@Override
protected void addExtraIndexLink(DeprecatedAPIListBuilder list, Content target) {
if (!list.getForRemoval().isEmpty()) {
addIndexLink("forRemoval", "doclet.For_Removal", target);
}
}
/**
* Add the index link.
*
* @param builder the deprecated list builder
* @param kind the kind of list being documented
* @param contentTree the content tree to which the index link will be added
*/
private void addIndexLink(DeprecatedAPIListBuilder builder,
DeprElementKind kind, Content contentTree) {
if (builder.hasDocumentation(kind)) {
Content li = HtmlTree.LI(links.createLink(getAnchorName(kind),
contents.getContent(getHeadingKey(kind))));
contentTree.add(li);
protected void addComments(Element e, Content desc) {
List<? extends DeprecatedTree> tags = utils.getDeprecatedTrees(e);
if (!tags.isEmpty()) {
addInlineDeprecatedComment(e, tags.get(0), desc);
} else {
desc.add(HtmlTree.EMPTY);
}
}
/**
* Get the contents list.
*
* @param deprapi the deprecated list builder
* @return a content tree for the contents list
*/
public Content getContentsList(DeprecatedAPIListBuilder deprapi) {
Content headContent = contents.deprecatedAPI;
Content heading = HtmlTree.HEADING_TITLE(Headings.PAGE_TITLE_HEADING,
HtmlStyle.title, headContent);
Content div = HtmlTree.DIV(HtmlStyle.header, heading);
Content headingContent = contents.contentsHeading;
div.add(HtmlTree.HEADING_TITLE(Headings.CONTENT_HEADING,
headingContent));
Content ul = new HtmlTree(TagName.UL);
for (DeprElementKind kind : DeprElementKind.values()) {
addIndexLink(deprapi, kind, ul);
}
div.add(ul);
return div;
}
/**
* Get the header for the deprecated API Listing.
*
* @return a content tree for the header
*/
public HtmlTree getHeader() {
String title = resources.getText("doclet.Window_Deprecated_List");
HtmlTree bodyTree = getBody(getWindowTitle(title));
bodyContents.setHeader(getHeader(PageMode.DEPRECATED));
return bodyTree;
}
/**
* Add deprecated information to the documentation tree
*
* @param deprList list of deprecated API elements
* @param id the id attribute of the table
* @param headingKey the caption for the deprecated table
* @param tableHeader table headers for the deprecated table
* @param contentTree the content tree to which the deprecated table will be added
*/
protected void addDeprecatedAPI(SortedSet<Element> deprList, String id, String headingKey,
TableHeader tableHeader, Content contentTree) {
if (deprList.size() > 0) {
Content caption = contents.getContent(headingKey);
Table table = new Table(HtmlStyle.summaryTable)
.setCaption(caption)
.setHeader(tableHeader)
.setId(id)
.setColumnStyles(HtmlStyle.colDeprecatedItemName, HtmlStyle.colLast);
for (Element e : deprList) {
Content link;
switch (e.getKind()) {
case MODULE:
ModuleElement m = (ModuleElement) e;
link = getModuleLink(m, new StringContent(m.getQualifiedName()));
break;
case PACKAGE:
PackageElement pkg = (PackageElement) e;
link = getPackageLink(pkg, getPackageName(pkg));
break;
default:
link = getDeprecatedLink(e);
}
Content desc = new ContentBuilder();
List<? extends DeprecatedTree> tags = utils.getDeprecatedTrees(e);
if (!tags.isEmpty()) {
addInlineDeprecatedComment(e, tags.get(0), desc);
} else {
desc.add(HtmlTree.EMPTY);
}
table.addRow(link, desc);
}
// note: singleton list
contentTree.add(HtmlTree.UL(HtmlStyle.blockList, HtmlTree.LI(table)));
}
}
protected Content getDeprecatedLink(Element e) {
AbstractMemberWriter writer;
switch (e.getKind()) {
case INTERFACE:
case CLASS:
case ENUM:
case ANNOTATION_TYPE:
case RECORD:
writer = new NestedClassWriterImpl(this);
break;
case FIELD:
writer = new FieldWriterImpl(this);
break;
case METHOD:
writer = new MethodWriterImpl(this);
break;
case CONSTRUCTOR:
writer = new ConstructorWriterImpl(this);
break;
case ENUM_CONSTANT:
writer = new EnumConstantWriterImpl(this);
break;
default:
writer = new AnnotationTypeOptionalMemberWriterImpl(this, null);
}
return writer.getDeprecatedLink(e);
}
}

11
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/EnumConstantWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -109,6 +109,11 @@ public class EnumConstantWriterImpl extends AbstractMemberWriter
addDeprecatedInfo(enumConstant, enumConstantsTree);
}
@Override
public void addPreview(VariableElement enumConstant, Content enumConstantsTree) {
addPreviewInfo(enumConstant, enumConstantsTree);
}
@Override
public void addComments(VariableElement enumConstant, Content enumConstantsTree) {
addComment(enumConstant, enumConstantsTree);
@ -172,9 +177,9 @@ public class EnumConstantWriterImpl extends AbstractMemberWriter
}
@Override
protected Content getDeprecatedLink(Element member) {
protected Content getSummaryLink(Element member) {
String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName();
return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name);
return writer.getDocLink(LinkInfoImpl.Kind.MEMBER_DEPRECATED_PREVIEW, member, name);
}
@Override

11
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FieldWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -109,6 +109,11 @@ public class FieldWriterImpl extends AbstractMemberWriter
addDeprecatedInfo(field, fieldTree);
}
@Override
public void addPreview(VariableElement field, Content fieldTree) {
addPreviewInfo(field, fieldTree);
}
@Override
public void addComments(VariableElement field, Content fieldTree) {
if (!utils.getFullBody(field).isEmpty()) {
@ -199,9 +204,9 @@ public class FieldWriterImpl extends AbstractMemberWriter
}
@Override
protected Content getDeprecatedLink(Element member) {
protected Content getSummaryLink(Element member) {
String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName();
return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name);
return writer.getDocLink(LinkInfoImpl.Kind.MEMBER_DEPRECATED_PREVIEW, member, name);
}
@Override

11
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -232,6 +232,15 @@ public class HelpWriter extends HtmlDocletWriter {
contentTree.add(section);
}
// Preview
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
section = newHelpSection(contents.previewAPI);
Content previewBody = getContent("doclet.help.preview.body",
links.createLink(DocPaths.PREVIEW_LIST, contents.previewAPI));
section.add(HtmlTree.P(previewBody));
contentTree.add(section);
}
// Index
if (options.createIndex()) {
DocPath dp = options.splitIndex()

14
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -60,6 +60,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
/**
* Configure the output based on the command-line options.
@ -120,7 +121,14 @@ public class HtmlConfiguration extends BaseConfiguration {
*/
protected DeprecatedAPIListBuilder deprecatedAPIListBuilder;
private Contents contents;
/**
* The collection of preview items, if any, to be displayed on the preview-list page,
* or null if the page should not be generated.
* The page will not be generated if there are no preview elements being documented.
*/
protected PreviewAPIListBuilder previewAPIListBuilder;
public Contents contents;
protected final Messages messages;
@ -136,7 +144,7 @@ public class HtmlConfiguration extends BaseConfiguration {
// Note: this should (eventually) be merged with Navigation.PageMode,
// which performs a somewhat similar role
public enum ConditionalPage {
CONSTANT_VALUES, DEPRECATED, SERIALIZED_FORM, SYSTEM_PROPERTIES
CONSTANT_VALUES, DEPRECATED, PREVIEW, SERIALIZED_FORM, SYSTEM_PROPERTIES
}
/**

12
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -48,6 +48,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
/**
* The class with "start" method, calls individual Writers.
@ -175,6 +176,11 @@ public class HtmlDoclet extends AbstractDoclet {
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.DEPRECATED);
}
}
PreviewAPIListBuilder builder = new PreviewAPIListBuilder(configuration);
if (!builder.isEmpty()) {
configuration.previewAPIListBuilder = builder;
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.PREVIEW);
}
super.generateClassFiles(classTree);
}
@ -223,6 +229,10 @@ public class HtmlDoclet extends AbstractDoclet {
DeprecatedListWriter.generate(configuration);
}
if (configuration.conditionalPages.contains((HtmlConfiguration.ConditionalPage.PREVIEW))) {
PreviewListWriter.generate(configuration);
}
if (options.createOverview()) {
if (configuration.showModules) {
ModuleIndexWriter.generate(configuration);

244
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -27,7 +27,9 @@ package jdk.javadoc.internal.doclets.formats.html;
import java.util.ArrayList;
import java.util.Collections;
import java.util.EnumSet;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedList;
import java.util.List;
import java.util.ListIterator;
@ -105,8 +107,11 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
import jdk.javadoc.internal.doclets.toolkit.util.Utils.DeclarationPreviewLanguageFeatures;
import jdk.javadoc.internal.doclets.toolkit.util.Utils.ElementFlag;
import jdk.javadoc.internal.doclets.toolkit.util.Utils.PreviewSummary;
import static com.sun.source.doctree.DocTree.Kind.CODE;
import static com.sun.source.doctree.DocTree.Kind.COMMENT;
@ -648,16 +653,35 @@ public class HtmlDocletWriter {
}
}
}
if (included || packageElement == null) {
return links.createLink(pathString(packageElement, DocPaths.PACKAGE_SUMMARY),
label);
Set<ElementFlag> flags;
if (packageElement != null) {
flags = utils.elementFlags(packageElement);
} else {
DocLink crossPkgLink = getCrossPackageLink(packageElement);
if (crossPkgLink != null) {
return links.createLink(crossPkgLink, label);
} else {
return label;
flags = EnumSet.noneOf(ElementFlag.class);
}
DocLink targetLink = null;
if (included || packageElement == null) {
targetLink = new DocLink(pathString(packageElement, DocPaths.PACKAGE_SUMMARY));
} else {
targetLink = getCrossPackageLink(packageElement);
}
if (targetLink != null) {
if (flags.contains(ElementFlag.PREVIEW)) {
return new ContentBuilder(
links.createLink(targetLink, label),
HtmlTree.SUP(links.createLink(targetLink.withFragment(getPreviewSectionAnchor(packageElement)),
contents.previewMark))
);
}
return links.createLink(targetLink, label);
} else {
if (flags.contains(ElementFlag.PREVIEW)) {
return new ContentBuilder(
label,
HtmlTree.SUP(contents.previewMark)
);
}
return label;
}
}
@ -669,10 +693,28 @@ public class HtmlDocletWriter {
* @return a content for the module link
*/
public Content getModuleLink(ModuleElement mdle, Content label) {
Set<ElementFlag> flags = mdle != null ? utils.elementFlags(mdle)
: EnumSet.noneOf(ElementFlag.class);
boolean included = utils.isIncluded(mdle);
return (included)
? links.createLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)), label, "", "")
: label;
if (included) {
DocLink targetLink = new DocLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)));
Content link = links.createLink(targetLink, label, "", "");
if (flags.contains(ElementFlag.PREVIEW) && label != contents.moduleLabel) {
link = new ContentBuilder(
link,
HtmlTree.SUP(links.createLink(targetLink.withFragment(getPreviewSectionAnchor(mdle)),
contents.previewMark))
);
}
return link;
}
if (flags.contains(ElementFlag.PREVIEW)) {
return new ContentBuilder(
label,
HtmlTree.SUP(contents.previewMark)
);
}
return label;
}
public Content interfaceName(TypeElement typeElement, boolean qual) {
@ -969,6 +1011,7 @@ public class HtmlDocletWriter {
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(links.getAnchor(ee, isProperty))
.targetMember(element)
.strong(strong));
}
@ -976,6 +1019,7 @@ public class HtmlDocletWriter {
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(links.getName(element.getSimpleName().toString()))
.targetMember(element)
.strong(strong));
}
@ -1001,10 +1045,11 @@ public class HtmlDocletWriter {
ExecutableElement emd = (ExecutableElement) element;
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(links.getAnchor(emd)));
.where(links.getAnchor(emd))
.targetMember(element));
} else if (utils.isVariableElement(element) || utils.isTypeElement(element)) {
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label).where(links.getName(element.getSimpleName().toString())));
.label(label).where(links.getName(element.getSimpleName().toString())).targetMember(element));
} else {
return label;
}
@ -1198,6 +1243,17 @@ public class HtmlDocletWriter {
addSummaryComment(element, utils.getFirstSentenceTrees(element), htmltree);
}
/**
* Adds the preview content.
*
* @param element the Element for which the summary will be generated
* @param firstSentenceTags the first sentence tags for the doc
* @param htmltree the documentation tree to which the summary will be added
*/
public void addPreviewComment(Element element, List<? extends DocTree> firstSentenceTags, Content htmltree) {
addCommentTags(element, firstSentenceTags, false, true, true, htmltree);
}
/**
* Adds the summary content.
*
@ -1261,8 +1317,7 @@ public class HtmlDocletWriter {
if (depr) {
div = HtmlTree.DIV(HtmlStyle.deprecationComment, result);
htmltree.add(div);
}
else {
} else {
div = HtmlTree.DIV(HtmlStyle.block, result);
htmltree.add(div);
}
@ -2120,4 +2175,159 @@ public class HtmlDocletWriter {
Content getVerticalSeparator() {
return HtmlTree.SPAN(HtmlStyle.verticalSeparator, new FixedStringContent("|"));
}
public void addPreviewSummary(Element forWhat, Content target) {
if (utils.isPreviewAPI(forWhat)) {
Content div = HtmlTree.DIV(HtmlStyle.block);
div.add(HtmlTree.SPAN(HtmlStyle.previewLabel, contents.previewPhrase));
target.add(div);
}
}
public void addPreviewInfo(Element forWhat, Content target) {
if (utils.isPreviewAPI(forWhat)) {
//in Java platform:
HtmlTree previewDiv = HtmlTree.DIV(HtmlStyle.previewBlock);
previewDiv.setId(getPreviewSectionAnchor(forWhat));
String name = (switch (forWhat.getKind()) {
case PACKAGE, MODULE ->
((QualifiedNameable) forWhat).getQualifiedName();
case CONSTRUCTOR ->
((TypeElement) forWhat.getEnclosingElement()).getSimpleName();
default -> forWhat.getSimpleName();
}).toString();
Content nameCode = HtmlTree.CODE(new StringContent(name));
boolean isReflectivePreview = utils.isReflectivePreviewAPI(forWhat);
String leadingNoteKey =
!isReflectivePreview ? "doclet.PreviewPlatformLeadingNote"
: "doclet.ReflectivePreviewPlatformLeadingNote";
Content leadingNote =
contents.getContent(leadingNoteKey, nameCode);
previewDiv.add(HtmlTree.SPAN(HtmlStyle.previewLabel,
leadingNote));
if (!isReflectivePreview) {
Content note1 = contents.getContent("doclet.PreviewTrailingNote1", nameCode);
previewDiv.add(HtmlTree.DIV(HtmlStyle.previewComment, note1));
}
Content note2 = contents.getContent("doclet.PreviewTrailingNote2", nameCode);
previewDiv.add(HtmlTree.DIV(HtmlStyle.previewComment, note2));
target.add(previewDiv);
} else if (forWhat.getKind().isClass() || forWhat.getKind().isInterface()) {
//in custom code:
List<Content> previewNotes = getPreviewNotes((TypeElement) forWhat);
if (!previewNotes.isEmpty()) {
Name name = forWhat.getSimpleName();
Content nameCode = HtmlTree.CODE(new StringContent(name));
HtmlTree previewDiv = HtmlTree.DIV(HtmlStyle.previewBlock);
previewDiv.setId(getPreviewSectionAnchor(forWhat));
Content leadingNote = contents.getContent("doclet.PreviewLeadingNote", nameCode);
previewDiv.add(HtmlTree.SPAN(HtmlStyle.previewLabel,
leadingNote));
HtmlTree ul = new HtmlTree(TagName.UL);
ul.setStyle(HtmlStyle.previewComment);
for (Content note : previewNotes) {
ul.add(HtmlTree.LI(note));
}
previewDiv.add(ul);
Content note1 =
contents.getContent("doclet.PreviewTrailingNote1",
nameCode);
previewDiv.add(HtmlTree.DIV(HtmlStyle.previewComment, note1));
Content note2 =
contents.getContent("doclet.PreviewTrailingNote2",
name);
previewDiv.add(HtmlTree.DIV(HtmlStyle.previewComment, note2));
target.add(previewDiv);
}
}
}
@SuppressWarnings("preview")
private List<Content> getPreviewNotes(TypeElement el) {
String className = el.getSimpleName().toString();
List<Content> result = new ArrayList<>();
PreviewSummary previewAPITypes = utils.declaredUsingPreviewAPIs(el);
Set<TypeElement> previewAPI = new HashSet<>(previewAPITypes.previewAPI);
Set<TypeElement> reflectivePreviewAPI = new HashSet<>(previewAPITypes.reflectivePreviewAPI);
Set<TypeElement> declaredUsingPreviewFeature = new HashSet<>(previewAPITypes.declaredUsingPreviewFeature);
Set<DeclarationPreviewLanguageFeatures> previewLanguageFeatures = new HashSet<>();
for (Element enclosed : el.getEnclosedElements()) {
if (!utils.isIncluded(enclosed)) {
continue;
}
if (!enclosed.getKind().isClass() && !enclosed.getKind().isInterface()) {
PreviewSummary memberAPITypes = utils.declaredUsingPreviewAPIs(enclosed);
declaredUsingPreviewFeature.addAll(memberAPITypes.declaredUsingPreviewFeature);
previewAPI.addAll(memberAPITypes.previewAPI);
reflectivePreviewAPI.addAll(memberAPITypes.reflectivePreviewAPI);
previewLanguageFeatures.addAll(utils.previewLanguageFeaturesUsed(enclosed));
} else if (!utils.previewLanguageFeaturesUsed(enclosed).isEmpty()) {
declaredUsingPreviewFeature.add((TypeElement) enclosed);
}
}
previewLanguageFeatures.addAll(utils.previewLanguageFeaturesUsed(el));
if (!previewLanguageFeatures.isEmpty()) {
if (previewLanguageFeatures.contains(DeclarationPreviewLanguageFeatures.SEALED_PERMITS)) {
previewLanguageFeatures.remove(DeclarationPreviewLanguageFeatures.SEALED);
}
for (DeclarationPreviewLanguageFeatures feature : previewLanguageFeatures) {
String featureDisplayName =
resources.getText("doclet.Declared_Using_Preview." + feature.name());
result.add(withPreviewFeatures("doclet.Declared_Using_Preview", className,
featureDisplayName, feature.features));
}
}
if (!declaredUsingPreviewFeature.isEmpty()) {
result.add(withLinks("doclet.UsesDeclaredUsingPreview", className, declaredUsingPreviewFeature));
}
if (!previewAPI.isEmpty()) {
result.add(withLinks("doclet.PreviewAPI", className, previewAPI));
}
if (!reflectivePreviewAPI.isEmpty()) {
result.add(withLinks("doclet.ReflectivePreviewAPI", className, reflectivePreviewAPI));
}
return result;
}
private Content withPreviewFeatures(String key, String className, String featureName, List<String> features) {
String[] sep = new String[] {""};
ContentBuilder featureCodes = new ContentBuilder();
features.stream()
.forEach(c -> {
featureCodes.add(sep[0]);
featureCodes.add(HtmlTree.CODE(new ContentBuilder().add(c)));
sep[0] = ", ";
});
return contents.getContent(key,
HtmlTree.CODE(new StringContent(className)),
new HtmlTree(TagName.EM).add(featureName),
featureCodes);
}
private Content withLinks(String key, String className, Set<TypeElement> elements) {
String[] sep = new String[] {""};
ContentBuilder links = new ContentBuilder();
elements.stream()
.sorted((te1, te2) -> te1.getSimpleName().toString().compareTo(te2.getSimpleName().toString()))
.distinct()
.map(te -> getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.CLASS, te).label(HtmlTree.CODE(new StringContent(te.getSimpleName()))).skipPreview(true)))
.forEach(c -> {
links.add(sep[0]);
links.add(c);
sep[0] = ", ";
});
return contents.getContent(key,
HtmlTree.CODE(new StringContent(className)),
links);
}
public String getPreviewSectionAnchor(Element el) {
return "preview-" + switch (el.getKind()) {
case CONSTRUCTOR, METHOD ->
links.getAnchor((ExecutableElement) el);
case PACKAGE -> getPackageAnchorName((PackageElement) el);
default -> utils.getFullyQualifiedName(el, false);
};
}
}

41
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/LinkFactoryImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -26,7 +26,9 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.util.ArrayList;
import java.util.EnumSet;
import java.util.List;
import java.util.Set;
import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.element.Element;
@ -36,12 +38,15 @@ import javax.lang.model.type.TypeMirror;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
import jdk.javadoc.internal.doclets.toolkit.util.Utils.ElementFlag;
import jdk.javadoc.internal.doclets.toolkit.util.links.LinkFactory;
import jdk.javadoc.internal.doclets.toolkit.util.links.LinkInfo;
@ -78,12 +83,27 @@ public class LinkFactoryImpl extends LinkFactory {
// Create a tool tip if we are linking to a class or interface. Don't
// create one if we are linking to a member.
String title = "";
if (classLinkInfo.where == null || classLinkInfo.where.length() == 0) {
boolean hasWhere = classLinkInfo.where != null && classLinkInfo.where.length() != 0;
if (!hasWhere) {
boolean isTypeLink = classLinkInfo.type != null &&
utils.isTypeVariable(utils.getComponentType(classLinkInfo.type));
title = getClassToolTip(typeElement, isTypeLink);
}
Content label = classLinkInfo.getClassLinkLabel(configuration);
Set<ElementFlag> flags;
Element target;
boolean showPreview = !classLinkInfo.skipPreview;
if (!hasWhere && showPreview) {
flags = utils.elementFlags(typeElement);
target = typeElement;
} else if ((classLinkInfo.context == LinkInfoImpl.Kind.SEE_TAG || classLinkInfo.context == LinkInfoImpl.Kind.MEMBER_DEPRECATED_PREVIEW) &&
classLinkInfo.targetMember != null && showPreview) {
flags = utils.elementFlags(classLinkInfo.targetMember);
target = classLinkInfo.targetMember;
} else {
flags = EnumSet.noneOf(ElementFlag.class);
target = null;
}
Content link = new ContentBuilder();
if (utils.isIncluded(typeElement)) {
@ -97,6 +117,11 @@ public class LinkFactoryImpl extends LinkFactory {
classLinkInfo.isStrong,
title,
classLinkInfo.target));
if (flags.contains(ElementFlag.PREVIEW)) {
link.add(HtmlTree.SUP(m_writer.links.createLink(
filename.fragment(m_writer.getPreviewSectionAnchor(target)),
m_writer.contents.previewMark)));
}
if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
link.add(getTypeParameterLinks(linkInfo));
}
@ -109,6 +134,13 @@ public class LinkFactoryImpl extends LinkFactory {
label, classLinkInfo.isStrong, true);
if (crossLink != null) {
link.add(crossLink);
if (flags.contains(ElementFlag.PREVIEW)) {
link.add(HtmlTree.SUP(m_writer.getCrossClassLink(
typeElement,
m_writer.getPreviewSectionAnchor(target),
m_writer.contents.previewMark,
false, false)));
}
if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
link.add(getTypeParameterLinks(linkInfo));
}
@ -117,6 +149,9 @@ public class LinkFactoryImpl extends LinkFactory {
}
// Can't link so just write label.
link.add(label);
if (flags.contains(ElementFlag.PREVIEW)) {
link.add(HtmlTree.SUP(m_writer.contents.previewMark));
}
if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
link.add(getTypeParameterLinks(linkInfo));
}
@ -171,7 +206,7 @@ public class LinkFactoryImpl extends LinkFactory {
*/
protected Content getTypeParameterLink(LinkInfo linkInfo, TypeMirror typeParam) {
LinkInfoImpl typeLinkInfo = new LinkInfoImpl(m_writer.configuration,
((LinkInfoImpl) linkInfo).getContext(), typeParam);
((LinkInfoImpl) linkInfo).getContext(), typeParam).skipPreview(true);
typeLinkInfo.excludeTypeBounds = linkInfo.excludeTypeBounds;
typeLinkInfo.excludeTypeParameterLinks = linkInfo.excludeTypeParameterLinks;
typeLinkInfo.linkToSelf = linkInfo.linkToSelf;

31
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/LinkInfoImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -25,6 +25,7 @@
package jdk.javadoc.internal.doclets.formats.html;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.type.TypeMirror;
@ -57,6 +58,11 @@ public class LinkInfoImpl extends LinkInfo {
*/
MEMBER,
/**
* Indicate that the link appears in member documentation on the Deprecated or Preview page.
*/
MEMBER_DEPRECATED_PREVIEW,
/**
* Indicate that the link appears in class use documentation.
*/
@ -235,6 +241,11 @@ public class LinkInfoImpl extends LinkInfo {
*/
public String where = "";
/**
* The member this link points to (if any).
*/
public Element targetMember;
/**
* The value of the target.
*/
@ -335,7 +346,23 @@ public class LinkInfoImpl extends LinkInfo {
public LinkInfoImpl where(String where) {
this.where = where;
return this;
}
}
/**
* Set the member this link points to (if any).
*/
public LinkInfoImpl targetMember(Element el) {
this.targetMember = el;
return this;
}
/**
* Set whether or not the preview flags should be skipped for this link.
*/
public LinkInfoImpl skipPreview(boolean skipPreview) {
this.skipPreview = skipPreview;
return this;
}
public Kind getContext() {
return context;

9
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -25,12 +25,14 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.util.List;
import java.util.SortedSet;
import java.util.TreeSet;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.type.DeclaredType;
import javax.lang.model.type.TypeMirror;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
@ -136,6 +138,11 @@ public class MethodWriterImpl extends AbstractExecutableMemberWriter
addDeprecatedInfo(method, methodDocTree);
}
@Override
public void addPreview(ExecutableElement method, Content methodDocTree) {
addPreviewInfo(method, methodDocTree);
}
@Override
public void addComments(TypeMirror holderType, ExecutableElement method, Content methodDocTree) {
TypeElement holder = utils.asTypeElement(holderType);

3
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -109,6 +109,7 @@ public class ModuleIndexWriter extends AbstractOverviewIndexWriter {
if (!(options.noDeprecated() && utils.isDeprecated(mdle))) {
Content moduleLinkContent = getModuleLink(mdle, new StringContent(mdle.getQualifiedName().toString()));
Content summaryContent = new ContentBuilder();
addPreviewSummary(mdle, summaryContent);
addSummaryComment(mdle, summaryContent);
table.addRow(mdle, moduleLinkContent, summaryContent);
}

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -617,6 +617,7 @@ public class ModuleWriterImpl extends HtmlDocletWriter implements ModuleSummaryW
row.add(getPackageExportOpensTo(entry.openedTo));
}
Content summary = new ContentBuilder();
addPreviewSummary(pkg, summary);
addSummaryComment(pkg, summary);
row.add(summary);
@ -811,6 +812,7 @@ public class ModuleWriterImpl extends HtmlDocletWriter implements ModuleSummaryW
@Override
public void addModuleDescription(Content moduleContentTree) {
addPreviewInfo(mdle, moduleContentTree);
if (!utils.getFullBody(mdle).isEmpty()) {
HtmlTree tree = HtmlTree.SECTION(HtmlStyle.moduleDescription);
tree.setId(SectionName.MODULE_DESCRIPTION.getName());

25
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -97,6 +97,7 @@ public class Navigation {
MODULE,
OVERVIEW,
PACKAGE,
PREVIEW,
SERIALIZED_FORM,
SYSTEM_PROPERTIES,
TREE,
@ -185,6 +186,7 @@ public class Navigation {
addPageLabel(tree, contents.useLabel, options.classUse());
addTreeLink(tree);
addDeprecatedLink(tree);
addPreviewLink(tree);
addIndexLink(tree);
addHelpLink(tree);
break;
@ -196,6 +198,7 @@ public class Navigation {
addPageLabel(tree, contents.useLabel, options.classUse());
addTreeLink(tree);
addDeprecatedLink(tree);
addPreviewLink(tree);
addIndexLink(tree);
addHelpLink(tree);
break;
@ -213,6 +216,7 @@ public class Navigation {
contents.treeLabel, "", ""));
}
addDeprecatedLink(tree);
addPreviewLink(tree);
addIndexLink(tree);
addHelpLink(tree);
break;
@ -230,6 +234,7 @@ public class Navigation {
contents.treeLabel, "", ""));
}
addDeprecatedLink(tree);
addPreviewLink(tree);
addIndexLink(tree);
addHelpLink(tree);
break;
@ -252,6 +257,7 @@ public class Navigation {
: links.createLink(pathToRoot.resolve(DocPaths.OVERVIEW_TREE), contents.treeLabel));
}
addDeprecatedLink(tree);
addPreviewLink(tree);
addIndexLink(tree);
addHelpLink(tree);
break;
@ -268,12 +274,14 @@ public class Navigation {
addPageLabel(tree, contents.useLabel, options.classUse());
addActivePageLink(tree, contents.treeLabel, options.createTree());
addDeprecatedLink(tree);
addPreviewLink(tree);
addIndexLink(tree);
addHelpLink(tree);
break;
case DEPRECATED:
case INDEX:
case HELP:
case PREVIEW:
addOverviewLink(tree);
addModuleLink(tree);
addPackageLink(tree);
@ -286,6 +294,12 @@ public class Navigation {
} else {
addDeprecatedLink(tree);
}
if (documentedPage == PageMode.PREVIEW) {
addActivePageLink(tree, contents.previewLabel,
configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW));
} else {
addPreviewLink(tree);
}
if (documentedPage == PageMode.INDEX) {
addActivePageLink(tree, contents.indexLabel, options.createIndex());
} else {
@ -309,6 +323,7 @@ public class Navigation {
addPageLabel(tree, contents.useLabel, options.classUse());
addTreeLink(tree);
addDeprecatedLink(tree);
addPreviewLink(tree);
addIndexLink(tree);
addHelpLink(tree);
break;
@ -320,6 +335,7 @@ public class Navigation {
addPageLabel(tree, contents.useLabel, options.classUse());
addTreeLink(tree);
addDeprecatedLink(tree);
addPreviewLink(tree);
addIndexLink(tree);
addHelpLink(tree);
break;
@ -842,6 +858,13 @@ public class Navigation {
}
}
private void addPreviewLink(Content tree) {
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
tree.add(HtmlTree.LI(links.createLink(pathToRoot.resolve(DocPaths.PREVIEW_LIST),
contents.previewLabel, "", "")));
}
}
private void addIndexLink(Content tree) {
if (options.createIndex()) {
tree.add(HtmlTree.LI(links.createLink(pathToRoot.resolve(

6
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/NestedClassWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -145,7 +145,7 @@ public class NestedClassWriterImpl extends AbstractMemberWriter
}
@Override
protected Content getDeprecatedLink(Element member) {
return writer.getQualifiedClassLink(LinkInfoImpl.Kind.MEMBER, member);
protected Content getSummaryLink(Element member) {
return writer.getQualifiedClassLink(LinkInfoImpl.Kind.MEMBER_DEPRECATED_PREVIEW, member);
}
}

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -218,6 +218,7 @@ public class PackageWriterImpl extends HtmlDocletWriter
Content classLink = getLink(new LinkInfoImpl(
configuration, LinkInfoImpl.Kind.PACKAGE, klass));
ContentBuilder description = new ContentBuilder();
addPreviewSummary(klass, description);
if (utils.isDeprecated(klass)) {
description.add(getDeprecatedPhrase(klass));
List<? extends DeprecatedTree> tags = utils.getDeprecatedTrees(klass);
@ -235,6 +236,7 @@ public class PackageWriterImpl extends HtmlDocletWriter
@Override
public void addPackageDescription(Content packageContentTree) {
addPreviewInfo(packageElement, packageContentTree);
if (!utils.getBody(packageElement).isEmpty()) {
HtmlTree tree = sectionTree;
tree.setId(SectionName.PACKAGE_DESCRIPTION.getName());

93
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PreviewListWriter.java Normal file
View File

@ -0,0 +1,93 @@
/*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.javadoc.internal.doclets.formats.html;
import java.util.List;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
/**
* Generate File to list all the preview elements with the
* appropriate links.
*
* <p><b>This is NOT part of any supported API.
* If you write code that depends on this, you do so at your own risk.
* This code and its internal interfaces are subject to change or
* deletion without notice.</b>
*
* @see java.util.List
*/
public class PreviewListWriter extends SummaryListWriter<PreviewAPIListBuilder> {
/**
* Constructor.
*
* @param configuration the configuration for this doclet
* @param filename the file to be generated
*/
public PreviewListWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename, PageMode.PREVIEW, "preview elements",
configuration.contents.previewAPI, "doclet.Window_Preview_List");
}
/**
* Get list of all the preview elements.
* Then instantiate PreviewListWriter and generate File.
*
* @param configuration the current configuration of the doclet.
* @throws DocFileIOException if there is a problem writing the preview list
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
DocPath filename = DocPaths.PREVIEW_LIST;
PreviewListWriter depr = new PreviewListWriter(configuration, filename);
depr.generateSummaryListFile(
new PreviewAPIListBuilder(configuration));
}
}
@Override
protected void addComments(Element e, Content desc) {
List<? extends DocTree> tags = utils.getFirstSentenceTrees(e);
if (!tags.isEmpty()) {
addPreviewComment(e, tags, desc);
} else {
desc.add(HtmlTree.EMPTY);
}
}
}

10
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PropertyWriterImpl.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -101,6 +101,10 @@ public class PropertyWriterImpl extends AbstractMemberWriter
public void addDeprecated(ExecutableElement property, Content propertyDocTree) {
}
@Override
public void addPreview(ExecutableElement property, Content propertyDocTree) {
}
@Override
public void addComments(ExecutableElement property, Content propertyDocTree) {
TypeElement holder = (TypeElement)property.getEnclosingElement();
@ -215,8 +219,8 @@ public class PropertyWriterImpl extends AbstractMemberWriter
}
@Override
protected Content getDeprecatedLink(Element member) {
return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member,
protected Content getSummaryLink(Element member) {
return writer.getDocLink(LinkInfoImpl.Kind.MEMBER_DEPRECATED_PREVIEW, member,
utils.getFullyQualifiedName(member));
}

7
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java
View File

@ -156,7 +156,12 @@ public class Signatures {
for (TypeMirror type : linkablePermits) {
if (isFirst) {
content.add(DocletConstants.NL);
permitsSpan.add("permits ");
permitsSpan.add("permits");
Content link =
classWriter.links.createLink(classWriter.getPreviewSectionAnchor(typeElement),
classWriter.contents.previewMark);
permitsSpan.add(HtmlTree.SUP(link));
permitsSpan.add(" ");
isFirst = false;
} else {
permitsSpan.add(", ");

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SubWriterHolderWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -37,6 +37,7 @@ import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
@ -109,6 +110,7 @@ public abstract class SubWriterHolderWriter extends HtmlDocletWriter {
*/
protected void addIndexComment(Element member, List<? extends DocTree> firstSentenceTags,
Content tdSummary) {
addPreviewSummary(member, tdSummary);
List<? extends DeprecatedTree> deprs = utils.getDeprecatedTrees(member);
Content div;
if (utils.isDeprecated(member)) {

303
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SummaryListWriter.java Normal file
View File

@ -0,0 +1,303 @@
/*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.javadoc.internal.doclets.formats.html;
import java.util.SortedSet;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.Table;
import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.SummaryAPIListBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.SummaryAPIListBuilder.SummaryElementKind;
/**
* Generate File to list all the summary elements with the
* appropriate links.
*
* <p><b>This is NOT part of any supported API.
* If you write code that depends on this, you do so at your own risk.
* This code and its internal interfaces are subject to change or
* deletion without notice.</b>
*
* @see java.util.List
*/
public abstract class SummaryListWriter<L extends SummaryAPIListBuilder> extends SubWriterHolderWriter {
private String getAnchorName(SummaryElementKind kind) {
return switch (kind) {
case MODULE -> "module";
case PACKAGE -> "package";
case INTERFACE -> "interface";
case CLASS -> "class";
case ENUM -> "enum.class";
case EXCEPTION -> "exception";
case ERROR -> "error";
case ANNOTATION_TYPE -> "annotation.interface";
case FIELD -> "field";
case METHOD -> "method";
case CONSTRUCTOR -> "constructor";
case ENUM_CONSTANT -> "enum.constant";
case ANNOTATION_TYPE_MEMBER -> "annotation.interface.member";
case RECORD_CLASS -> "record.class";
};
}
private String getHeadingKey(SummaryElementKind kind) {
return switch (kind) {
case MODULE -> "doclet.Modules";
case PACKAGE -> "doclet.Packages";
case INTERFACE -> "doclet.Interfaces";
case CLASS -> "doclet.Classes";
case ENUM -> "doclet.Enums";
case EXCEPTION -> "doclet.Exceptions";
case ERROR -> "doclet.Errors";
case ANNOTATION_TYPE -> "doclet.Annotation_Types";
case FIELD -> "doclet.Fields";
case METHOD -> "doclet.Methods";
case CONSTRUCTOR -> "doclet.Constructors";
case ENUM_CONSTANT -> "doclet.Enum_Constants";
case ANNOTATION_TYPE_MEMBER -> "doclet.Annotation_Type_Members";
case RECORD_CLASS -> "doclet.RecordClasses";
};
}
private String getHeaderKey(SummaryElementKind kind) {
return switch (kind) {
case MODULE -> "doclet.Module";
case PACKAGE -> "doclet.Package";
case INTERFACE -> "doclet.Interface";
case CLASS -> "doclet.Class";
case ENUM -> "doclet.Enum";
case EXCEPTION -> "doclet.Exceptions";
case ERROR -> "doclet.Errors";
case ANNOTATION_TYPE -> "doclet.AnnotationType";
case FIELD -> "doclet.Field";
case METHOD -> "doclet.Method";
case CONSTRUCTOR -> "doclet.Constructor";
case ENUM_CONSTANT -> "doclet.Enum_Constant";
case ANNOTATION_TYPE_MEMBER -> "doclet.Annotation_Type_Member";
case RECORD_CLASS -> "doclet.RecordClass";
};
}
private final PageMode pageMode;
private final String description;
private final Content headContent;
private final String titleKey;
/**
* Constructor.
*
* @param configuration the configuration for this doclet
* @param filename the file to be generated
* @param pageMode page mode to use
* @param description page description
* @param headContent page heading content
* @param titleKey page title resource key
*/
public SummaryListWriter(HtmlConfiguration configuration, DocPath filename,
PageMode pageMode, String description,
Content headContent, String titleKey) {
super(configuration, filename);
this.pageMode = pageMode;
this.description = description;
this.headContent = headContent;
this.titleKey = titleKey;
}
/**
* Generate the API summary.
*
* @param summaryapi list of API summary built already.
* @throws DocFileIOException if there is a problem writing the summary list
*/
protected void generateSummaryListFile(L summaryapi)
throws DocFileIOException {
HtmlTree body = getHeader();
bodyContents.addMainContent(getContentsList(summaryapi));
Content content = new ContentBuilder();
addExtraSection(summaryapi, content);
for (SummaryElementKind kind : SummaryElementKind.values()) {
if (summaryapi.hasDocumentation(kind)) {
addSummaryAPI(summaryapi.getSet(kind), getAnchorName(kind),
getHeadingKey(kind), getHeaderKey(kind), content);
}
}
bodyContents.addMainContent(content);
bodyContents.setFooter(getFooter());
body.add(bodyContents);
printHtmlDocument(null, description, body);
}
/**
* Add the index link.
*
* @param builder the summary list builder
* @param kind the kind of list being documented
* @param contentTree the content tree to which the index link will be added
*/
protected void addIndexLink(String anchorName, String headingKey,
Content contentTree) {
Content li = HtmlTree.LI(links.createLink(anchorName,
contents.getContent(headingKey)));
contentTree.add(li);
}
/**
* Get the contents list.
*
* @param apisummary the summary list builder
* @return a content tree for the contents list
*/
public Content getContentsList(L apisummary) {
Content heading = HtmlTree.HEADING_TITLE(Headings.PAGE_TITLE_HEADING,
HtmlStyle.title, headContent);
Content div = HtmlTree.DIV(HtmlStyle.header, heading);
Content headingContent = contents.contentsHeading;
div.add(HtmlTree.HEADING_TITLE(Headings.CONTENT_HEADING,
headingContent));
Content ul = new HtmlTree(TagName.UL);
addExtraIndexLink(apisummary, ul);
for (SummaryElementKind kind : SummaryElementKind.values()) {
if (apisummary.hasDocumentation(kind)) {
addIndexLink(getAnchorName(kind), getHeadingKey(kind), ul);
}
}
div.add(ul);
return div;
}
/**
* Get the header for the API Summary Listing.
*
* @return a content tree for the header
*/
public HtmlTree getHeader() {
String title = resources.getText(titleKey);
HtmlTree bodyTree = getBody(getWindowTitle(title));
bodyContents.setHeader(getHeader(pageMode));
return bodyTree;
}
/**
* Add summary information to the documentation tree
*
* @param apiList list of API summary elements
* @param id the id attribute of the table
* @param headingKey the caption for the summary table
* @param headerKey table header key for the summary table
* @param contentTree the content tree to which the summary table will be added
*/
protected void addSummaryAPI(SortedSet<Element> apiList, String id,
String headingKey, String headerKey,
Content contentTree) {
if (apiList.size() > 0) {
TableHeader tableHeader = new TableHeader(
contents.getContent(headerKey), contents.descriptionLabel);
Content caption = contents.getContent(headingKey);
Table table = new Table(HtmlStyle.summaryTable)
.setCaption(caption)
.setHeader(tableHeader)
.setId(id)
.setColumnStyles(HtmlStyle.colSummaryItemName, HtmlStyle.colLast);
for (Element e : apiList) {
Content link;
switch (e.getKind()) {
case MODULE:
ModuleElement m = (ModuleElement) e;
link = getModuleLink(m, new StringContent(m.getQualifiedName()));
break;
case PACKAGE:
PackageElement pkg = (PackageElement) e;
link = getPackageLink(pkg, getPackageName(pkg));
break;
default:
link = getSummaryLink(e);
}
Content desc = new ContentBuilder();
addComments(e, desc);
table.addRow(link, desc);
}
// note: singleton list
contentTree.add(HtmlTree.UL(HtmlStyle.blockList, HtmlTree.LI(table)));
}
}
/**
* Add summary text for the given element.
*
* @param e the element for which the summary text should be added
* @param desc the target to which the text should be added
*/
protected abstract void addComments(Element e, Content desc);
protected Content getSummaryLink(Element e) {
AbstractMemberWriter writer = switch (e.getKind()) {
case INTERFACE, CLASS, ENUM,
ANNOTATION_TYPE, RECORD -> new NestedClassWriterImpl(this);
case FIELD -> new FieldWriterImpl(this);
case METHOD -> new MethodWriterImpl(this);
case CONSTRUCTOR -> new ConstructorWriterImpl(this);
case ENUM_CONSTANT -> new EnumConstantWriterImpl(this);
case RECORD_COMPONENT ->
throw new AssertionError("Record components are not supported by SummaryListWriter!");
default -> new AnnotationTypeOptionalMemberWriterImpl(this, null);
};
return writer.getSummaryLink(e);
}
/**
* Add an extra optional section to the content.
*
* @param list the element list
* @param target the target content to which the section should be added
*/
protected void addExtraSection(L list, Content target) {
}
/**
* Add an extra optional index link.
*
* @param list the element list
* @param target the target content to which the link should be added
*/
protected void addExtraIndexLink(L list, Content target) {
}
}

22
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2010, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2010, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -78,6 +78,9 @@ public enum HtmlStyle {
packageHierarchyLabel,
packageUses,
permitsNote,
previewBlock,
previewComment,
previewLabel,
searchTagLink,
searchTagResult,
serializedPackageContainer,
@ -418,12 +421,6 @@ public enum HtmlStyle {
*/
colConstructorName,
/**
* The class of the cells in a table column used to display the name
* of a deprecated item.
*/
colDeprecatedItemName,
/**
* The class of the first column of cells in a table.
* This is typically the "type and modifiers" column, where the type is
@ -438,6 +435,12 @@ public enum HtmlStyle {
*/
colLast,
/**
* The class of the cells in a table column used to display the name
* of a summary item.
*/
colSummaryItemName,
/**
* The class of the second column of cells in a table.
* This is typically the column that defines the name of a field or the
@ -690,6 +693,11 @@ public enum HtmlStyle {
*/
packageUsePage,
/**
* The class of the {@code body} element for the page listing any deprecated items.
*/
previewListPage,
/**
* The class of the {@code body} element for the serialized-forms page.
*/

15
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2010, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2010, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -783,6 +783,17 @@ public class HtmlTree extends Content {
.add(body);
}
/**
* Creates an HTML {@code SUP} element with the given content.
*
* @param body the content
* @return the element
*/
public static HtmlTree SUP(Content body) {
return new HtmlTree(TagName.SUP)
.add(body);
}
/**
* Creates an HTML {@code TD} element with the given style and some content.
*
@ -929,7 +940,7 @@ public class HtmlTree extends Content {
public boolean isInline() {
switch (tagName) {
case A: case BUTTON: case BR: case CODE: case EM: case I: case IMG:
case LABEL: case SMALL: case SPAN: case STRONG: case SUB:
case LABEL: case SMALL: case SPAN: case STRONG: case SUB: case SUP:
return true;
default:
return false;

3
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/TagName.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2010, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2010, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -83,6 +83,7 @@ public enum TagName {
SPAN,
STRONG,
SUB,
SUP,
TABLE,
TBODY,
THEAD,

22
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
View File

@ -1,5 +1,5 @@
#
# Copyright (c) 2010, 2020, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2010, 2021, Oracle and/or its affiliates. All rights reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -75,6 +75,7 @@ doclet.Navigation=Navigation
doclet.New_Page=NewPage
doclet.navDeprecated=Deprecated
doclet.Window_Deprecated_List=Deprecated List
doclet.Window_Preview_List=Preview List
doclet.Overrides=Overrides:
doclet.in_class=in class
doclet.Element_in=Element in {0}
@ -96,17 +97,18 @@ doclet.see.class_or_package_not_found=Tag {0}: reference not found: {1}
doclet.see.class_or_package_not_accessible=Tag {0}: reference not accessible: {1}
doclet.tag.invalid_usage=invalid usage of tag {0}
doclet.Deprecated_API=Deprecated API
doclet.Preview_API=Preview API
doclet.Preview_Label=Preview
doclet.Preview_Mark=PREVIEW
doclet.For_Removal=For Removal
doclet.Annotation_Types=Annotation Types
doclet.Annotation_Interfaces=Annotation Interfaces
doclet.Annotation_Type_Members=Annotation Type Elements
doclet.Annotation_Interface_Members=Annotation Interface Elements
doclet.for_removal=for removal
doclet.annotation_types=annotation types
doclet.annotation_interfaces=annotation interfaces
doclet.annotation_type_members=annotation type elements
doclet.annotation_interface_members=annotation interface elements
doclet.record_classes=record classes
doclet.Generated_Docs_Untitled=Generated Documentation (Untitled)
doclet.Other_Packages=Other Packages
doclet.Description=Description
@ -200,6 +202,9 @@ doclet.help.deprecated.body=\
The {0} page lists all of the API that have been deprecated. A deprecated API is not \
recommended for use, generally due to shortcomings, and a replacement API is usually given. \
Deprecated APIs may be removed in future implementations.
doclet.help.preview.body=\
The {0} page lists all of the Preview APIs. \
Preview APIs may be removed in future implementations.
doclet.help.index.head=\
Index
doclet.help.index.body=\
@ -286,6 +291,17 @@ doclet.navClassUse=Use
doclet.Error_in_grouplist=Bad -group option: {0} {1}
doclet.Groupname_already_used=In -group option, group name already used: {0}
doclet.Same_element_name_used=Element name or pattern used twice: {0}
doclet.PreviewLeadingNote={0} relies on preview features of the Java platform:
doclet.Declared_Using_Preview={0} is declared using {1}, a preview feature of the Java language ({2}).
doclet.PreviewAPI={0} refers to one or more preview APIs: {1}.
doclet.ReflectivePreviewAPI={0} refers to one or more reflective preview APIs: {1}.
doclet.UsesDeclaredUsingPreview={0} refers to one or more types which are declared using a preview feature of the Java language: {1}.
doclet.PreviewTrailingNote1=Programs can only use {0} when preview features are enabled.
doclet.PreviewTrailingNote2=Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
doclet.Declared_Using_Preview.SEALED=Sealed Classes
doclet.Declared_Using_Preview.SEALED_PERMITS=Sealed Classes
doclet.PreviewPlatformLeadingNote={0} is a preview API of the Java platform.
doclet.ReflectivePreviewPlatformLeadingNote={0} is a reflective preview API of the Java platform.
# option specifiers
doclet.usage.add-stylesheet.parameters=\

10
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AnnotationTypeRequiredMemberWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -92,6 +92,14 @@ public interface AnnotationTypeRequiredMemberWriter extends MemberWriter {
*/
void addDeprecated(Element member, Content annotationDocTree);
/**
* Add the preview output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the preview information will be added
*/
void addPreview(Element member, Content contentTree);
/**
* Add the comments for the given member.
*

10
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ConstructorWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -70,6 +70,14 @@ public interface ConstructorWriter extends MemberWriter {
*/
void addDeprecated(ExecutableElement constructor, Content constructorDocTree);
/**
* Add the preview output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the preview information will be added
*/
void addPreview(ExecutableElement member, Content contentTree);
/**
* Add the comments for the given constructor.
*

8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/EnumConstantWriter.java
View File

@ -75,6 +75,14 @@ public interface EnumConstantWriter extends MemberWriter {
*/
void addDeprecated(VariableElement enumConstant, Content enumConstantsTree);
/**
* Add the preview output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the preview information will be added
*/
void addPreview(VariableElement member, Content contentTree);
/**
* Add the comments for the given enum constant.
*

10
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/FieldWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -71,6 +71,14 @@ public interface FieldWriter extends MemberWriter {
*/
void addDeprecated(VariableElement field, Content fieldDocTree);
/**
* Adds the preview output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the preview information will be added
*/
void addPreview(VariableElement member, Content contentTree);
/**
* Add the comments for the given field.
*

8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/MethodWriter.java
View File

@ -71,6 +71,14 @@ public interface MethodWriter extends MemberWriter {
*/
void addDeprecated(ExecutableElement method, Content methodDocTree);
/**
* Adds the preview output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the preview information will be added
*/
void addPreview(ExecutableElement member, Content contentTree);
/**
* Add the comments for the given method.
*

10
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/PropertyWriter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -70,6 +70,14 @@ public interface PropertyWriter extends MemberWriter {
*/
void addDeprecated(ExecutableElement property, Content propertyDocTree);
/**
* Add the preview output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the preview information will be added
*/
void addPreview(ExecutableElement member, Content contentTree);
/**
* Add the comments for the given property.
*

13
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -513,4 +513,15 @@ public class WorkArounds {
? utils.elementUtils.getPackageElement(parsedPackageName)
: ((JavacElements) utils.elementUtils).getPackageElement(encl, parsedPackageName);
}
public boolean isPreviewAPI(Element el) {
Symbol sym = (Symbol) el;
return (sym.flags() & Flags.PREVIEW_API) != 0;
}
public boolean isReflectivePreviewAPI(Element el) {
Symbol sym = (Symbol) el;
return (sym.flags() & Flags.PREVIEW_REFLECTIVE) != 0;
}
}

13
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeRequiredMemberBuilder.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -29,6 +29,7 @@ import java.util.*;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import jdk.javadoc.internal.doclets.formats.html.AbstractMemberWriter;
import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeRequiredMemberWriter;
import jdk.javadoc.internal.doclets.toolkit.BaseOptions;
@ -152,6 +153,7 @@ public class AnnotationTypeRequiredMemberBuilder extends AbstractMemberBuilder {
protected void buildAnnotationTypeMemberChildren(Content annotationDocTree) {
buildSignature(annotationDocTree);
buildDeprecationInfo(annotationDocTree);
buildPreviewInfo(annotationDocTree);
buildMemberComments(annotationDocTree);
buildTagInfo(annotationDocTree);
}
@ -174,6 +176,15 @@ public class AnnotationTypeRequiredMemberBuilder extends AbstractMemberBuilder {
writer.addDeprecated(currentMember, annotationDocTree);
}
/**
* Build the preview information.
*
* @param annotationDocTree the content tree to which the documentation will be added
*/
protected void buildPreviewInfo(Content annotationDocTree) {
writer.addPreview(currentMember, annotationDocTree);
}
/**
* Build the comments for the member. Do nothing if
* {@link BaseOptions#noComment()} is set to true.

12
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstructorBuilder.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -132,6 +132,7 @@ public class ConstructorBuilder extends AbstractMemberBuilder {
buildSignature(constructorDocTree);
buildDeprecationInfo(constructorDocTree);
buildPreviewInfo(constructorDocTree);
buildConstructorComments(constructorDocTree);
buildTagInfo(constructorDocTree);
@ -160,6 +161,15 @@ public class ConstructorBuilder extends AbstractMemberBuilder {
writer.addDeprecated(currentConstructor, constructorDocTree);
}
/**
* Build the preview information.
*
* @param constructorDocTree the content tree to which the documentation will be added
*/
protected void buildPreviewInfo(Content constructorDocTree) {
writer.addPreview(currentConstructor, constructorDocTree);
}
/**
* Build the comments for the constructor. Do nothing if
* {@link BaseOptions#noComment()} is set to true.

12
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/EnumConstantBuilder.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -125,6 +125,7 @@ public class EnumConstantBuilder extends AbstractMemberBuilder {
buildSignature(enumConstantsTree);
buildDeprecationInfo(enumConstantsTree);
buildPreviewInfo(enumConstantsTree);
buildEnumConstantComments(enumConstantsTree);
buildTagInfo(enumConstantsTree);
@ -154,6 +155,15 @@ public class EnumConstantBuilder extends AbstractMemberBuilder {
writer.addDeprecated(currentElement, enumConstantsTree);
}
/**
* Build the preview information.
*
* @param enumConstantsTree the content tree to which the documentation will be added
*/
protected void buildPreviewInfo(Content enumConstantsTree) {
writer.addPreview(currentElement, enumConstantsTree);
}
/**
* Build the comments for the enum constant. Do nothing if
* {@link BaseOptions#noComment()} is set to true.

12
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/FieldBuilder.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -125,6 +125,7 @@ public class FieldBuilder extends AbstractMemberBuilder {
buildSignature(fieldDocTree);
buildDeprecationInfo(fieldDocTree);
buildPreviewInfo(fieldDocTree);
buildFieldComments(fieldDocTree);
buildTagInfo(fieldDocTree);
@ -153,6 +154,15 @@ public class FieldBuilder extends AbstractMemberBuilder {
writer.addDeprecated(currentElement, fieldDocTree);
}
/**
* Build the preview information.
*
* @param fieldDocTree the content tree to which the documentation will be added
*/
protected void buildPreviewInfo(Content fieldDocTree) {
writer.addPreview(currentElement, fieldDocTree);
}
/**
* Build the comments for the field. Do nothing if
* {@link BaseOptions#noComment()} is set to true.

12
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MethodBuilder.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -123,6 +123,7 @@ public class MethodBuilder extends AbstractMemberBuilder {
buildSignature(methodDocTree);
buildDeprecationInfo(methodDocTree);
buildPreviewInfo(methodDocTree);
buildMethodComments(methodDocTree);
buildTagInfo(methodDocTree);
@ -151,6 +152,15 @@ public class MethodBuilder extends AbstractMemberBuilder {
writer.addDeprecated(currentMethod, methodDocTree);
}
/**
* Build the preview information.
*
* @param methodDocTree the content tree to which the documentation will be added
*/
protected void buildPreviewInfo(Content methodDocTree) {
writer.addPreview(currentMethod, methodDocTree);
}
/**
* Build the comments for the method. Do nothing if
* {@link BaseOptions#noComment()} is set to true.

11
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PropertyBuilder.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -152,6 +152,15 @@ public class PropertyBuilder extends AbstractMemberBuilder {
writer.addDeprecated(currentProperty, propertyDocTree);
}
/**
* Build the preview information.
*
* @param propertyDocTree the content tree to which the documentation will be added
*/
protected void buildPreviewInfo(Content propertyDocTree) {
writer.addPreview(currentProperty, propertyDocTree);
}
/**
* Build the comments for the property. Do nothing if
* {@link BaseOptions#noComment()} is set to true.

13
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties
View File

@ -1,5 +1,5 @@
#
# Copyright (c) 2010, 2020, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2010, 2021, Oracle and/or its affiliates. All rights reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -151,8 +151,6 @@ doclet.AnnotationInterfaces=Annotation Interfaces
doclet.Exceptions=Exceptions
doclet.Errors=Errors
doclet.Classes=Classes
doclet.packages=packages
doclet.modules=modules
doclet.All_Classes=All Classes
doclet.All_Superinterfaces=All Superinterfaces:
doclet.All_Implemented_Interfaces=All Implemented Interfaces:
@ -171,17 +169,13 @@ doclet.enumclass=enum class
doclet.enums=enums
doclet.enumclasses=enum classes
doclet.interface=interface
doclet.interfaces=interfaces
doclet.class=class
doclet.classes=classes
doclet.RecordClass=Record Class
doclet.recordclass=record class
doclet.Error=Error
doclet.error=error
doclet.errors=errors
doclet.Exception=Exception
doclet.exception=exception
doclet.exceptions=exceptions
doclet.ExportedTo=Exported To Modules
doclet.OpenedTo=Opened To Modules
doclet.Package_private=(package private)
@ -216,12 +210,10 @@ doclet.value_tag_invalid_constant=@value tag (which references {0}) can only be
doclet.value_tag_invalid_use=@value tag cannot be used here.
doclet.dest_dir_create=Creating destination directory: "{0}"
doclet.in={0} in {1}
doclet.fields=fields
doclet.Fields=Fields
doclet.Preview=Preview.
doclet.Properties=Properties
doclet.constructors=constructors
doclet.Constructors=Constructors
doclet.methods=methods
doclet.Methods=Methods
doclet.All_Methods=All Methods
doclet.Static_Methods=Static Methods
@ -232,7 +224,6 @@ doclet.Default_Methods=Default Methods
doclet.Deprecated_Methods=Deprecated Methods
doclet.Annotation_Type_Optional_Members=Optional Elements
doclet.Annotation_Type_Required_Members=Required Elements
doclet.enum_constants=enum constants
doclet.Enum_Constants=Enum Constants
doclet.Nested_Classes=Nested Classes
doclet.Modifier=Modifier

21
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
View File

@ -431,7 +431,7 @@ div.table-tabs > button.table-tab {
text-align:left;
padding: 8px 3px 3px 7px;
}
.col-first, .col-second, .col-last, .col-constructor-name, .col-deprecated-item-name {
.col-first, .col-second, .col-last, .col-constructor-name, .col-summary-item-name {
vertical-align:top;
padding-right:0;
padding-top:8px;
@ -444,7 +444,7 @@ div.table-tabs > button.table-tab {
.col-first, .col-first {
font-size:13px;
}
.col-second, .col-second, .col-last, .col-constructor-name, .col-deprecated-item-name, .col-last {
.col-second, .col-second, .col-last, .col-constructor-name, .col-summary-item-name, .col-last {
font-size:13px;
}
.col-first, .col-second, .col-constructor-name {
@ -459,7 +459,7 @@ div.table-tabs > button.table-tab {
.col-first a:link, .col-first a:visited,
.col-second a:link, .col-second a:visited,
.col-constructor-name a:link, .col-constructor-name a:visited,
.col-deprecated-item-name a:link, .col-deprecated-item-name a:visited,
.col-summary-item-name a:link, .col-summary-item-name a:visited,
.constant-values-container a:link, .constant-values-container a:visited,
.all-classes-container a:link, .all-classes-container a:visited,
.all-packages-container a:link, .all-packages-container a:visited {
@ -534,10 +534,10 @@ h1.hidden {
}
.deprecated-label, .descfrm-type-label, .implementation-label, .member-name-label, .member-name-link,
.module-label-in-package, .module-label-in-type, .override-specify-label, .package-label-in-type,
.package-hierarchy-label, .type-name-label, .type-name-link, .search-tag-link {
.package-hierarchy-label, .type-name-label, .type-name-link, .search-tag-link, .preview-label {
font-weight:bold;
}
.deprecation-comment, .help-footnote, .interface-name {
.deprecation-comment, .help-footnote, .interface-name, .preview-comment {
font-style:italic;
}
.deprecation-block {
@ -551,6 +551,17 @@ h1.hidden {
margin-right:10px;
display:inline-block;
}
.preview-block {
font-size:14px;
font-family:'DejaVu Serif', Georgia, "Times New Roman", Times, serif;
border-style:solid;
border-width:thin;
border-radius:10px;
padding:10px;
margin-bottom:10px;
margin-right:10px;
display:inline-block;
}
div.block div.deprecation-comment, div.block div.block span.emphasized-phrase,
div.block div.block span.interface-name {
font-style:normal;

15
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Comparators.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -124,17 +124,18 @@ public class Comparators {
return packageComparator;
}
private Comparator<Element> deprecatedComparator = null;
private Comparator<Element> summaryComparator = null;
/**
* Returns a Comparator for deprecated items listed on deprecated list page, by comparing the
* Returns a Comparator for items listed on summary list pages
* (like deprecated or preview summary pages), by comparing the
* fully qualified names, and if those are equal the names of the enclosing modules.
*
* @return a Comparator
*/
public Comparator<Element> makeDeprecatedComparator() {
if (deprecatedComparator == null) {
deprecatedComparator = new ElementComparator() {
public Comparator<Element> makeSummaryComparator() {
if (summaryComparator == null) {
summaryComparator = new ElementComparator() {
@Override
public int compare(Element e1, Element e2) {
int result = compareFullyQualifiedNames(e1, e2);
@ -150,7 +151,7 @@ public class Comparators {
}
};
}
return deprecatedComparator;
return summaryComparator;
}
private Comparator<SerialFieldTree> serialFieldTreeComparator = null;

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -28,9 +28,6 @@ package jdk.javadoc.internal.doclets.toolkit.util;
import java.util.*;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
@ -42,31 +39,8 @@ import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
* This code and its internal interfaces are subject to change or
* deletion without notice.</b>
*/
public class DeprecatedAPIListBuilder {
/**
* List of deprecated type Lists.
*/
private final Map<DeprElementKind, SortedSet<Element>> deprecatedMap;
private final BaseConfiguration configuration;
private final Utils utils;
public enum DeprElementKind {
REMOVAL,
MODULE,
PACKAGE,
INTERFACE,
CLASS,
ENUM,
EXCEPTION, // no ElementKind mapping
ERROR, // no ElementKind mapping
RECORD_CLASS,
ANNOTATION_TYPE,
FIELD,
METHOD,
CONSTRUCTOR,
ENUM_CONSTANT,
ANNOTATION_TYPE_MEMBER // no ElementKind mapping
};
public class DeprecatedAPIListBuilder extends SummaryAPIListBuilder {
private SortedSet<Element> forRemoval;
/**
* Constructor.
@ -74,135 +48,21 @@ public class DeprecatedAPIListBuilder {
* @param configuration the current configuration of the doclet
*/
public DeprecatedAPIListBuilder(BaseConfiguration configuration) {
this.configuration = configuration;
this.utils = configuration.utils;
deprecatedMap = new EnumMap<>(DeprElementKind.class);
for (DeprElementKind kind : DeprElementKind.values()) {
deprecatedMap.put(kind,
new TreeSet<>(utils.comparators.makeDeprecatedComparator()));
}
buildDeprecatedAPIInfo();
super(configuration, configuration.utils::isDeprecated);
}
public boolean isEmpty() {
return deprecatedMap.values().stream().allMatch(Set::isEmpty);
public SortedSet<Element> getForRemoval() {
if (forRemoval == null) {
forRemoval = createSummarySet();
}
return forRemoval;
}
/**
* Build the sorted list of all the deprecated APIs in this run.
* Build separate lists for deprecated modules, packages, classes, constructors,
* methods and fields.
*/
private void buildDeprecatedAPIInfo() {
SortedSet<Element> rset = deprecatedMap.get(DeprElementKind.REMOVAL);
SortedSet<ModuleElement> modules = configuration.modules;
SortedSet<Element> mset = deprecatedMap.get(DeprElementKind.MODULE);
for (Element me : modules) {
if (utils.isDeprecatedForRemoval(me)) {
rset.add(me);
}
if (utils.isDeprecated(me)) {
mset.add(me);
}
}
SortedSet<PackageElement> packages = configuration.packages;
SortedSet<Element> pset = deprecatedMap.get(DeprElementKind.PACKAGE);
for (Element pe : packages) {
if (utils.isDeprecatedForRemoval(pe)) {
rset.add(pe);
}
if (utils.isDeprecated(pe)) {
pset.add(pe);
}
}
for (Element e : configuration.getIncludedTypeElements()) {
TypeElement te = (TypeElement)e;
SortedSet<Element> eset;
if (utils.isDeprecatedForRemoval(e)) {
rset.add(e);
}
if (utils.isDeprecated(e)) {
switch (e.getKind()) {
case ANNOTATION_TYPE:
eset = deprecatedMap.get(DeprElementKind.ANNOTATION_TYPE);
eset.add(e);
break;
case CLASS:
if (utils.isError(te)) {
eset = deprecatedMap.get(DeprElementKind.ERROR);
} else if (utils.isException(te)) {
eset = deprecatedMap.get(DeprElementKind.EXCEPTION);
} else {
eset = deprecatedMap.get(DeprElementKind.CLASS);
}
eset.add(e);
break;
case INTERFACE:
eset = deprecatedMap.get(DeprElementKind.INTERFACE);
eset.add(e);
break;
case ENUM:
eset = deprecatedMap.get(DeprElementKind.ENUM);
eset.add(e);
break;
case RECORD:
eset = deprecatedMap.get(DeprElementKind.RECORD_CLASS);
eset.add(e);
break;
}
}
composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.FIELD),
utils.getFields(te));
composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.METHOD),
utils.getMethods(te));
composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.CONSTRUCTOR),
utils.getConstructors(te));
if (utils.isEnum(e)) {
composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.ENUM_CONSTANT),
utils.getEnumConstants(te));
}
if (utils.isAnnotationType(e)) {
composeDeprecatedList(rset, deprecatedMap.get(DeprElementKind.ANNOTATION_TYPE_MEMBER),
utils.getAnnotationMembers(te));
}
@Override
protected void handleElement(Element e) {
if (utils.isDeprecatedForRemoval(e)) {
getForRemoval().add(e);
}
}
/**
* Add the members into a single list of deprecated members.
*
* @param rset set of elements deprecated for removal.
* @param sset set of deprecated elements.
* @param members members to be added in the list.
*/
private void composeDeprecatedList(SortedSet<Element> rset, SortedSet<Element> sset, List<? extends Element> members) {
for (Element member : members) {
if (utils.isDeprecatedForRemoval(member)) {
rset.add(member);
}
if (utils.isDeprecated(member)) {
sset.add(member);
}
}
}
/**
* Return the list of deprecated elements of a given type.
*
* @param kind the DeprElementKind
* @return
*/
public SortedSet<Element> getSet(DeprElementKind kind) {
return deprecatedMap.get(kind);
}
/**
* Return true if the list of a given type has size greater than 0.
*
* @param kind the type of list being checked.
*/
public boolean hasDocumentation(DeprElementKind kind) {
return !deprecatedMap.get(kind).isEmpty();
}
}

6
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocLink.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -102,6 +102,10 @@ public class DocLink {
return new DocLink(newPath, fragment);
}
public DocLink withFragment(String fragment) {
return new DocLink(path, fragment);
}
// return true if the path begins <letters>://
private boolean isAbsoluteURL(DocPath path) {
String s = path.getPath();

5
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocPaths.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -139,6 +139,9 @@ public class DocPaths {
/** The name of the file for the package usage info. */
public static final DocPath PACKAGE_USE = DocPath.create("package-use.html");
/** The name of the fie for preview elements. */
public static final DocPath PREVIEW_LIST = DocPath.create("preview-list.html");
/** The name of the file for all system properties. */
public static final DocPath SYSTEM_PROPERTIES = DocPath.create("system-properties.html");

48
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PreviewAPIListBuilder.java Normal file
View File

@ -0,0 +1,48 @@
/*
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.javadoc.internal.doclets.toolkit.util;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
/**
* Build list of all the preview packages, classes, constructors, fields and methods.
*
* <p><b>This is NOT part of any supported API.
* If you write code that depends on this, you do so at your own risk.
* This code and its internal interfaces are subject to change or
* deletion without notice.</b>
*/
public class PreviewAPIListBuilder extends SummaryAPIListBuilder {
/**
* Constructor.
*
* @param configuration the current configuration of the doclet
*/
public PreviewAPIListBuilder(BaseConfiguration configuration) {
super(configuration, e -> configuration.utils.isPreviewAPI(e));
}
}

225
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/SummaryAPIListBuilder.java Normal file
View File

@ -0,0 +1,225 @@
/*
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.javadoc.internal.doclets.toolkit.util;
import java.util.*;
import java.util.function.Predicate;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.RecordComponentElement;
import javax.lang.model.element.TypeElement;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
/**
* Build list of all the summary packages, classes, constructors, fields and methods.
*
* <p><b>This is NOT part of any supported API.
* If you write code that depends on this, you do so at your own risk.
* This code and its internal interfaces are subject to change or
* deletion without notice.</b>
*/
public class SummaryAPIListBuilder {
/**
* List of summary type Lists.
*/
private final Map<SummaryElementKind, SortedSet<Element>> summaryMap;
private final BaseConfiguration configuration;
protected final Utils utils;
private final Predicate<Element> belongsToSummary;
public enum SummaryElementKind {
MODULE,
PACKAGE,
INTERFACE,
CLASS,
ENUM,
EXCEPTION, // no ElementKind mapping
ERROR, // no ElementKind mapping
RECORD_CLASS,
ANNOTATION_TYPE,
FIELD,
METHOD,
CONSTRUCTOR,
ENUM_CONSTANT,
ANNOTATION_TYPE_MEMBER // no ElementKind mapping
};
/**
* Constructor.
*
* @param configuration the current configuration of the doclet
*/
public SummaryAPIListBuilder(BaseConfiguration configuration,
Predicate<Element> belongsToSummary) {
this.configuration = configuration;
this.utils = configuration.utils;
this.belongsToSummary = belongsToSummary;
summaryMap = new EnumMap<>(SummaryElementKind.class);
for (SummaryElementKind kind : SummaryElementKind.values()) {
summaryMap.put(kind, createSummarySet());
}
buildSummaryAPIInfo();
}
public boolean isEmpty() {
return summaryMap.values().stream().allMatch(Set::isEmpty);
}
/**
* Build the sorted list of all the summary APIs in this run.
* Build separate lists for summary modules, packages, classes, constructors,
* methods and fields.
*/
private void buildSummaryAPIInfo() {
SortedSet<ModuleElement> modules = configuration.modules;
SortedSet<Element> mset = summaryMap.get(SummaryElementKind.MODULE);
for (Element me : modules) {
if (belongsToSummary.test(me)) {
mset.add(me);
}
handleElement(me);
}
SortedSet<PackageElement> packages = configuration.packages;
SortedSet<Element> pset = summaryMap.get(SummaryElementKind.PACKAGE);
for (Element pe : packages) {
if (belongsToSummary.test(pe)) {
pset.add(pe);
}
handleElement(pe);
}
for (Element e : configuration.getIncludedTypeElements()) {
TypeElement te = (TypeElement)e;
SortedSet<Element> eset;
if (belongsToSummary.test(e)) {
switch (e.getKind()) {
case ANNOTATION_TYPE -> {
eset = summaryMap.get(SummaryElementKind.ANNOTATION_TYPE);
eset.add(e);
}
case CLASS -> {
if (utils.isError(te)) {
eset = summaryMap.get(SummaryElementKind.ERROR);
} else if (utils.isException(te)) {
eset = summaryMap.get(SummaryElementKind.EXCEPTION);
} else {
eset = summaryMap.get(SummaryElementKind.CLASS);
}
eset.add(e);
}
case INTERFACE -> {
eset = summaryMap.get(SummaryElementKind.INTERFACE);
eset.add(e);
}
case ENUM -> {
eset = summaryMap.get(SummaryElementKind.ENUM);
eset.add(e);
}
case RECORD -> {
eset = summaryMap.get(SummaryElementKind.RECORD_CLASS);
eset.add(e);
}
}
}
handleElement(te);
composeSummaryList(summaryMap.get(SummaryElementKind.FIELD),
utils.getFields(te));
composeSummaryList(summaryMap.get(SummaryElementKind.METHOD),
utils.getMethods(te));
composeSummaryList(summaryMap.get(SummaryElementKind.CONSTRUCTOR),
utils.getConstructors(te));
if (utils.isEnum(e)) {
composeSummaryList(summaryMap.get(SummaryElementKind.ENUM_CONSTANT),
utils.getEnumConstants(te));
}
if (utils.isRecord(te)) {
for (RecordComponentElement component : te.getRecordComponents()) {
if (belongsToSummary.test(component)) {
throw new AssertionError("record components not supported in summary builders: " +
"component: " + component.getSimpleName() +
" of record: " + te.getQualifiedName());
}
}
}
if (utils.isAnnotationType(e)) {
composeSummaryList(summaryMap.get(SummaryElementKind.ANNOTATION_TYPE_MEMBER),
utils.getAnnotationMembers(te));
}
}
}
/**
* Add the members into a single list of summary members.
*
* @param rset set of elements summary for removal.
* @param sset set of summary elements.
* @param members members to be added in the list.
*/
private void composeSummaryList(SortedSet<Element> sset, List<? extends Element> members) {
for (Element member : members) {
if (belongsToSummary.test(member)) {
sset.add(member);
}
handleElement(member);
}
}
/**
* Return the list of summary elements of a given type.
*
* @param kind the SummaryElementKind
* @return
*/
public SortedSet<Element> getSet(SummaryElementKind kind) {
return summaryMap.get(kind);
}
/**
* Return true if the list of a given type has size greater than 0.
*
* @param kind the type of list being checked.
*/
public boolean hasDocumentation(SummaryElementKind kind) {
return !summaryMap.get(kind).isEmpty();
}
/**
* Additional extra processing of an analyzed element.
*
* @param e element to process
*/
protected void handleElement(Element e) {}
/**
* Create a summary set of elements.
*
* @return a summary set
*/
protected final SortedSet<Element> createSummarySet() {
return new TreeSet<>(utils.comparators.makeSummaryComparator());
}
}

256
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -56,6 +56,7 @@ import java.util.TreeSet;
import java.util.function.Predicate;
import java.util.stream.Collectors;
import javax.lang.model.AnnotatedConstruct;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.element.AnnotationValue;
@ -82,6 +83,7 @@ import javax.lang.model.type.WildcardType;
import javax.lang.model.util.ElementFilter;
import javax.lang.model.util.ElementKindVisitor14;
import javax.lang.model.util.Elements;
import javax.lang.model.util.SimpleAnnotationValueVisitor14;
import javax.lang.model.util.SimpleElementVisitor14;
import javax.lang.model.util.SimpleTypeVisitor9;
import javax.lang.model.util.TypeKindVisitor9;
@ -2960,4 +2962,256 @@ public class Utils {
return first + ":" + second;
}
}
/**
* Return the set of preview language features used to declare the given element.
*
* @param e the Element to check.
* @return the set of preview language features used to declare the given element
*/
@SuppressWarnings("preview")
public Set<DeclarationPreviewLanguageFeatures> previewLanguageFeaturesUsed(Element e) {
Set<DeclarationPreviewLanguageFeatures> result = new HashSet<>();
if ((e.getKind().isClass() || e.getKind().isInterface()) &&
e.getModifiers().contains(Modifier.SEALED)) {
List<? extends TypeMirror> permits = ((TypeElement) e).getPermittedSubclasses();
boolean hasLinkablePermits = permits.stream()
.anyMatch(t -> isLinkable(asTypeElement(t)));
if (hasLinkablePermits) {
result.add(DeclarationPreviewLanguageFeatures.SEALED_PERMITS);
} else {
result.add(DeclarationPreviewLanguageFeatures.SEALED);
}
}
return result;
}
public enum DeclarationPreviewLanguageFeatures {
SEALED(List.of("sealed")),
SEALED_PERMITS(List.of("sealed", "permits"));
public final List<String> features;
private DeclarationPreviewLanguageFeatures(List<String> features) {
this.features = features;
}
}
@SuppressWarnings("preview")
public PreviewSummary declaredUsingPreviewAPIs(Element el) {
List<TypeElement> usedInDeclaration = new ArrayList<>();
usedInDeclaration.addAll(annotations2Classes(el));
switch (el.getKind()) {
case ANNOTATION_TYPE, CLASS, ENUM, INTERFACE, RECORD -> {
TypeElement te = (TypeElement) el;
for (TypeParameterElement tpe : te.getTypeParameters()) {
usedInDeclaration.addAll(types2Classes(tpe.getBounds()));
}
usedInDeclaration.addAll(types2Classes(List.of(te.getSuperclass())));
usedInDeclaration.addAll(types2Classes(te.getInterfaces()));
usedInDeclaration.addAll(types2Classes(te.getPermittedSubclasses()));
usedInDeclaration.addAll(types2Classes(te.getRecordComponents().stream().map(c -> c.asType()).collect(Collectors.toList()))); //TODO: annotations on record components???
}
case CONSTRUCTOR, METHOD -> {
ExecutableElement ee = (ExecutableElement) el;
for (TypeParameterElement tpe : ee.getTypeParameters()) {
usedInDeclaration.addAll(types2Classes(tpe.getBounds()));
}
usedInDeclaration.addAll(types2Classes(List.of(ee.getReturnType())));
usedInDeclaration.addAll(types2Classes(List.of(ee.getReceiverType())));
usedInDeclaration.addAll(types2Classes(ee.getThrownTypes()));
usedInDeclaration.addAll(types2Classes(ee.getParameters().stream().map(p -> p.asType()).collect(Collectors.toList())));
usedInDeclaration.addAll(annotationValue2Classes(ee.getDefaultValue()));
}
case FIELD, ENUM_CONSTANT, RECORD_COMPONENT -> {
VariableElement ve = (VariableElement) el;
usedInDeclaration.addAll(types2Classes(List.of(ve.asType())));
}
case MODULE, PACKAGE -> {
}
default -> throw new IllegalArgumentException("Unexpected: " + el.getKind());
}
Set<TypeElement> previewAPI = new HashSet<>();
Set<TypeElement> reflectivePreviewAPI = new HashSet<>();
Set<TypeElement> declaredUsingPreviewFeature = new HashSet<>();
for (TypeElement type : usedInDeclaration) {
if (!isIncluded(type) && !configuration.extern.isExternal(type)) {
continue;
}
if (isPreviewAPI(type)) {
if (isReflectivePreviewAPI(type)) {
reflectivePreviewAPI.add(type);
} else {
previewAPI.add(type);
}
}
if (!previewLanguageFeaturesUsed(type).isEmpty()) {
declaredUsingPreviewFeature.add(type);
}
}
return new PreviewSummary(previewAPI, reflectivePreviewAPI, declaredUsingPreviewFeature);
}
private Collection<TypeElement> types2Classes(List<? extends TypeMirror> types) {
List<TypeElement> result = new ArrayList<>();
List<TypeMirror> todo = new ArrayList<>(types);
while (!todo.isEmpty()) {
TypeMirror type = todo.remove(todo.size() - 1);
result.addAll(annotations2Classes(type));
if (type.getKind() == DECLARED) {
DeclaredType dt = (DeclaredType) type;
result.add((TypeElement) dt.asElement());
todo.addAll(dt.getTypeArguments());
}
}
return result;
}
private Collection<TypeElement> annotations2Classes(AnnotatedConstruct annotated) {
List<TypeElement> result = new ArrayList<>();
for (AnnotationMirror am : annotated.getAnnotationMirrors()) {
result.addAll(annotation2Classes(am));
}
return result;
}
private Collection<TypeElement> annotation2Classes(AnnotationMirror am) {
List<TypeElement> result = new ArrayList<>();
result.addAll(types2Classes(List.of(am.getAnnotationType())));
am.getElementValues()
.values()
.stream()
.flatMap(av -> annotationValue2Classes(av).stream())
.forEach(result::add);
return result;
}
private Collection<TypeElement> annotationValue2Classes(AnnotationValue value) {
if (value == null) {
return List.of();
}
List<TypeElement> result = new ArrayList<>();
value.accept(new SimpleAnnotationValueVisitor14<>() {
@Override
public Object visitArray(List<? extends AnnotationValue> vals, Object p) {
vals.stream()
.forEach(v -> v.accept(this, null));
return super.visitArray(vals, p);
}
@Override
public Object visitAnnotation(AnnotationMirror a, Object p) {
result.addAll(annotation2Classes(a));
return super.visitAnnotation(a, p);
}
@Override
public Object visitType(TypeMirror t, Object p) {
result.addAll(types2Classes(List.of(t)));
return super.visitType(t, p);
}
}, null);
return result;
}
public static final class PreviewSummary {
public final Set<TypeElement> previewAPI;
public final Set<TypeElement> reflectivePreviewAPI;
public final Set<TypeElement> declaredUsingPreviewFeature;
public PreviewSummary(Set<TypeElement> previewAPI, Set<TypeElement> reflectivePreviewAPI, Set<TypeElement> declaredUsingPreviewFeature) {
this.previewAPI = previewAPI;
this.reflectivePreviewAPI = reflectivePreviewAPI;
this.declaredUsingPreviewFeature = declaredUsingPreviewFeature;
}
@Override
public String toString() {
return "PreviewSummary{" + "previewAPI=" + previewAPI + ", reflectivePreviewAPI=" + reflectivePreviewAPI + ", declaredUsingPreviewFeature=" + declaredUsingPreviewFeature + '}';
}
}
/**
* Checks whether the given Element should be marked as a preview API.
*
* Note that if a type is marked as a preview, its members are not.
*
* @param el the element to check
* @return true if and only if the given element should be marked as a preview API
*/
public boolean isPreviewAPI(Element el) {
boolean parentPreviewAPI = false;
Element enclosing = el.getEnclosingElement();
if (enclosing != null && (enclosing.getKind().isClass() || enclosing.getKind().isInterface())) {
parentPreviewAPI = configuration.workArounds.isPreviewAPI(el.getEnclosingElement());
}
boolean previewAPI = configuration.workArounds.isPreviewAPI(el);
return !parentPreviewAPI && previewAPI;
}
/**
* Checks whether the given Element should be marked as a reflective preview API.
*
* Note that if a type is marked as a preview, its members are not.
*
* @param el the element to check
* @return true if and only if the given element should be marked
* as a reflective preview API
*/
public boolean isReflectivePreviewAPI(Element el) {
return isPreviewAPI(el) && configuration.workArounds.isReflectivePreviewAPI(el);
}
/**
* Return all flags for the given Element.
*
* @param el the element to test
* @return the set of all the element's flags.
*/
public Set<ElementFlag> elementFlags(Element el) {
Set<ElementFlag> flags = EnumSet.noneOf(ElementFlag.class);
PreviewSummary previewAPIs = declaredUsingPreviewAPIs(el);
if (isDeprecated(el)) {
flags.add(ElementFlag.DEPRECATED);
}
if (!previewLanguageFeaturesUsed(el).isEmpty() ||
configuration.workArounds.isPreviewAPI(el) ||
!previewAPIs.previewAPI.isEmpty() ||
!previewAPIs.reflectivePreviewAPI.isEmpty() ||
!previewAPIs.declaredUsingPreviewFeature.isEmpty()) {
flags.add(ElementFlag.PREVIEW);
}
return flags;
}
/**
* An element can have flags that place it into some sub-categories, like
* being a preview or a deprecated element.
*/
public enum ElementFlag {
DEPRECATED,
PREVIEW;
}
}

5
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/links/LinkFactory.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -36,6 +36,7 @@ import javax.lang.model.type.TypeMirror;
import javax.lang.model.type.TypeVariable;
import javax.lang.model.type.WildcardType;
import javax.lang.model.util.SimpleTypeVisitor9;
import jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
@ -139,6 +140,7 @@ public abstract class LinkFactory {
Content label = newContent();
label.add(utils.getTypeName(type, false));
linkInfo.label = label;
linkInfo.skipPreview = true;
link.add(getClassLink(linkInfo));
} else {
// No need to link method type parameters.
@ -204,6 +206,7 @@ public abstract class LinkFactory {
linkInfo.typeElement = null;
linkInfo.label = null;
linkInfo.type = bound;
linkInfo.skipPreview = false;
}
/**

5
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/links/LinkInfo.java
View File

@ -110,6 +110,11 @@ public abstract class LinkInfo {
*/
public boolean linkToSelf = true;
/**
* True iff the preview flags should be skipped for this link.
*/
public boolean skipPreview;
/**
* Return an empty instance of a content object.
*

3
src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -1285,6 +1285,7 @@ public class ElementsTable {
case CONSTRUCTOR: case ENUM_CONSTANT: case EXCEPTION_PARAMETER:
case FIELD: case INSTANCE_INIT: case LOCAL_VARIABLE: case PARAMETER:
case RESOURCE_VARIABLE: case STATIC_INIT: case TYPE_PARAMETER:
case RECORD_COMPONENT:
return ElementKind.METHOD;
default:
throw new AssertionError("unsupported kind: " + kind);

8
src/jdk.jshell/share/classes/jdk/jshell/Snippet.java
View File

@ -236,20 +236,12 @@ public abstract class Snippet {
ENUM_SUBKIND(Kind.TYPE_DECL),
/**
* {@preview Associated with records, a preview feature of the Java language.
*
* This enum constant is associated with <i>records</i>, a preview
* feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent
* features of the Java language.}
*
* A record declaration.
* A {@code SubKind} of {@link Kind#TYPE_DECL}.
* @jls 8.10 Record Types
* @since 14
*
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.RECORDS)
RECORD_SUBKIND(Kind.TYPE_DECL),
/**

4
test/jdk/java/lang/invoke/defineHiddenClass/PreviewHiddenClass.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -56,7 +56,7 @@ public class PreviewHiddenClass {
// compile a class with --enable-preview
Path sourceFile = SRC_DIR.resolve("HiddenInterface.java");
String[] options = new String[] {
"--enable-preview", "-source", String.valueOf(Runtime.version().feature()) };
"--enable-preview", "-source", String.valueOf(Runtime.version().feature()), "-XDforcePreview" };
if (!CompilerUtils.compile(sourceFile, CLASSES_DIR, options)) {
throw new RuntimeException("Compilation of the test failed: " + sourceFile);
}

5
test/jdk/java/lang/ref/CleanerTest.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -55,8 +55,7 @@ import org.testng.annotations.Test;
* jdk.test.lib.JDKToolLauncher
* jdk.test.lib.Platform
* jdk.test.lib.process.*
* @modules java.base/jdk.internal
* java.base/jdk.internal.misc
* @modules java.base/jdk.internal.misc
* java.base/jdk.internal.ref
* java.management
* @run driver ClassFileInstaller sun.hotspot.WhiteBox

3
test/jdk/java/util/Arrays/TimSortStackSize2.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -27,7 +27,6 @@
* @summary Test TimSort stack size on big arrays
* @library /test/lib
* @modules java.management
* java.base/jdk.internal
* @requires (vm.debug == false)
* @build TimSortStackSize2
* @run driver ClassFileInstaller sun.hotspot.WhiteBox

2
test/jdk/jdk/modules/etc/JdkQualifiedExportTest.java
View File

@ -74,7 +74,7 @@ public class JdkQualifiedExportTest {
"jdk.internal.vm.ci/jdk.vm.ci.hotspot",
"jdk.internal.vm.ci/jdk.vm.ci.meta",
"jdk.internal.vm.ci/jdk.vm.ci.code",
"java.base/jdk.internal");
"java.base/jdk.internal.javac");
static void checkExports(ModuleDescriptor md) {
// build a map of upgradeable module to Exports that are qualified to it

36
test/langtools/jdk/javadoc/doclet/testDeprecatedDocs/TestDeprecatedDocs.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -291,7 +291,7 @@ public class TestDeprecatedDocs extends JavadocTester {
<div class="summary-table two-column-summary">
<div class="table-header col-first">Enum Class</div>
<div class="table-header col-last">Description</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/TestEnum.html" title="enum class in pkg">pkg.TestEnum</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/TestEnum.html" title="enum class in pkg">pkg.TestEnum</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">enum_test1 passes.</div>
</div>""",
@ -301,7 +301,7 @@ public class TestDeprecatedDocs extends JavadocTester {
<div class="summary-table two-column-summary">
<div class="table-header col-first">Exceptions</div>
<div class="table-header col-last">Description</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/TestException.html" title="class in pkg">pkg.TestException</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/TestException.html" title="class in pkg">pkg.TestException</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">exception_test1 passes.</div>
</div>""",
@ -311,25 +311,25 @@ public class TestDeprecatedDocs extends JavadocTester {
<div class="summary-table two-column-summary">
<div class="table-header col-first">Field</div>
<div class="table-header col-last">Description</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/DeprecatedClassByAnnotation.html#field">pkg.DeprecatedClassByAnnotation.field</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/DeprecatedClassByAnnotation.html#field">pkg.DeprecatedClassByAnnotation.field</a></div>
<div class="col-last even-row-color"></div>
<div class="col-deprecated-item-name odd-row-color"><a href="pkg/TestAnnotationType.html#field">pkg.TestAnnotationType.field</a></div>
<div class="col-summary-item-name odd-row-color"><a href="pkg/TestAnnotationType.html#field">pkg.TestAnnotationType.field</a></div>
<div class="col-last odd-row-color">
<div class="deprecation-comment">annotation_test4 passes.</div>
</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/TestClass.html#field">pkg.TestClass.field</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/TestClass.html#field">pkg.TestClass.field</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">class_test2 passes. This is the second sentence of deprecated description for a field.</div>
</div>
<div class="col-deprecated-item-name odd-row-color"><a href="pkg/TestError.html#field">pkg.TestError.field</a></div>
<div class="col-summary-item-name odd-row-color"><a href="pkg/TestError.html#field">pkg.TestError.field</a></div>
<div class="col-last odd-row-color">
<div class="deprecation-comment">error_test2 passes.</div>
</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/TestException.html#field">pkg.TestException.field</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/TestException.html#field">pkg.TestException.field</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">exception_test2 passes.</div>
</div>
<div class="col-deprecated-item-name odd-row-color"><a href="pkg/TestInterface.html#field">pkg.TestInterface.field</a></div>
<div class="col-summary-item-name odd-row-color"><a href="pkg/TestInterface.html#field">pkg.TestInterface.field</a></div>
<div class="col-last odd-row-color">
<div class="deprecation-comment">interface_test2 passes.</div>
</div>
@ -341,25 +341,25 @@ public class TestDeprecatedDocs extends JavadocTester {
<div class="summary-table two-column-summary">
<div class="table-header col-first">Method</div>
<div class="table-header col-last">Description</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/DeprecatedClassByAnnotation.html#method()">pkg.DeprecatedClassByAnnotation.method()</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/DeprecatedClassByAnnotation.html#method()">pkg.DeprecatedClassByAnnotation.method()</a></div>
<div class="col-last even-row-color"></div>
<div class="col-deprecated-item-name odd-row-color"><a href="pkg/TestAnnotationType.html#optional()">pkg.TestAnnotationType.optional()</a></div>
<div class="col-summary-item-name odd-row-color"><a href="pkg/TestAnnotationType.html#optional()">pkg.TestAnnotationType.optional()</a></div>
<div class="col-last odd-row-color">
<div class="deprecation-comment">annotation_test2 passes.</div>
</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/TestAnnotationType.html#required()">pkg.TestAnnotationType.required()</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/TestAnnotationType.html#required()">pkg.TestAnnotationType.required()</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">annotation_test3 passes.</div>
</div>
<div class="col-deprecated-item-name odd-row-color"><a href="pkg/TestClass.html#method()">pkg.TestClass.method()</a></div>
<div class="col-summary-item-name odd-row-color"><a href="pkg/TestClass.html#method()">pkg.TestClass.method()</a></div>
<div class="col-last odd-row-color">
<div class="deprecation-comment">class_test5 passes. This is the second sentence of deprecated description for a method.</div>
</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/TestClass.html#overloadedMethod(int)">pkg.TestClass.overloadedMethod&#8203;(int)</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/TestClass.html#overloadedMethod(int)">pkg.TestClass.overloadedMethod&#8203;(int)</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">class_test7 passes. Overloaded method 2.</div>
</div>
<div class="col-deprecated-item-name odd-row-color"><a href="pkg/TestClass.html#overloadedMethod(java.lang.String)">pkg.TestClass.overloadedMethod&#8203;(String)</a></div>
<div class="col-summary-item-name odd-row-color"><a href="pkg/TestClass.html#overloadedMethod(java.lang.String)">pkg.TestClass.overloadedMethod&#8203;(String)</a></div>
<div class="col-last odd-row-color">
<div class="deprecation-comment">class_test6 passes. Overloaded method 1.</div>
</div>""",
@ -369,13 +369,13 @@ public class TestDeprecatedDocs extends JavadocTester {
<div class="summary-table two-column-summary">
<div class="table-header col-first">Constructor</div>
<div class="table-header col-last">Description</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/DeprecatedClassByAnnotation.html#%3Cinit%3E()">pkg.DeprecatedClassByAnnotation()</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/DeprecatedClassByAnnotation.html#%3Cinit%3E()">pkg.DeprecatedClassByAnnotation()</a></div>
<div class="col-last even-row-color"></div>
<div class="col-deprecated-item-name odd-row-color"><a href="pkg/TestClass.html#%3Cinit%3E()">pkg.TestClass()</a></div>
<div class="col-summary-item-name odd-row-color"><a href="pkg/TestClass.html#%3Cinit%3E()">pkg.TestClass()</a></div>
<div class="col-last odd-row-color">
<div class="deprecation-comment">class_test3 passes. This is the second sentence of deprecated description for a constructor.</div>
</div>
<div class="col-deprecated-item-name even-row-color"><a href="pkg/TestClass.html#%3Cinit%3E(java.lang.String)">pkg.TestClass&#8203;(String)</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg/TestClass.html#%3Cinit%3E(java.lang.String)">pkg.TestClass&#8203;(String)</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">class_test4 passes. Overloaded constructor.</div>
</div>""");

10
test/langtools/jdk/javadoc/doclet/testHtmlTableTags/TestHtmlTableTags.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2009, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -672,12 +672,12 @@ public class TestHtmlTableTags extends JavadocTester {
// Deprecated
checkOutput("deprecated-list.html", true,
"""
<div class="col-deprecated-item-name even-row-color"><a href="pkg2/C2.html#dep_field">pkg2.C2.dep_field</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg2/C2.html#dep_field">pkg2.C2.dep_field</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">don't use this field anymore.</div>
</div>""",
"""
<div class="col-deprecated-item-name even-row-color"><a href="pkg1/C1.html#deprecatedMethod()">pkg1.C1.deprecatedMethod()</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg1/C1.html#deprecatedMethod()">pkg1.C1.deprecatedMethod()</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">don't use this anymore.</div>
</div>""");
@ -803,10 +803,10 @@ public class TestHtmlTableTags extends JavadocTester {
// Deprecated
checkOutput("deprecated-list.html", true,
"""
<div class="col-deprecated-item-name even-row-color"><a href="pkg2/C2.html#dep_field">pkg2.C2.dep_field</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg2/C2.html#dep_field">pkg2.C2.dep_field</a></div>
<div class="col-last even-row-color"></div>""",
"""
<div class="col-deprecated-item-name even-row-color"><a href="pkg1/C1.html#deprecatedMethod()">pkg1.C1.deprecatedMethod()</a></div>
<div class="col-summary-item-name even-row-color"><a href="pkg1/C1.html#deprecatedMethod()">pkg1.C1.deprecatedMethod()</a></div>
<div class="col-last even-row-color"></div>""");
// Constant values

5
test/langtools/jdk/javadoc/doclet/testModules/TestModules.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -289,6 +289,7 @@ public class TestModules extends JavadocTester {
"--show-module-contents=all",
"-Xdoclint:none",
"--module-source-path", testSrc,
"--add-modules", "moduleC",
"--module", "moduleB",
"testpkg2mdlB", "testpkgmdlB");
checkExit(Exit.OK);
@ -1091,7 +1092,7 @@ public class TestModules extends JavadocTester {
<li><a href="#module">Modules</a></li>
</ul>""",
"""
<div class="col-deprecated-item-name even-row-color"><a href="moduleA/module-summary.html">moduleA</a></div>
<div class="col-summary-item-name even-row-color"><a href="moduleA/module-summary.html">moduleA</a></div>
<div class="col-last even-row-color">
<div class="deprecation-comment">This module is deprecated.</div>""");
checkOutput("moduleB/module-summary.html", !found,

123
test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java Normal file
View File

@ -0,0 +1,123 @@
/*
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
* @test
* @bug 8250768
* @summary test generated docs for items declared using preview
* @library ../../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.resources:+open
* @build javadoc.tester.*
* @run main TestPreview
*/
import java.nio.file.Paths;
import java.text.MessageFormat;
import java.util.ResourceBundle;
import javadoc.tester.JavadocTester;
public class TestPreview extends JavadocTester {
public static void main(String... args) throws Exception {
TestPreview tester = new TestPreview();
tester.runTests();
}
@Test
public void testUserJavadoc() {
String doc = Paths.get(testSrc, "doc").toUri().toString();
javadoc("-d", "out-user-javadoc",
"-XDforcePreview", "--enable-preview", "-source", System.getProperty("java.specification.version"),
"--patch-module", "java.base=" + Paths.get(testSrc, "api").toAbsolutePath().toString(),
"--add-exports", "java.base/preview=m",
"--module-source-path", testSrc,
"-linkoffline", doc, doc,
"m/pkg");
checkExit(Exit.OK);
ResourceBundle bundle = ResourceBundle.getBundle("jdk.javadoc.internal.doclets.formats.html.resources.standard", ModuleLayer.boot().findModule("jdk.javadoc").get());
{
String zero = MessageFormat.format(bundle.getString("doclet.PreviewLeadingNote"), "<code>TestPreviewDeclaration</code>");
String one = MessageFormat.format(bundle.getString("doclet.Declared_Using_Preview"), "<code>TestPreviewDeclaration</code>", "<em>Sealed Classes</em>", "<code>sealed</code>");
String two = MessageFormat.format(bundle.getString("doclet.PreviewTrailingNote1"), "<code>TestPreviewDeclaration</code>");
String three = MessageFormat.format(bundle.getString("doclet.PreviewTrailingNote2"), new Object[0]);
String expectedTemplate = """
<div class="preview-block" id="preview-pkg.TestPreviewDeclaration"><span class="preview-label">{0}</span>
<ul class="preview-comment">
<li>{1}</li>
</ul>
<div class="preview-comment">{2}</div>
<div class="preview-comment">{3}</div>
</div>""";
String expected = MessageFormat.format(expectedTemplate, zero, one, two, three);
checkOutput("m/pkg/TestPreviewDeclaration.html", true, expected);
}
checkOutput("m/pkg/TestPreviewDeclarationUse.html", true,
"<code><a href=\"TestPreviewDeclaration.html\" title=\"interface in pkg\">TestPreviewDeclaration</a><sup><a href=\"TestPreviewDeclaration.html#preview-pkg.TestPreviewDeclaration\">PREVIEW</a></sup></code>");
checkOutput("m/pkg/TestPreviewAPIUse.html", true,
"<a href=\"" + doc + "java.base/preview/Core.html\" title=\"class or interface in preview\" class=\"external-link\">Core</a><sup><a href=\"" + doc + "java.base/preview/Core.html#preview-preview.Core\" title=\"class or interface in preview\" class=\"external-link\">PREVIEW</a>");
checkOutput("m/pkg/DocAnnotation.html", true,
"<div class=\"preview-block\" id=\"preview-pkg.DocAnnotation\"><span class=\"preview-label\">");
checkOutput("m/pkg/DocAnnotationUse1.html", true,
"<div class=\"preview-block\" id=\"preview-pkg.DocAnnotationUse1\"><span class=\"preview-label\">");
checkOutput("m/pkg/DocAnnotationUse2.html", true,
"<div class=\"preview-block\" id=\"preview-pkg.DocAnnotationUse2\"><span class=\"preview-label\">");
}
@Test
public void testPreviewAPIJavadoc() {
javadoc("-d", "out-preview-api",
"--patch-module", "java.base=" + Paths.get(testSrc, "api").toAbsolutePath().toString(),
"--add-exports", "java.base/preview=m",
"--source-path", Paths.get(testSrc, "api").toAbsolutePath().toString(),
"--show-packages=all",
"preview");
checkExit(Exit.OK);
checkOutput("preview-list.html", true,
"""
<div id="record.class">
<div class="caption"><span>Record Classes</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Record Class</div>
<div class="table-header col-last">Description</div>
<div class="col-summary-item-name even-row-color"><a href="java.base/preview/CoreRecord.html" title="class in preview">preview.CoreRecord</a><sup><a href="java.base/preview/CoreRecord.html#preview-preview.CoreRecord">PREVIEW</a></sup></div>
<div class="col-last even-row-color"></div>
</div>
""",
"""
<div id="method">
<div class="caption"><span>Methods</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Method</div>
<div class="table-header col-last">Description</div>
<div class="col-summary-item-name even-row-color"><a href="java.base/preview/CoreRecordComponent.html#i()">preview.CoreRecordComponent.i()</a><sup><a href="java.base/preview/CoreRecordComponent.html#preview-i()">PREVIEW</a></sup></div>
<div class="col-last even-row-color">
<div class="block">Returns the value of the <code>i</code> record component.</div>
</div>
""");
}
}

30
test/langtools/jdk/javadoc/doclet/testPreview/api/preview/Core.java Normal file
View File

@ -0,0 +1,30 @@
/*
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package preview;
import jdk.internal.javac.PreviewFeature;
import jdk.internal.javac.PreviewFeature.Feature;
@PreviewFeature(feature=Feature.TEST)
public class Core {
}

30
test/langtools/jdk/javadoc/doclet/testPreview/api/preview/CoreRecord.java Normal file
View File

@ -0,0 +1,30 @@
/*
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package preview;
import jdk.internal.javac.PreviewFeature;
import jdk.internal.javac.PreviewFeature.Feature;
@PreviewFeature(feature=Feature.TEST)
public record CoreRecord(int i) {
}

29
test/langtools/jdk/javadoc/doclet/testPreview/api/preview/CoreRecordComponent.java Normal file
View File

@ -0,0 +1,29 @@
/*
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package preview;
import jdk.internal.javac.PreviewFeature;
import jdk.internal.javac.PreviewFeature.Feature;
public record CoreRecordComponent(@PreviewFeature(feature=Feature.TEST) int i) {
}

30
test/langtools/jdk/javadoc/doclet/testPreview/api/preview/Reflective.java Normal file
View File

@ -0,0 +1,30 @@
/*
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package preview;
import jdk.internal.javac.PreviewFeature;
import jdk.internal.javac.PreviewFeature.Feature;
@PreviewFeature(feature=Feature.TEST, reflective=true)
public class Reflective {
}

2
test/langtools/jdk/javadoc/doclet/testPreview/doc/element-list Normal file
View File

@ -0,0 +1,2 @@
module:java.base
preview

Some files were not shown because too many files have changed in this diff Show More