archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 07:14:30 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8262807: Note assumptions of core reflection modeling and parameter handling

Browse source 
Reviewed-by: rriggs
This commit is contained in:
Joe Darcy 2021-03-17 21:58:48 +00:00
parent 26234b5333
commit 99b39aadbd
4 changed files with 93 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

3
src/java.base/share/classes/java/lang/Class.java
View file

@ -1266,6 +1266,9 @@ public final class Class<T> implements java.io.Serializable,
*
* @return the {@code int} representing the modifiers for this class
* @see java.lang.reflect.Modifier
* @see <a
* href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
* programming language and JVM modeling in core reflection</a>
* @since 1.1
* @jls 8.1.1 Class Modifiers
* @jls 9.1.1. Interface Modifiers

48
src/java.base/share/classes/java/lang/reflect/Executable.java
View file

@ -201,8 +201,8 @@ public abstract class Executable extends AccessibleObject
public abstract String getName();
/**
* Returns the Java language {@linkplain Modifier modifiers} for
* the executable represented by this object.
* {@return the Java language {@linkplain Modifier modifiers} for
* the executable represented by this object}
*/
public abstract int getModifiers();
@ -257,13 +257,20 @@ public abstract class Executable extends AccessibleObject
}
/**
* Returns an array of {@code Type} objects that represent the formal
* parameter types, in declaration order, of the executable represented by
* this object. Returns an array of length 0 if the
* underlying executable takes no parameters.
* Note that the constructors of some inner classes
* may have an implicitly declared parameter in addition to
* explicitly declared ones.
* Returns an array of {@code Type} objects that represent the
* formal parameter types, in declaration order, of the executable
* represented by this object. An array of length 0 is returned if the
* underlying executable takes no parameters. Note that the
* constructors of some inner classes may have an implicitly
* declared parameter in addition to explicitly declared ones.
* Also note that as a <a
* href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">modeling
* artifact</a>, the number of returned parameters can differ
* depending on whether or not generic information is present. If
* generic information is present, only parameters explicitly
* present in the source will be returned; if generic information
* is not present, implicit and synthetic parameters may be
* returned as well.
*
* <p>If a formal parameter type is a parameterized type,
* the {@code Type} object returned for it must accurately reflect
@ -340,19 +347,17 @@ public abstract class Executable extends AccessibleObject
}
/**
* Returns an array of {@code Parameter} objects that represent
* {@return an array of {@code Parameter} objects representing
* all the parameters to the underlying executable represented by
* this object. Returns an array of length 0 if the executable
* this object} An array of length 0 is returned if the executable
* has no parameters.
*
* <p>The parameters of the underlying executable do not necessarily
* have unique names, or names that are legal identifiers in the
* Java programming language (JLS 3.8).
* Java programming language (JLS {@jls 3.8}).
*
* @throws MalformedParametersException if the class file contains
* a MethodParameters attribute that is improperly formatted.
* @return an array of {@code Parameter} objects representing all
* the parameters to the executable this object represents.
*/
public Parameter[] getParameters() {
// TODO: This may eventually need to be guarded by security
@ -492,19 +497,14 @@ public abstract class Executable extends AccessibleObject
}
/**
* Returns a string describing this {@code Executable}, including
* any type parameters.
* @return a string describing this {@code Executable}, including
* any type parameters
* {@return a string describing this {@code Executable}, including
* any type parameters}
*/
public abstract String toGenericString();
/**
* Returns {@code true} if this executable was declared to take a
* variable number of arguments; returns {@code false} otherwise.
*
* @return {@code true} if an only if this executable was declared
* to take a variable number of arguments.
* {@return {@code true} if this executable was declared to take a
* variable number of arguments; returns {@code false} otherwise}
*/
public boolean isVarArgs() {
return (getModifiers() & Modifier.VARARGS) != 0;
@ -672,7 +672,7 @@ public abstract class Executable extends AccessibleObject
* by this {@code Executable} object.
*
* The receiver type of a method/constructor is available only if the
* method/constructor has a receiver parameter (JLS 8.4.1). If this {@code
* method/constructor has a receiver parameter (JLS {@jls 8.4.1}). If this {@code
* Executable} object <em>represents an instance method or represents a
* constructor of an inner member class</em>, and the
* method/constructor <em>either</em> has no receiver parameter or has a

15
src/java.base/share/classes/java/lang/reflect/Parameter.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2013, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2013, 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,19 +145,20 @@ public final class Parameter implements AnnotatedElement {
}
/**
* Return the {@code Executable} which declares this parameter.
*
* @return The {@code Executable} declaring this parameter.
* {@return the {@code Executable} declaring this parameter}
*/
public Executable getDeclaringExecutable() {
return executable;
}
/**
* Get the modifier flags for this the parameter represented by
* this {@code Parameter} object.
* {@return the Java language {@linkplain Modifier modifiers} for
* the parameter represented by this object}
*
* @return The modifier flags for this parameter.
* @jls 8.4.1 Formal Parameters
* @see <a
* href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
* programming language and JVM modeling in core reflection</a>
*/
public int getModifiers() {
return modifiers;

66
src/java.base/share/classes/java/lang/reflect/package-info.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2017, 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
@ -26,16 +26,10 @@
/**
* Provides classes and interfaces for obtaining reflective information about
* classes and objects. Reflection allows programmatic access to information
* about the fields, methods and constructors of loaded classes, and the use
* about the fields, methods, and constructors of loaded classes, and the use
* of reflected fields, methods, and constructors to operate on their underlying
* counterparts, within encapsulation and security restrictions.
*
* <p>{@code AccessibleObject} allows suppression of access checks if
* the necessary {@code ReflectPermission} is available.
*
* <p>{@code Array} provides static methods to dynamically create and
* access arrays.
*
* <p>Classes in this package, along with {@code java.lang.Class}
* accommodate applications such as debuggers, interpreters, object
* inspectors, class browsers, and services such as Object
@ -43,6 +37,62 @@
* members of a target object (based on its runtime class) or the
* members declared by a given class.
*
* <p>{@link AccessibleObject} allows suppression of access checks if
* the necessary {@link ReflectPermission} is available.
*
* <p>{@link Array} provides static methods to dynamically create and
* access arrays.
*
* <h2><a id="LanguageJvmModel">Java programming language and JVM modeling in core reflection</a></h2>
*
* The components of core reflection, which include types in this
* package as well as {@link java.lang.Class Class}, {@link
* java.lang.Package Package}, and {@link java.lang.Module Module},
* fundamentally present a JVM model of the entities in question
* rather than a Java programming language model. A Java compiler,
* such as {@code javac}, translates Java source code into executable
* output that can be run on a JVM, primarily {@code class}
* files. Compilers for source languages other than Java can and do
* target the JVM as well.
*
* <p>The translation process, including from Java language sources,
* to executable output for the JVM is not a one-to-one
* mapping. Structures present in the source language may have no
* representation in the output and structures <em>not</em> present in
* the source language may be present in the output. The latter are
* called <i>synthetic</i> structures. Synthetic structures can
* include {@linkplain Method#isSynthetic() methods}, {@linkplain
* Field#isSynthetic() fields}, {@linkplain Parameter#isSynthetic()
* parameters}, {@linkplain Class#isSynthetic() classes and
* interfaces}. One particular kind of synthetic method is a
* {@linkplain Method#isBridge() bridge method}. It is possible a
* synthetic structure may not be marked as such. In particular, not
* all {@code class} file versions support marking a parameter as
* synthetic. A source language compiler generally has multiple ways
* to translate a source program into a {@code class} file
* representation. The translation may also depend on the version of
* the {@code class} file format being targeted as different {@code
* class} file versions have different capabilities and features. In
* some cases the modifiers present in the {@code class} file
* representation may differ from the modifiers on the originating
* element in the source language, including {@link Modifier#FINAL
* final} on a {@linkplain Parameter#getModifiers() parameter} and
* {@code protected}, {@code private}, and {@code static} on
* {@linkplain java.lang.Class#getModifiers() classes and interfaces}.
*
* <p>Besides differences in structural representation between the
* source language and the JVM representation, core reflection also
* exposes runtime specific information. For example, the {@linkplain
* java.lang.Class#getClassLoader() class loaders} and {@linkplain
* java.lang.Class#getProtectionDomain() protection domains} of a
* {@code Class} are runtime concepts without a direct analogue in
* source code.
*
* @jls 13.1 The Form of a Binary
* @jvms 1.2 The Java Virtual Machine
* @jvms 4.7.8 The Synthetic Attribute
* @jvms 5.3.1 Loading Using the Bootstrap Class Loader
* @jvms 5.3.2 Loading Using a User-defined Class Loader
* @since 1.1
* @revised 9
*/