mirror of
https://github.com/openjdk/jdk.git
synced 2025-08-26 06:14:49 +02:00
8342468: Improve API documentation for java.lang.classfile.constantpool
Reviewed-by: asotona
This commit is contained in:
parent
40f0a398fa
commit
bcefab5e55
31 changed files with 1070 additions and 371 deletions
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,7 +25,9 @@
|
|||
|
||||
package java.lang.classfile;
|
||||
|
||||
import java.lang.classfile.attribute.BootstrapMethodsAttribute;
|
||||
import java.lang.classfile.constantpool.ConstantPool;
|
||||
import java.lang.classfile.constantpool.ConstantPoolBuilder;
|
||||
import java.lang.classfile.constantpool.LoadableConstantEntry;
|
||||
import java.lang.classfile.constantpool.MethodHandleEntry;
|
||||
import java.util.List;
|
||||
|
@ -34,10 +36,20 @@ import jdk.internal.classfile.impl.BootstrapMethodEntryImpl;
|
|||
|
||||
/**
|
||||
* Models an entry in the bootstrap method table. The bootstrap method table
|
||||
* is stored in the {@code BootstrapMethods} attribute, but is modeled by
|
||||
* the {@link ConstantPool}, since the bootstrap method table is logically
|
||||
* part of the constant pool.
|
||||
* is stored in the {@link BootstrapMethodsAttribute BootstrapMethods}
|
||||
* attribute, but is modeled by the {@link ConstantPool}, since the bootstrap
|
||||
* method table is logically part of the constant pool.
|
||||
* <p>
|
||||
* A bootstrap method entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="BootstrapMethodEntry" target="ConstantPoolBuilder#bsmEntry(MethodHandleEntry, List)" :
|
||||
* BootstrapMethodEntry(
|
||||
* MethodHandleEntry bootstrapMethod, // @link substring="bootstrapMethod" target="#bootstrapMethod"
|
||||
* List<LoadableConstantEntry> arguments // @link substring="arguments" target="#arguments()"
|
||||
* )
|
||||
* }
|
||||
*
|
||||
* @see ConstantPoolBuilder#bsmEntry ConstantPoolBuilder::bsmEntry
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface BootstrapMethodEntry
|
||||
|
@ -45,11 +57,19 @@ public sealed interface BootstrapMethodEntry
|
|||
|
||||
/**
|
||||
* {@return the constant pool associated with this entry}
|
||||
*
|
||||
* @apiNote
|
||||
* Given a {@link ConstantPoolBuilder} {@code builder} and a {@code
|
||||
* BootstrapMethodEntry} {@code entry}, use {@link
|
||||
* ConstantPoolBuilder#canWriteDirect
|
||||
* builder.canWriteDirect(entry.constantPool())} instead of object equality
|
||||
* of the constant pool to determine if an entry is compatible.
|
||||
*/
|
||||
ConstantPool constantPool();
|
||||
|
||||
/**
|
||||
* {@return the index into the bootstrap method table corresponding to this entry}
|
||||
* {@return the index into the bootstrap method table corresponding to this
|
||||
* entry}
|
||||
*/
|
||||
int bsmIndex();
|
||||
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -140,21 +140,56 @@ public sealed interface ClassFile
|
|||
|
||||
/**
|
||||
* Option describing whether to preserve the original constant pool when
|
||||
* transforming a classfile. Reusing the constant pool enables significant
|
||||
* optimizations in processing time and minimizes differences between the
|
||||
* original and transformed classfile, but may result in a bigger classfile
|
||||
* when a classfile is significantly transformed.
|
||||
* Default is {@code SHARED_POOL} to preserve the original constant
|
||||
* pool.
|
||||
* transforming a {@code class} file. Reusing the constant pool enables
|
||||
* significant optimizations in processing time and minimizes differences
|
||||
* between the original and transformed {@code class} files, but may result
|
||||
* in a bigger transformed {@code class} file when many elements of the
|
||||
* original {@code class} file are dropped and many original constant
|
||||
* pool entries become unused. Default is {@link #SHARED_POOL} to preserve
|
||||
* the original constant pool.
|
||||
*
|
||||
* @see ConstantPoolBuilder
|
||||
* @see #build(ClassEntry, ConstantPoolBuilder, Consumer)
|
||||
* @see #transformClass(ClassModel, ClassTransform)
|
||||
* @since 24
|
||||
*/
|
||||
enum ConstantPoolSharingOption implements Option {
|
||||
|
||||
/** Preserves the original constant pool when transforming classfile */
|
||||
/**
|
||||
* Preserves the original constant pool when transforming the {@code
|
||||
* class} file.
|
||||
* <p>
|
||||
* These two transformations below are equivalent:
|
||||
* {@snippet lang=java :
|
||||
* ClassModel originalClass = null; // @replace substring=null; replacement=...
|
||||
* ClassDesc resultClassName = null; // @replace substring=null; replacement=...
|
||||
* ClassTransform classTransform = null; // @replace substring=null; replacement=...
|
||||
* var resultOne = ClassFile.of(ConstantPoolSharingOption.SHARED_POOL)
|
||||
* .transformClass(originalClass, resultClassName, classTransform);
|
||||
* var resultTwo = ClassFile.of().build(resultClassName, ConstantPoolBuilder.of(originalClass),
|
||||
* clb -> clb.transform(originalClass, classTransform));
|
||||
* }
|
||||
*
|
||||
* @see ConstantPoolBuilder#of(ClassModel) ConstantPoolBuilder::of(ClassModel)
|
||||
*/
|
||||
SHARED_POOL,
|
||||
|
||||
/** Creates a new constant pool when transforming classfile */
|
||||
/**
|
||||
* Creates a new constant pool when transforming the {@code class} file.
|
||||
* <p>
|
||||
* These two transformations below are equivalent:
|
||||
* {@snippet lang=java :
|
||||
* ClassModel originalClass = null; // @replace substring=null; replacement=...
|
||||
* ClassDesc resultClassName = null; // @replace substring=null; replacement=...
|
||||
* ClassTransform classTransform = null; // @replace substring=null; replacement=...
|
||||
* var resultOne = ClassFile.of(ConstantPoolSharingOption.NEW_POOL)
|
||||
* .transformClass(originalClass, resultClassName, classTransform);
|
||||
* var resultTwo = ClassFile.of().build(resultClassName, ConstantPoolBuilder.of(),
|
||||
* clb -> clb.transform(originalClass, classTransform));
|
||||
* }
|
||||
*
|
||||
* @see ConstantPoolBuilder#of() ConstantPoolBuilder::of()
|
||||
*/
|
||||
NEW_POOL
|
||||
}
|
||||
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +28,9 @@ import java.lang.classfile.AnnotationValue;
|
|||
import java.lang.constant.ConstantDesc;
|
||||
|
||||
/**
|
||||
* A constant pool entry that may be used by annotation constant values,
|
||||
* which includes the four kinds of primitive constants and UTF8 constants.
|
||||
* These entries are also the only entries that do not refer to other
|
||||
* constant pool entries.
|
||||
* Marker interface for constant pool entries that can represent constant values
|
||||
* associated with elements of annotations. They are also the only entries that
|
||||
* do not refer to other constant pool entries.
|
||||
*
|
||||
* @apiNote
|
||||
* An annotation constant value entry alone is not sufficient to determine
|
||||
|
@ -40,6 +39,7 @@ import java.lang.constant.ConstantDesc;
|
|||
* in {@link AnnotationValue.OfInt}.
|
||||
*
|
||||
* @see AnnotationValue.OfConstant
|
||||
* @jvms 4.7.16.1 The {@code element_value} structure
|
||||
* @sealedGraph
|
||||
* @since 24
|
||||
*/
|
||||
|
@ -47,9 +47,9 @@ public sealed interface AnnotationConstantValueEntry extends PoolEntry
|
|||
permits DoubleEntry, FloatEntry, IntegerEntry, LongEntry, Utf8Entry {
|
||||
|
||||
/**
|
||||
* {@return the constant value} The constant value will be an {@link Integer},
|
||||
* {@link Long}, {@link Float}, {@link Double} for the primitive constants,
|
||||
* or {@link String} for UTF8 constants.
|
||||
* {@return the constant value} The constant value will be an {@link
|
||||
* Integer}, {@link Long}, {@link Float}, {@link Double} for the primitive
|
||||
* constants, or {@link String} for UTF8 constants.
|
||||
*/
|
||||
ConstantDesc constantValue();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -30,33 +30,82 @@ import java.lang.constant.ConstantDesc;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Class_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.1 The CONSTANT_Class_info Structure
|
||||
* Models a {@code CONSTANT_Class_info} structure, representing a reference
|
||||
* type, in the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code ClassEntry} is modeled by a {@link ClassDesc} that is not
|
||||
* primitive. Conversions are through {@link ConstantPoolBuilder#classEntry(
|
||||
* ClassDesc)} and {@link #asSymbol()}.
|
||||
* <p>
|
||||
* A {@code ClassEntry} is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="ClassEntry" target="ConstantPoolBuilder#classEntry(Utf8Entry)" :
|
||||
* ClassEntry(Utf8Entry name) // @link substring="name" target="#name"
|
||||
* }
|
||||
* where {@code name} represents:
|
||||
* <ul>
|
||||
* <li>The internal form of a binary name (JVMS {@jvms 4.2.1}), if and only if
|
||||
* this {@code ClassEntry} represents a class or interface, such as {@code
|
||||
* java/lang/String} for the {@link String} class.
|
||||
* <li>A field descriptor string (JVMS {@jvms 4.3.2}) representing an array type,
|
||||
* if and only if this {@code ClassEntry} represents an array type, such as
|
||||
* {@code [I} for the {@code int[]} type, or {@code [Ljava/lang/String;} for the
|
||||
* {@code String[]} type.
|
||||
* </ul>
|
||||
* A field descriptor string for an array type can be distinguished by its
|
||||
* leading {@code '['} character.
|
||||
*
|
||||
* @apiNote
|
||||
* The internal form of a binary name, where all occurrences of {@code .} in the
|
||||
* name are replaced by {@code /}, is informally known as an <dfn>{@index
|
||||
* "internal name"}</dfn>. This concept also applies to package names in
|
||||
* addition to class and interface names.
|
||||
*
|
||||
* @see ConstantPoolBuilder#classEntry ConstantPoolBuilder::classEntry
|
||||
* @see ClassDesc
|
||||
* @jvms 4.4.1 The {@code CONSTANT_Class_info} Structure
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface ClassEntry
|
||||
extends LoadableConstantEntry
|
||||
permits AbstractPoolEntry.ClassEntryImpl {
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
* <p>
|
||||
* This is equivalent to {@link #asSymbol() asSymbol()}.
|
||||
*/
|
||||
@Override
|
||||
default ConstantDesc constantValue() {
|
||||
return asSymbol();
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return the UTF8 constant pool entry for the class name}
|
||||
* {@return the {@code Utf8Entry} referred by this structure} If the
|
||||
* value of the UTF8 starts with a {@code [}, this represents an array type
|
||||
* and the value is a descriptor string; otherwise, this represents a class
|
||||
* or interface and the value is the {@linkplain ##internalname internal
|
||||
* form} of a binary name.
|
||||
*
|
||||
* @see ConstantPoolBuilder#classEntry(Utf8Entry)
|
||||
* ConstantPoolBuilder::classEntry(Utf8Entry)
|
||||
*/
|
||||
Utf8Entry name();
|
||||
|
||||
/**
|
||||
* {@return the class name, as an internal binary name}
|
||||
* {@return the represented reference type, as the {@linkplain
|
||||
* ##internalname internal form} of a binary name or an array descriptor
|
||||
* string} This is a shortcut for {@link #name() name().stringValue()}.
|
||||
*/
|
||||
String asInternalName();
|
||||
|
||||
/**
|
||||
* {@return the class name, as a symbolic descriptor}
|
||||
* {@return the represented reference type, as a symbolic descriptor} The
|
||||
* returned descriptor is never {@linkplain ClassDesc#isPrimitive()
|
||||
* primitive}.
|
||||
*
|
||||
* @see ConstantPoolBuilder#classEntry(ClassDesc)
|
||||
* ConstantPoolBuilder::classEntry(ClassDesc)
|
||||
*/
|
||||
ClassDesc asSymbol();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -33,10 +33,36 @@ import jdk.internal.classfile.impl.AbstractPoolEntry;
|
|||
import jdk.internal.classfile.impl.Util;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Dynamic_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.10 The CONSTANT_Dynamic_info and CONSTANT_InvokeDynamic_info Structures
|
||||
* Models a {@code CONSTANT_Dynamic_info} structure, representing a <dfn>{@index
|
||||
* "dynamically-computed constant"}</dfn>, in the constant pool of a {@code
|
||||
* class} file.
|
||||
* <p>
|
||||
* The use of a {@code ConstantDynamicEntry} is modeled by a {@link
|
||||
* DynamicConstantDesc}. Conversions are through {@link #asSymbol()} and {@link
|
||||
* ConstantPoolBuilder#constantDynamicEntry(DynamicConstantDesc)}.
|
||||
* <p>
|
||||
* A dynamic constant entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="ConstantDynamicEntry" target="ConstantPoolBuilder#constantDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)" :
|
||||
* ConstantDynamicEntry(
|
||||
* BootstrapMethodEntry bootstrap, // @link substring="bootstrap" target="#bootstrap()"
|
||||
* NameAndTypeEntry nameAndType // @link substring="nameAndType" target="#nameAndType()"
|
||||
* )
|
||||
* }
|
||||
* where {@link #type() nameAndType.type()} is a {@linkplain #typeSymbol()
|
||||
* field descriptor} string.
|
||||
*
|
||||
* @apiNote
|
||||
* A dynamically-computed constant is frequently called a <dfn>{@index "dynamic
|
||||
* constant"}</dfn>, or a <dfn>{@index "condy"}</dfn>, from the abbreviation of
|
||||
* "constant dynamic".
|
||||
*
|
||||
* @see ConstantPoolBuilder#constantDynamicEntry
|
||||
* ConstantPoolBuilder::constantDynamicEntry
|
||||
* @see DynamicConstantDesc
|
||||
* @see java.lang.invoke##condycon Dynamically-computed constants
|
||||
* @jvms 4.4.10 The {@code CONSTANT_Dynamic_info} and {@code
|
||||
* CONSTANT_InvokeDynamic_info} Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface ConstantDynamicEntry
|
||||
|
@ -44,19 +70,28 @@ public sealed interface ConstantDynamicEntry
|
|||
permits AbstractPoolEntry.ConstantDynamicEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the dynamic constant's type}
|
||||
* {@return a symbolic descriptor for the {@linkplain #type() field type} of
|
||||
* this dynamically-computed constant}
|
||||
*/
|
||||
default ClassDesc typeSymbol() {
|
||||
return Util.fieldTypeSymbol(type());
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
* <p>
|
||||
* This is equivalent to {@link #asSymbol() asSymbol()}.
|
||||
*/
|
||||
@Override
|
||||
default ConstantDesc constantValue() {
|
||||
return asSymbol();
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return the symbolic descriptor for the {@code invokedynamic} constant}
|
||||
* {@return a symbolic descriptor for this dynamically-computed constant}
|
||||
*
|
||||
* @see ConstantPoolBuilder#constantDynamicEntry(DynamicConstantDesc)
|
||||
* ConstantPoolBuilder::constantDynamicEntry(DynamicConstantDesc)
|
||||
*/
|
||||
default DynamicConstantDesc<?> asSymbol() {
|
||||
return DynamicConstantDesc.ofNamed(bootstrap().bootstrapMethod().asSymbol(),
|
||||
|
@ -68,10 +103,15 @@ public sealed interface ConstantDynamicEntry
|
|||
}
|
||||
|
||||
/**
|
||||
* {@return the type of the constant}
|
||||
* {@inheritDoc}
|
||||
*
|
||||
* @apiNote
|
||||
* The data type of a dynamically-computed constant depends on its
|
||||
* {@linkplain #type() descriptor}, while the data type of all other
|
||||
* constants can be determined by their {@linkplain #tag() constant type}.
|
||||
*/
|
||||
@Override
|
||||
default TypeKind typeKind() {
|
||||
return TypeKind.fromDescriptor(type().stringValue());
|
||||
return TypeKind.fromDescriptor(type());
|
||||
}
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,14 +27,22 @@ package java.lang.classfile.constantpool;
|
|||
|
||||
import java.lang.classfile.BootstrapMethodEntry;
|
||||
import java.lang.classfile.ClassReader;
|
||||
import java.lang.classfile.attribute.BootstrapMethodsAttribute;
|
||||
import java.util.Iterator;
|
||||
import java.util.NoSuchElementException;
|
||||
|
||||
/**
|
||||
* Provides read access to the constant pool and bootstrap method table of a
|
||||
* classfile.
|
||||
* @jvms 4.4 The Constant Pool
|
||||
* Provides read access to the constant pool and the bootstrap method table of a
|
||||
* {@code class} file.
|
||||
*
|
||||
* <h2 id="index">Index in the Constant Pool</h2>
|
||||
* The constant pool entries are accessed by index. A valid index is in the
|
||||
* range of {@link #size() [1, size())}. It is {@linkplain PoolEntry#width()
|
||||
* unusable} if a {@link LongEntry} or {@link DoubleEntry} is at its previous
|
||||
* index.
|
||||
*
|
||||
* @see BootstrapMethodsAttribute
|
||||
* @jvms 4.4 The Constant Pool
|
||||
* @sealedGraph
|
||||
* @since 24
|
||||
*/
|
||||
|
@ -46,7 +54,7 @@ public sealed interface ConstantPool extends Iterable<PoolEntry>
|
|||
*
|
||||
* @apiNote
|
||||
* If only a particular type of entry is expected, use {@link #entryByIndex(
|
||||
* int, Class) entryByIndex(int, Class)}.
|
||||
* int, Class)}.
|
||||
*
|
||||
* @param index the index within the pool of the desired entry
|
||||
* @throws ConstantPoolException if the index is out of range of the
|
||||
|
@ -55,7 +63,11 @@ public sealed interface ConstantPool extends Iterable<PoolEntry>
|
|||
PoolEntry entryByIndex(int index);
|
||||
|
||||
/**
|
||||
* {@return the size of the constant pool}
|
||||
* {@return the exclusive upper bound of the valid indices of this constant
|
||||
* pool} The actual number of entries is lower because {@code 0}, {@code
|
||||
* size()} are not valid, and a valid index may be unusable.
|
||||
*
|
||||
* @see ##index Index in the Constant Pool
|
||||
*/
|
||||
int size();
|
||||
|
||||
|
@ -66,12 +78,17 @@ public sealed interface ConstantPool extends Iterable<PoolEntry>
|
|||
* @param index the index within the pool of the desired entry
|
||||
* @param cls the entry type
|
||||
* @throws ConstantPoolException if the index is out of range of the
|
||||
* constant pool, or the entry is not of the given type
|
||||
* constant pool or considered unusable, or the entry is not
|
||||
* of the given type
|
||||
*/
|
||||
<T extends PoolEntry> T entryByIndex(int index, Class<T> cls);
|
||||
|
||||
/**
|
||||
* {@return an iterator over pool entries}
|
||||
*
|
||||
* @apiNote
|
||||
* This skips any unusable index and is less error-prone than iterating by
|
||||
* raw index. See <em>{@linkplain ##index Index in the Constant Pool}</em>.
|
||||
*/
|
||||
@Override
|
||||
default Iterator<PoolEntry> iterator() {
|
||||
|
@ -93,7 +110,6 @@ public sealed interface ConstantPool extends Iterable<PoolEntry>
|
|||
};
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* {@return the {@link BootstrapMethodEntry} at the specified index within
|
||||
* the bootstrap method table}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +25,16 @@
|
|||
package java.lang.classfile.constantpool;
|
||||
|
||||
import java.lang.classfile.BootstrapMethodEntry;
|
||||
import java.lang.classfile.ClassBuilder;
|
||||
import java.lang.classfile.ClassFile;
|
||||
import java.lang.classfile.ClassFileBuilder;
|
||||
import java.lang.classfile.ClassModel;
|
||||
import java.lang.classfile.CodeBuilder;
|
||||
import java.lang.classfile.attribute.ConstantValueAttribute;
|
||||
import java.lang.classfile.instruction.ConstantInstruction;
|
||||
import java.lang.constant.*;
|
||||
import java.lang.invoke.MethodHandleInfo;
|
||||
import java.util.List;
|
||||
import java.util.function.Consumer;
|
||||
|
||||
import jdk.internal.classfile.impl.AbstractPoolEntry.ClassEntryImpl;
|
||||
import jdk.internal.classfile.impl.ClassReaderImpl;
|
||||
|
@ -39,14 +45,45 @@ import jdk.internal.classfile.impl.Util;
|
|||
import static java.util.Objects.requireNonNull;
|
||||
|
||||
/**
|
||||
* Builder for the constant pool of a classfile. Provides read and write access
|
||||
* to the constant pool that is being built. Writing is append-only and idempotent
|
||||
* (entry-bearing methods will return an existing entry if there is one).
|
||||
* Builder for the constant pool of a {@code class} file. Provides read and
|
||||
* write access to the constant pool that is {@linkplain ClassFileBuilder#constantPool()
|
||||
* being built}. Writing is append-only (the index of new entries monotonically
|
||||
* increase) and idempotent (entry-bearing methods will return an existing entry
|
||||
* if there is a suitable one).
|
||||
* <p>
|
||||
* For {@code class} file building, an overload of {@link ClassFile#build(
|
||||
* ClassEntry, ConstantPoolBuilder, Consumer) ClassFile::build} takes a
|
||||
* {@code ConstantPoolBuilder}. For {@code class} file transformations via
|
||||
* {@link ClassFile#transformClass ClassFile::transformClass}, the {@link
|
||||
* ClassFile.ConstantPoolSharingOption} controls how the constant pool builder
|
||||
* of the resulting {@code class} is created.
|
||||
*
|
||||
* A {@linkplain ConstantPoolBuilder} is associated with a {@link ClassBuilder}.
|
||||
* The {@linkplain ConstantPoolBuilder} also provides access to some of the
|
||||
* state of the {@linkplain ClassBuilder}, such as classfile processing options.
|
||||
* <h2 id="alien">Alien Constant Pool Entries</h2>
|
||||
* In {@code class} file building and constant pool building, some constant pool
|
||||
* entries supplied may be {@linkplain #canWriteDirect(ConstantPool) alien}
|
||||
* to this constant pool builder of the active class file builder. For example,
|
||||
* {@link #classEntry(Utf8Entry) classEntry(Utf8Entry)} may be called with an
|
||||
* alien UTF8 entry. Alien entries will be converted to a pool entry in
|
||||
* this constant pool builder, reusing equivalent entries or adding new entries
|
||||
* if there is none. As a result, all pool entries returned by entry-bearing
|
||||
* methods in this constant pool builder belong to this constant pool.
|
||||
* <p>
|
||||
* Some {@link ClassFileBuilder} methods may have their outputs adjusted if they
|
||||
* receive pool entries alien to {@linkplain ClassFileBuilder#constantPool
|
||||
* their constant pools}. For example, if an {@link ConstantInstruction#ofLoad
|
||||
* ldc_w} instruction with an alien entry is written to a {@link CodeBuilder},
|
||||
* the {@code CodeBuilder} may emit a functionally equivalent {@code ldc}
|
||||
* instruction instead, if the converted entry can be encoded in such an
|
||||
* instruction.
|
||||
* <p>
|
||||
* To avoid the conversion of alien constant pool entries, such as for the
|
||||
* accuracy of the generated {@code class} file, users can always supply
|
||||
* constant pool entries obtained by calling the constant pool builder
|
||||
* entry-bearing methods of the constant pools associated with the {@code
|
||||
* ClassFileBuilder}. Otherwise, the conversions have no impact on the
|
||||
* behaviors of the generated {@code class} files.
|
||||
*
|
||||
* @see ClassFileBuilder#constantPool()
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface ConstantPoolBuilder
|
||||
|
@ -55,10 +92,14 @@ public sealed interface ConstantPoolBuilder
|
|||
|
||||
/**
|
||||
* {@return a new constant pool builder} The new constant pool builder will
|
||||
* be pre-populated with the contents of the constant pool associated with
|
||||
* the class reader.
|
||||
* be pre-populated with the contents of the constant pool {@linkplain
|
||||
* ClassModel#constantPool() associated with} the given class model. The
|
||||
* index of new entries will start from the {@link ConstantPool#size()
|
||||
* size()} of the source pool.
|
||||
*
|
||||
* @param classModel the class to copy from
|
||||
* @see ClassFile#build(ClassEntry, ConstantPoolBuilder, Consumer)
|
||||
* @see ClassFile.ConstantPoolSharingOption#SHARED_POOL
|
||||
*/
|
||||
static ConstantPoolBuilder of(ClassModel classModel) {
|
||||
return new SplitConstantPool((ClassReaderImpl) classModel.constantPool());
|
||||
|
@ -66,35 +107,47 @@ public sealed interface ConstantPoolBuilder
|
|||
|
||||
/**
|
||||
* {@return a new constant pool builder} The new constant pool builder
|
||||
* will be empty.
|
||||
* will be empty. The index of new entries will start from {@code 1}.
|
||||
*
|
||||
* @see ClassFile.ConstantPoolSharingOption#NEW_POOL
|
||||
*/
|
||||
static ConstantPoolBuilder of() {
|
||||
return new SplitConstantPool();
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return whether the provided constant pool is index-compatible with this
|
||||
* one} This may be because they are the same constant pool, or because this
|
||||
* constant pool was copied from the other.
|
||||
* {@return {@code true} if the index of any entry in the given constant
|
||||
* pool refers to the same entry in this builder} This may be because they
|
||||
* are the same builder, or because this builder was {@linkplain
|
||||
* #of(ClassModel) pre-populated} from the given constant pool.
|
||||
* <p>
|
||||
* If the constant pool of an entry is not directly writable to this pool,
|
||||
* it is alien to this pool, and a {@link ClassFileBuilder} associated
|
||||
* with this constant pool will convert that alien constant pool entry.
|
||||
*
|
||||
* @param constantPool the other constant pool
|
||||
* @param constantPool the given constant pool
|
||||
* @see ClassFileBuilder#constantPool() ClassFileBuilder::constantPool
|
||||
* @see ##alien Alien Constant Pool Entries
|
||||
*/
|
||||
boolean canWriteDirect(ConstantPool constantPool);
|
||||
|
||||
/**
|
||||
* {@return A {@link Utf8Entry} describing the provided {@linkplain String}}
|
||||
* If a UTF8 entry in the pool already describes this string, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return a {@link Utf8Entry} describing the provided {@link String}}
|
||||
*
|
||||
* @param s the string
|
||||
* @see Utf8Entry#stringValue() Utf8Entry::stringValue
|
||||
*/
|
||||
Utf8Entry utf8Entry(String s);
|
||||
|
||||
/**
|
||||
* {@return A {@link Utf8Entry} describing the field descriptor of the provided
|
||||
* {@linkplain ClassDesc}}
|
||||
* If a UTF8 entry in the pool already describes this field descriptor, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return a {@link Utf8Entry} describing the {@linkplain
|
||||
* ClassDesc#descriptorString() field descriptor string} of the provided
|
||||
* {@link ClassDesc}}
|
||||
*
|
||||
* @apiNote
|
||||
* The resulting {@code Utf8Entry} is usually not {@linkplain
|
||||
* #classEntry(Utf8Entry) referable by} a {@link ClassEntry}, which uses
|
||||
* internal form of binary names.
|
||||
*
|
||||
* @param desc the symbolic descriptor for the class
|
||||
*/
|
||||
|
@ -103,10 +156,9 @@ public sealed interface ConstantPoolBuilder
|
|||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link Utf8Entry} describing the method descriptor of the provided
|
||||
* {@linkplain MethodTypeDesc}}
|
||||
* If a UTF8 entry in the pool already describes this field descriptor, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return a {@link Utf8Entry} describing the {@linkplain
|
||||
* MethodTypeDesc#descriptorString() method descriptor string} of the
|
||||
* provided {@link MethodTypeDesc}}
|
||||
*
|
||||
* @param desc the symbolic descriptor for the method type
|
||||
*/
|
||||
|
@ -115,25 +167,24 @@ public sealed interface ConstantPoolBuilder
|
|||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link ClassEntry} describing the class whose internal name
|
||||
* is encoded in the provided {@linkplain Utf8Entry}}
|
||||
* If a Class entry in the pool already describes this class,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link ClassEntry} referring to the provided {@link
|
||||
* Utf8Entry}} The {@code Utf8Entry} describes the internal form
|
||||
* of the binary name of a class or interface or the field descriptor
|
||||
* string of an array type.
|
||||
*
|
||||
* @param ne the constant pool entry describing the internal name of the class
|
||||
* @param ne the {@code Utf8Entry}
|
||||
* @see ClassEntry#name() ClassEntry::name
|
||||
*/
|
||||
ClassEntry classEntry(Utf8Entry ne);
|
||||
|
||||
/**
|
||||
* {@return A {@link ClassEntry} describing the class described by
|
||||
* provided {@linkplain ClassDesc}}
|
||||
* If a Class entry in the pool already describes this class,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link ClassEntry} describing the same reference type
|
||||
* as the provided {@link ClassDesc}}
|
||||
*
|
||||
* @param classDesc the symbolic descriptor for the class
|
||||
* @throws IllegalArgumentException if {@code classDesc} represents a primitive type
|
||||
* @param classDesc the symbolic descriptor for the reference type
|
||||
* @throws IllegalArgumentException if {@code classDesc} represents a
|
||||
* primitive type
|
||||
* @see ClassEntry#asSymbol() ClassEntry::asSymbol
|
||||
*/
|
||||
default ClassEntry classEntry(ClassDesc classDesc) {
|
||||
if (requireNonNull(classDesc).isPrimitive()) {
|
||||
|
@ -145,196 +196,191 @@ public sealed interface ConstantPoolBuilder
|
|||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link PackageEntry} describing the class whose internal name
|
||||
* is encoded in the provided {@linkplain Utf8Entry}}
|
||||
* If a Package entry in the pool already describes this class,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link PackageEntry} referring to the provided {@link
|
||||
* Utf8Entry}} The {@code Utf8Entry} describes the internal form
|
||||
* of the name of a package.
|
||||
*
|
||||
* @param nameEntry the constant pool entry describing the internal name of
|
||||
* the package
|
||||
* @param nameEntry the {@code Utf8Entry}
|
||||
* @see PackageEntry#name() PackageEntry::name
|
||||
*/
|
||||
PackageEntry packageEntry(Utf8Entry nameEntry);
|
||||
|
||||
/**
|
||||
* {@return A {@link PackageEntry} describing the class described by
|
||||
* provided {@linkplain PackageDesc}}
|
||||
* If a Package entry in the pool already describes this class,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link PackageEntry} describing the same package as the
|
||||
* provided {@link PackageDesc}}
|
||||
*
|
||||
* @param packageDesc the symbolic descriptor for the class
|
||||
* @param packageDesc the symbolic descriptor for the package
|
||||
* @see PackageEntry#asSymbol() PackageEntry::asSymbol
|
||||
*/
|
||||
default PackageEntry packageEntry(PackageDesc packageDesc) {
|
||||
return packageEntry(utf8Entry(packageDesc.internalName()));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link ModuleEntry} describing the module whose name
|
||||
* is encoded in the provided {@linkplain Utf8Entry}}
|
||||
* If a module entry in the pool already describes this class,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link ModuleEntry} referring to the provided {@link
|
||||
* Utf8Entry}} The {@code Utf8Entry} describes the module name.
|
||||
*
|
||||
* @param moduleName the constant pool entry describing the module name
|
||||
* @see ModuleEntry#name() ModuleEntry::name
|
||||
*/
|
||||
ModuleEntry moduleEntry(Utf8Entry moduleName);
|
||||
|
||||
/**
|
||||
* {@return A {@link ModuleEntry} describing the module described by
|
||||
* provided {@linkplain ModuleDesc}}
|
||||
* If a module entry in the pool already describes this class,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link ModuleEntry} describing the same module as the provided
|
||||
* {@link ModuleDesc}}
|
||||
*
|
||||
* @param moduleDesc the symbolic descriptor for the class
|
||||
* @param moduleDesc the symbolic descriptor for the module
|
||||
* @see ModuleEntry#asSymbol() ModuleEntry::asSymbol
|
||||
*/
|
||||
default ModuleEntry moduleEntry(ModuleDesc moduleDesc) {
|
||||
return moduleEntry(utf8Entry(moduleDesc.name()));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link NameAndTypeEntry} describing the provided name and type}
|
||||
* If a NameAndType entry in the pool already describes this name and type,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link NameAndTypeEntry} referring to the provided name and
|
||||
* type {@link Utf8Entry}} The name {@code Utf8Entry} describes an
|
||||
* unqualified name or the special name {@value ConstantDescs#INIT_NAME},
|
||||
* and the type {@code Utf8Entry} describes a field or method descriptor
|
||||
* string.
|
||||
*
|
||||
* @param nameEntry the member name
|
||||
* @param typeEntry the member field or method descriptor
|
||||
* @param nameEntry the name {@code Utf8Entry}
|
||||
* @param typeEntry the type {@code Utf8Entry}
|
||||
* @see NameAndTypeEntry#name() NameAndTypeEntry::name
|
||||
* @see NameAndTypeEntry#type() NameAndTypeEntry::type
|
||||
*/
|
||||
NameAndTypeEntry nameAndTypeEntry(Utf8Entry nameEntry, Utf8Entry typeEntry);
|
||||
|
||||
/**
|
||||
* {@return A {@link NameAndTypeEntry} describing the provided name and type}
|
||||
* If a NameAndType entry in the pool already describes this name and type,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link NameAndTypeEntry} describing the provided unqualified
|
||||
* name and field descriptor}
|
||||
*
|
||||
* @param name the member name
|
||||
* @param type the symbolic descriptor for a field type
|
||||
* @param name the unqualified name
|
||||
* @param type the field descriptor
|
||||
*/
|
||||
default NameAndTypeEntry nameAndTypeEntry(String name, ClassDesc type) {
|
||||
return nameAndTypeEntry(utf8Entry(name), utf8Entry(type));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link NameAndTypeEntry} describing the provided name and type}
|
||||
* If a NameAndType entry in the pool already describes this name and type,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link NameAndTypeEntry} describing the provided name and
|
||||
* method descriptor} The name can be an unqualified name or the
|
||||
* special name {@value ConstantDescs#INIT_NAME}.
|
||||
*
|
||||
* @param name the member name
|
||||
* @param type the symbolic descriptor for a method type
|
||||
* @param name the unqualified name, or {@value ConstantDescs#INIT_NAME}
|
||||
* @param type the method descriptor
|
||||
*/
|
||||
default NameAndTypeEntry nameAndTypeEntry(String name, MethodTypeDesc type) {
|
||||
return nameAndTypeEntry(utf8Entry(name), utf8Entry(type));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link FieldRefEntry} describing a field of a class}
|
||||
* If a FieldRef entry in the pool already describes this field,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link FieldRefEntry} referring to a {@link ClassEntry} and a
|
||||
* {@link NameAndTypeEntry}} The {@code ClassEntry} describes a class or
|
||||
* interface that has this field as a member, and the {@code
|
||||
* NameAndTypeEntry} describes the unqualified name and the field descriptor
|
||||
* for this field.
|
||||
*
|
||||
* @param owner the class the field is a member of
|
||||
* @param nameAndType the name and type of the field
|
||||
* @param owner the {@code ClassEntry}
|
||||
* @param nameAndType the {@code NameAndTypeEntry}
|
||||
* @see FieldRefEntry#owner() FieldRefEntry::owner
|
||||
* @see FieldRefEntry#nameAndType() FieldRefEntry::nameAndType
|
||||
*/
|
||||
FieldRefEntry fieldRefEntry(ClassEntry owner, NameAndTypeEntry nameAndType);
|
||||
|
||||
/**
|
||||
* {@return A {@link FieldRefEntry} describing a field of a class}
|
||||
* If a FieldRef entry in the pool already describes this field,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link FieldRefEntry} describing a field of a class}
|
||||
*
|
||||
* @param owner the class the field is a member of
|
||||
* @param name the name of the field
|
||||
* @param type the type of the field
|
||||
* @param owner the class or interface the field is a member of
|
||||
* @param name the unqualified name of the field
|
||||
* @param type the field descriptor
|
||||
* @throws IllegalArgumentException if {@code owner} represents a primitive type
|
||||
* @see FieldRefEntry#typeSymbol() FieldRefEntry::typeSymbol
|
||||
*/
|
||||
default FieldRefEntry fieldRefEntry(ClassDesc owner, String name, ClassDesc type) {
|
||||
return fieldRefEntry(classEntry(owner), nameAndTypeEntry(name, type));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link MethodRefEntry} describing a method of a class}
|
||||
* If a MethodRefEntry entry in the pool already describes this method,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link MethodRefEntry} referring to a {@link ClassEntry} and a
|
||||
* {@link NameAndTypeEntry}} The {@code ClassEntry} describes a class that
|
||||
* has this method as a member, and the {@code NameAndTypeEntry} describes
|
||||
* the unqualified name or the special name {@value ConstantDescs#INIT_NAME}
|
||||
* and the method descriptor for this method.
|
||||
*
|
||||
* @param owner the class the method is a member of
|
||||
* @param nameAndType the name and type of the method
|
||||
* @param owner the {@code ClassEntry}
|
||||
* @param nameAndType the {@code NameAndTypeEntry}
|
||||
* @see MethodRefEntry#owner() MethodRefEntry::owner
|
||||
* @see MethodRefEntry#nameAndType() MethodRefEntry::nameAndType
|
||||
*/
|
||||
MethodRefEntry methodRefEntry(ClassEntry owner, NameAndTypeEntry nameAndType);
|
||||
|
||||
/**
|
||||
* {@return A {@link MethodRefEntry} describing a method of a class}
|
||||
* If a MethodRefEntry entry in the pool already describes this method,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link MethodRefEntry} describing a method of a class}
|
||||
*
|
||||
* @param owner the class the method is a member of
|
||||
* @param name the name of the method
|
||||
* @param type the type of the method
|
||||
* @param name the unqualified name, or special name {@value
|
||||
* ConstantDescs#INIT_NAME}, of the method
|
||||
* @param type the method descriptor
|
||||
* @throws IllegalArgumentException if {@code owner} represents a primitive type
|
||||
* @see MethodRefEntry#typeSymbol() MethodRefEntry::typeSymbol
|
||||
*/
|
||||
default MethodRefEntry methodRefEntry(ClassDesc owner, String name, MethodTypeDesc type) {
|
||||
return methodRefEntry(classEntry(owner), nameAndTypeEntry(name, type));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link InterfaceMethodRefEntry} describing a method of a class}
|
||||
* If a InterfaceMethodRefEntry entry in the pool already describes this method,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return an {@link InterfaceMethodRefEntry} referring to a {@link
|
||||
* ClassEntry} and a {@link NameAndTypeEntry}} The {@code ClassEntry}
|
||||
* describes an interface that has this method as a member, and the {@code
|
||||
* NameAndTypeEntry} describes the unqualified name and the method
|
||||
* descriptor for this method.
|
||||
*
|
||||
* @param owner the class the method is a member of
|
||||
* @param nameAndType the name and type of the method
|
||||
* @param owner the {@code ClassEntry}
|
||||
* @param nameAndType the {@code NameAndTypeEntry}
|
||||
* @see InterfaceMethodRefEntry#owner() InterfaceMethodRefEntry::owner
|
||||
* @see InterfaceMethodRefEntry#nameAndType()
|
||||
* InterfaceMethodRefEntry::nameAndType
|
||||
*/
|
||||
InterfaceMethodRefEntry interfaceMethodRefEntry(ClassEntry owner, NameAndTypeEntry nameAndType);
|
||||
|
||||
/**
|
||||
* {@return A {@link InterfaceMethodRefEntry} describing a method of a class}
|
||||
* If a InterfaceMethodRefEntry entry in the pool already describes this method,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return an {@link InterfaceMethodRefEntry} describing a method of an
|
||||
* interface}
|
||||
*
|
||||
* @param owner the class the method is a member of
|
||||
* @param name the name of the method
|
||||
* @param type the type of the method
|
||||
* @param owner the interface the method is a member of
|
||||
* @param name the unqualified name of the method
|
||||
* @param type the method descriptor
|
||||
* @throws IllegalArgumentException if {@code owner} represents a primitive type
|
||||
* @see InterfaceMethodRefEntry#typeSymbol() InterfaceMethodRefEntry::typeSymbol
|
||||
*/
|
||||
default InterfaceMethodRefEntry interfaceMethodRefEntry(ClassDesc owner, String name, MethodTypeDesc type) {
|
||||
return interfaceMethodRefEntry(classEntry(owner), nameAndTypeEntry(name, type));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link MethodTypeEntry} describing a method type}
|
||||
* If a MethodType entry in the pool already describes this method type,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link MethodTypeEntry} describing the same method type as
|
||||
* the provided {@link MethodTypeDesc}}
|
||||
*
|
||||
* @param descriptor the symbolic descriptor of the method type
|
||||
* @see MethodTypeEntry#asSymbol() MethodTypeEntry::asSymbol
|
||||
*/
|
||||
MethodTypeEntry methodTypeEntry(MethodTypeDesc descriptor);
|
||||
|
||||
/**
|
||||
* {@return A {@link MethodTypeEntry} describing a method type}
|
||||
* If a MethodType entry in the pool already describes this method type,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link MethodTypeEntry} referring to a {@link Utf8Entry}}
|
||||
* The {@code Utf8Entry} represents a method descriptor string.
|
||||
*
|
||||
* @param descriptor the constant pool entry for the method type descriptor
|
||||
* @param descriptor the {@code Utf8Entry}
|
||||
* @see MethodTypeEntry#descriptor() MethodTypeEntry::descriptor
|
||||
*/
|
||||
MethodTypeEntry methodTypeEntry(Utf8Entry descriptor);
|
||||
|
||||
/**
|
||||
* {@return A {@link MethodHandleEntry} describing a direct method handle}
|
||||
* If a MethodHandle entry in the pool already describes this method handle,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link MethodHandleEntry} describing the same method handle as
|
||||
* the given {@link DirectMethodHandleDesc}}
|
||||
*
|
||||
* @param descriptor the symbolic descriptor of the method handle
|
||||
* @see MethodHandleEntry#asSymbol() MethodHandleEntry::asSymbol
|
||||
*/
|
||||
default MethodHandleEntry methodHandleEntry(DirectMethodHandleDesc descriptor) {
|
||||
var owner = classEntry(descriptor.owner());
|
||||
|
@ -347,125 +393,133 @@ public sealed interface ConstantPoolBuilder
|
|||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link MethodHandleEntry} describing a field accessor or method}
|
||||
* If a MethodHandle entry in the pool already describes this method handle,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link MethodHandleEntry} encoding a reference kind and
|
||||
* referring to a {@link MemberRefEntry}} The reference kind must be
|
||||
* in {@code [1, 9]}, and the {@code MemberRefEntry} is subject to
|
||||
* various restrictions based on the reference kind (JVMS {@jvms 4.4.8}).
|
||||
*
|
||||
* @param refKind the reference kind of the method handle (JVMS {@jvms 4.4.8})
|
||||
* @param reference the constant pool entry describing the field or method
|
||||
* @param refKind the reference kind of the method handle
|
||||
* @param reference the {@code MemberRefEntry}
|
||||
* @see MethodHandleInfo##refKinds Reference kinds
|
||||
* @see MethodHandleEntry#kind() MethodHandleEntry::kind
|
||||
* @see MethodHandleEntry#reference() MethodHandleEntry::reference
|
||||
*/
|
||||
MethodHandleEntry methodHandleEntry(int refKind, MemberRefEntry reference);
|
||||
|
||||
/**
|
||||
* {@return An {@link InvokeDynamicEntry} describing a dynamic call site}
|
||||
* If an InvokeDynamic entry in the pool already describes this site,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return an {@link InvokeDynamicEntry} describing the same dynamic call
|
||||
* site as the provided {@link DynamicCallSiteDesc}}
|
||||
*
|
||||
* @param dcsd the symbolic descriptor of the method handle
|
||||
* @param dcsd the symbolic descriptor of the dynamic call site
|
||||
* @see InvokeDynamicEntry#asSymbol() InvokeDynamicEntry::asSymbol
|
||||
*/
|
||||
default InvokeDynamicEntry invokeDynamicEntry(DynamicCallSiteDesc dcsd) {
|
||||
return invokeDynamicEntry(bsmEntry((DirectMethodHandleDesc)dcsd.bootstrapMethod(), List.of(dcsd.bootstrapArgs())), nameAndTypeEntry(dcsd.invocationName(), dcsd.invocationType()));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return An {@link InvokeDynamicEntry} describing a dynamic call site}
|
||||
* If an InvokeDynamic entry in the pool already describes this site,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return an {@link InvokeDynamicEntry} referring to a {@link
|
||||
* BootstrapMethodEntry} and a {@link NameAndTypeEntry}}
|
||||
* The {@code BootstrapMethodEntry} describes the bootstrap method
|
||||
* and its invocation arguments in addition to the name and type,
|
||||
* and the {@code NameAndTypeEntry} a name and a method descriptor.
|
||||
*
|
||||
* @param bootstrapMethodEntry the entry in the bootstrap method table
|
||||
* @param nameAndType the invocation name and type
|
||||
* @param bootstrapMethodEntry the {@code BootstrapMethodEntry}
|
||||
* @param nameAndType the {@code NameAndTypeEntry}
|
||||
* @see InvokeDynamicEntry#bootstrap() InvokeDynamicEntry::bootstrap
|
||||
* @see InvokeDynamicEntry#nameAndType() InvokeDynamicEntry::nameAndType
|
||||
*/
|
||||
InvokeDynamicEntry invokeDynamicEntry(BootstrapMethodEntry bootstrapMethodEntry,
|
||||
NameAndTypeEntry nameAndType);
|
||||
|
||||
/**
|
||||
* {@return A {@link ConstantDynamicEntry} describing a dynamic constant}
|
||||
* If a ConstantDynamic entry in the pool already describes this site,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link ConstantDynamicEntry} describing the dynamic constant
|
||||
* as the provided {@link DynamicConstantDesc}}
|
||||
*
|
||||
* @param dcd the symbolic descriptor of the constant
|
||||
* @see ConstantDynamicEntry#asSymbol() ConstantDynamicEntry::asSymbol
|
||||
*/
|
||||
default ConstantDynamicEntry constantDynamicEntry(DynamicConstantDesc<?> dcd) {
|
||||
return constantDynamicEntry(bsmEntry(dcd.bootstrapMethod(), List.of(dcd.bootstrapArgs())), nameAndTypeEntry(dcd.constantName(), dcd.constantType()));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link ConstantDynamicEntry} describing a dynamic constant}
|
||||
* If a ConstantDynamic entry in the pool already describes this site,
|
||||
* it is returned; otherwise, a new entry is added and the new entry is
|
||||
* returned.
|
||||
* {@return a {@link ConstantDynamicEntry} referring to a {@link
|
||||
* BootstrapMethodEntry} and a {@link NameAndTypeEntry}}
|
||||
* The {@code BootstrapMethodEntry} describes the bootstrap method
|
||||
* and its invocation arguments in addition to the name and type,
|
||||
* and the {@code NameAndTypeEntry} a name and a field descriptor.
|
||||
*
|
||||
* @param bootstrapMethodEntry the entry in the bootstrap method table
|
||||
* @param nameAndType the invocation name and type
|
||||
* @param bootstrapMethodEntry the {@code BootstrapMethodEntry}
|
||||
* @param nameAndType the {@code NameAndTypeEntry}
|
||||
* @see ConstantDynamicEntry#bootstrap() ConstantDynamicEntry::bootstrap
|
||||
* @see ConstantDynamicEntry#nameAndType() ConstantDynamicEntry::nameAndType
|
||||
*/
|
||||
ConstantDynamicEntry constantDynamicEntry(BootstrapMethodEntry bootstrapMethodEntry, NameAndTypeEntry nameAndType);
|
||||
|
||||
/**
|
||||
* {@return An {@link IntegerEntry} describing the provided value}
|
||||
* If an integer entry in the pool already describes this value, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return an {@link IntegerEntry} describing the provided value}
|
||||
*
|
||||
* @param value the value
|
||||
* @see IntegerEntry#intValue() IntegerEntry::intValue
|
||||
*/
|
||||
IntegerEntry intEntry(int value);
|
||||
|
||||
/**
|
||||
* {@return A {@link FloatEntry} describing the provided value}
|
||||
* If a float entry in the pool already describes this value, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return a {@link FloatEntry} describing the provided value}
|
||||
*
|
||||
* @param value the value
|
||||
* @see FloatEntry#floatValue() FloatEntry::floatValue
|
||||
*/
|
||||
FloatEntry floatEntry(float value);
|
||||
|
||||
/**
|
||||
* {@return A {@link LongEntry} describing the provided value}
|
||||
* If a long entry in the pool already describes this value, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return a {@link LongEntry} describing the provided value}
|
||||
*
|
||||
* @param value the value
|
||||
* @see LongEntry#longValue() LongEntry::longValue
|
||||
*/
|
||||
LongEntry longEntry(long value);
|
||||
|
||||
/**
|
||||
* {@return A {@link DoubleEntry} describing the provided value}
|
||||
* If a double entry in the pool already describes this value, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return a {@link DoubleEntry} describing the provided value}
|
||||
*
|
||||
* @param value the value
|
||||
* @see DoubleEntry#doubleValue() DoubleEntry::doubleValue
|
||||
*/
|
||||
DoubleEntry doubleEntry(double value);
|
||||
|
||||
/**
|
||||
* {@return A {@link StringEntry} referencing the provided UTF8 entry}
|
||||
* If a String entry in the pool already describes this value, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return a {@link StringEntry} referring to a {@link Utf8Entry}}
|
||||
* The {@code Utf8Entry} describes the string value.
|
||||
*
|
||||
* @param utf8 the UTF8 entry describing the string
|
||||
* @param utf8 the {@code Utf8Entry}
|
||||
* @see StringEntry#utf8() StringEntry::utf8
|
||||
*/
|
||||
StringEntry stringEntry(Utf8Entry utf8);
|
||||
|
||||
/**
|
||||
* {@return A {@link StringEntry} describing the provided value}
|
||||
* If a string entry in the pool already describes this value, it is returned;
|
||||
* otherwise, a new entry is added and the new entry is returned.
|
||||
* {@return a {@link StringEntry} describing the provided value}
|
||||
*
|
||||
* @param value the value
|
||||
* @see StringEntry#stringValue() StringEntry::stringValue
|
||||
*/
|
||||
default StringEntry stringEntry(String value) {
|
||||
return stringEntry(utf8Entry(value));
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link ConstantValueEntry} describing the provided
|
||||
* Integer, Long, Float, Double, or String constant}
|
||||
* {@return a {@link ConstantValueEntry} describing the provided constant
|
||||
* {@link Integer}, {@link Long}, {@link Float}, {@link Double}, or {@link
|
||||
* String} value}
|
||||
*
|
||||
* @param c the constant
|
||||
* @see ConstantValueEntry#constantValue()
|
||||
* @param c the provided constant value
|
||||
* @throws IllegalArgumentException if the value is not one of {@code
|
||||
* Integer}, {@code Long}, {@code Float}, {@code Double}, or {@code
|
||||
* String}
|
||||
* @see ConstantValueEntry#constantValue() ConstantValueEntry::constantValue
|
||||
* @see ConstantValueAttribute#of(ConstantDesc)
|
||||
* ConstantValueAttribute::of(ConstantDesc)
|
||||
*/
|
||||
default ConstantValueEntry constantValueEntry(ConstantDesc c) {
|
||||
if (c instanceof Integer i) return intEntry(i);
|
||||
|
@ -477,13 +531,10 @@ public sealed interface ConstantPoolBuilder
|
|||
}
|
||||
|
||||
/**
|
||||
* {@return A {@link LoadableConstantEntry} describing the provided
|
||||
* constant} The constant should be an Integer, String, Long, Float,
|
||||
* Double, ClassDesc (for a Class constant), MethodTypeDesc (for a MethodType
|
||||
* constant), DirectMethodHandleDesc (for a MethodHandle constant), or
|
||||
* a DynamicConstantDesc (for a dynamic constant.)
|
||||
* {@return a {@link LoadableConstantEntry} describing the provided constant
|
||||
* value}
|
||||
*
|
||||
* @param c the constant
|
||||
* @param c the nominal descriptor for the constant
|
||||
*/
|
||||
default LoadableConstantEntry loadableConstantEntry(ConstantDesc c) {
|
||||
if (c instanceof Integer i) return intEntry(i);
|
||||
|
@ -500,10 +551,10 @@ public sealed interface ConstantPoolBuilder
|
|||
|
||||
/**
|
||||
* {@return a {@link BootstrapMethodEntry} describing the provided
|
||||
* bootstrap method and static arguments}
|
||||
* bootstrap method and arguments}
|
||||
*
|
||||
* @param methodReference the bootstrap method
|
||||
* @param arguments the bootstrap arguments
|
||||
* @param arguments the arguments
|
||||
*/
|
||||
default BootstrapMethodEntry bsmEntry(DirectMethodHandleDesc methodReference,
|
||||
List<ConstantDesc> arguments) {
|
||||
|
@ -512,11 +563,16 @@ public sealed interface ConstantPoolBuilder
|
|||
}
|
||||
|
||||
/**
|
||||
* {@return a {@link BootstrapMethodEntry} describing the provided
|
||||
* bootstrap method and static arguments}
|
||||
* {@return a {@link BootstrapMethodEntry} referring to a {@link
|
||||
* MethodHandleEntry} and a list of {@link LoadableConstantEntry}}
|
||||
* The {@code MethodHandleEntry} is the bootstrap method, and the
|
||||
* list of {@code LoadableConstantEntry} is the arguments.
|
||||
*
|
||||
* @param methodReference the bootstrap method
|
||||
* @param arguments the bootstrap arguments
|
||||
* @param methodReference the {@code MethodHandleEntry}
|
||||
* @param arguments the list of {@code LoadableConstantEntry}
|
||||
* @see BootstrapMethodEntry#bootstrapMethod()
|
||||
* BootstrapMethodEntry::bootstrapMethod
|
||||
* @see BootstrapMethodEntry#arguments() BootstrapMethodEntry::arguments
|
||||
*/
|
||||
BootstrapMethodEntry bsmEntry(MethodHandleEntry methodReference,
|
||||
List<LoadableConstantEntry> arguments);
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2023, 2025, 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 java.lang.classfile.constantpool;
|
|||
|
||||
/**
|
||||
* Thrown to indicate that requested entry cannot be obtained from the constant
|
||||
* pool.
|
||||
* pool or the bootstrap method table. This is also thrown when the lazy
|
||||
* evaluation of constant pool or bootstrap method table entries encounter
|
||||
* format errors.
|
||||
*
|
||||
* @since 24
|
||||
*/
|
||||
|
@ -47,7 +49,8 @@ public class ConstantPoolException extends IllegalArgumentException {
|
|||
* Constructs a {@code ConstantPoolException} with the specified detail
|
||||
* message.
|
||||
*
|
||||
* @param message the detail message.
|
||||
* @param message the detail message, may be {@code null} for no detail
|
||||
* message
|
||||
*/
|
||||
public ConstantPoolException(String message) {
|
||||
super(message);
|
||||
|
@ -55,11 +58,10 @@ public class ConstantPoolException extends IllegalArgumentException {
|
|||
|
||||
/**
|
||||
* Constructs a {@code ConstantPoolException} with the specified cause and
|
||||
* a detail message of {@code (cause==null ? null : cause.toString())}.
|
||||
* @param cause the cause (which is saved for later retrieval by the
|
||||
* {@link Throwable#getCause()} method). (A {@code null} value is
|
||||
* permitted, and indicates that the cause is nonexistent or
|
||||
* unknown.)
|
||||
* a detail message of {@code cause == null ? null : cause.toString()}.
|
||||
*
|
||||
* @param cause the cause, may be {@code null} for nonexistent or unknown
|
||||
* cause
|
||||
*/
|
||||
public ConstantPoolException(Throwable cause) {
|
||||
super(cause);
|
||||
|
@ -69,12 +71,10 @@ public class ConstantPoolException extends IllegalArgumentException {
|
|||
* Constructs a {@code ConstantPoolException} with the specified detail
|
||||
* message and cause.
|
||||
*
|
||||
* @param message the detail message (which is saved for later retrieval
|
||||
* by the {@link Throwable#getMessage()} method).
|
||||
* @param cause the cause (which is saved for later retrieval by the
|
||||
* {@link Throwable#getCause()} method). (A {@code null} value
|
||||
* is permitted, and indicates that the cause is nonexistent or
|
||||
* unknown.)
|
||||
* @param message the detail message, may be {@code null} for no detail
|
||||
* message
|
||||
* @param cause the cause, may be {@code null} for nonexistent or unknown
|
||||
* cause
|
||||
*/
|
||||
public ConstantPoolException(String message, Throwable cause) {
|
||||
super(message, cause);
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +28,11 @@ import java.lang.classfile.Attributes;
|
|||
import java.lang.constant.ConstantDesc;
|
||||
|
||||
/**
|
||||
* Models a constant pool entry that can be used as the constant in a
|
||||
* {@link Attributes#constantValue() ConstantValue} attribute; this includes the four
|
||||
* primitive constant types and {@linkplain String} constants.
|
||||
* Marker interface for constant pool entries that can represent constant values
|
||||
* in the {@link Attributes#constantValue() ConstantValue} attribute.
|
||||
*
|
||||
* @see ConstantPoolBuilder#constantValueEntry
|
||||
* ConstantPoolBuilder::constantValueEntry
|
||||
* @sealedGraph
|
||||
* @since 24
|
||||
*/
|
||||
|
@ -39,8 +40,8 @@ public sealed interface ConstantValueEntry extends LoadableConstantEntry
|
|||
permits DoubleEntry, FloatEntry, IntegerEntry, LongEntry, StringEntry {
|
||||
|
||||
/**
|
||||
* {@return the constant value} The constant value will be an {@link Integer},
|
||||
* {@link Long}, {@link Float}, {@link Double}, or {@link String}.
|
||||
* {@return the constant value} The constant value will be an {@link
|
||||
* Integer}, {@link Long}, {@link Float}, {@link Double}, or {@link String}.
|
||||
*
|
||||
* @see ConstantPoolBuilder#constantValueEntry(ConstantDesc)
|
||||
*/
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +29,20 @@ import java.lang.classfile.TypeKind;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Double_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.5 The CONSTANT_Long_info and CONSTANT_Double_info Structures
|
||||
* Models a {@code CONSTANT_Double_info} structure, representing a {@code
|
||||
* double} constant, in the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code DoubleEntry} is modeled by a {@code double}. Conversions
|
||||
* are through {@link ConstantPoolBuilder#doubleEntry} and {@link #doubleValue()}.
|
||||
* In the conversions, all NaN values of the {@code double} may be collapsed
|
||||
* into a single {@linkplain Double#NaN "canonical" NaN value}.
|
||||
* <p>
|
||||
* A double entry has a {@linkplain #width() width} of {@code 2}, making its
|
||||
* subsequent constant pool index valid and unusable.
|
||||
*
|
||||
* @see ConstantPoolBuilder#doubleEntry ConstantPoolBuilder::doubleEntry
|
||||
* @jvms 4.4.5 The {@code CONSTANT_Long_info} and {@code CONSTANT_Double_info}
|
||||
* Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface DoubleEntry
|
||||
|
@ -40,13 +50,13 @@ public sealed interface DoubleEntry
|
|||
permits AbstractPoolEntry.DoubleEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return the double value}
|
||||
* {@return the {@code double} value}
|
||||
*
|
||||
* @see ConstantPoolBuilder#doubleEntry(double)
|
||||
* ConstantPoolBuilder::doubleEntry(double)
|
||||
*/
|
||||
double doubleValue();
|
||||
|
||||
/**
|
||||
* {@return the type of the constant}
|
||||
*/
|
||||
@Override
|
||||
default TypeKind typeKind() {
|
||||
return TypeKind.DOUBLE;
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +27,27 @@ package java.lang.classfile.constantpool;
|
|||
import java.lang.classfile.BootstrapMethodEntry;
|
||||
|
||||
/**
|
||||
* Models a dynamic constant pool entry, which is either {@link ConstantDynamicEntry}
|
||||
* or {@link InvokeDynamicEntry}.
|
||||
* @jvms 4.4.10 The CONSTANT_Dynamic_info and CONSTANT_InvokeDynamic_info Structures
|
||||
* Superinterface modeling dynamically-computed constant pool entries, which
|
||||
* include {@link ConstantDynamicEntry} and {@link InvokeDynamicEntry}, in the
|
||||
* constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* Different types of dynamically-computed constant pool entries bear structural
|
||||
* similarities, but they appear in distinct locations. As a result, their uses
|
||||
* are represented by different symbolic descriptors, specific to each subtype.
|
||||
* <p>
|
||||
* A dynamic constant entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* DynamicConstantPoolEntry(
|
||||
* BootstrapMethodEntry bootstrap, // @link substring="bootstrap" target="#bootstrap()"
|
||||
* NameAndTypeEntry nameAndType // @link substring="nameAndType" target="#nameAndType()"
|
||||
* )
|
||||
* }
|
||||
*
|
||||
* @see java.lang.invoke##jvm_mods Dynamic resolution of call sites and
|
||||
* constants
|
||||
* @jvms 4.4.10 The {@code CONSTANT_Dynamic_info} and {@code
|
||||
* CONSTANT_InvokeDynamic_info} Structures
|
||||
* @jvms 5.4.3.6 Dynamically-Computed Constant and Call Site Resolution
|
||||
* @sealedGraph
|
||||
* @since 24
|
||||
*/
|
||||
|
@ -39,28 +56,50 @@ public sealed interface DynamicConstantPoolEntry extends PoolEntry
|
|||
|
||||
/**
|
||||
* {@return the entry in the bootstrap method table for this constant}
|
||||
*
|
||||
* @see java.lang.invoke##bsm Execution of bootstrap methods
|
||||
* @see ConstantPoolBuilder#constantDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)
|
||||
* ConstantPoolBuilder::constantDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)
|
||||
* @see ConstantPoolBuilder#invokeDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)
|
||||
* ConstantPoolBuilder::invokeDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)
|
||||
*/
|
||||
BootstrapMethodEntry bootstrap();
|
||||
|
||||
/**
|
||||
* {@return index of the entry in the bootstrap method table for this constant}
|
||||
* {@return index of the entry in the bootstrap method table for this
|
||||
* constant} The return value is equivalent to {@code
|
||||
* bootstrap().bsmIndex()}.
|
||||
*/
|
||||
int bootstrapMethodIndex();
|
||||
|
||||
/**
|
||||
* {@return the invocation name and type}
|
||||
* {@return the name and the descriptor string indicated by this symbolic
|
||||
* reference}
|
||||
*
|
||||
* @see java.lang.invoke##bsm Execution of bootstrap methods
|
||||
* @see ConstantPoolBuilder#constantDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)
|
||||
* ConstantPoolBuilder::constantDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)
|
||||
* @see ConstantPoolBuilder#invokeDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)
|
||||
* ConstantPoolBuilder::invokeDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)
|
||||
*/
|
||||
NameAndTypeEntry nameAndType();
|
||||
|
||||
/**
|
||||
* {@return the invocation name}
|
||||
* {@return the name indicated by this symbolic reference}
|
||||
*/
|
||||
default Utf8Entry name() {
|
||||
return nameAndType().name();
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return the invocation type}
|
||||
* {@return the descriptor string indicated by this symbolic reference}
|
||||
* This is a field descriptor string if this entry is a {@link
|
||||
* ConstantDynamicEntry}, or a method descriptor string if this entry is a
|
||||
* {@link InvokeDynamicEntry}.
|
||||
*
|
||||
* @apiNote
|
||||
* Each subinterface has its specific accessor named {@code typeSymbol} for
|
||||
* the symbolic descriptor derived from this descriptor string.
|
||||
*/
|
||||
default Utf8Entry type() {
|
||||
return nameAndType().type();
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -30,17 +30,31 @@ import jdk.internal.classfile.impl.AbstractPoolEntry;
|
|||
import jdk.internal.classfile.impl.Util;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Fieldref_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.2 The CONSTANT_Fieldref_info, CONSTANT_Methodref_info, and CONSTANT_InterfaceMethodref_info Structures
|
||||
* Models a {@code CONSTANT_Fieldref_info} structure, or a symbolic reference
|
||||
* to a field, in the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* A field reference constant pool entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="FieldRefEntry" target="ConstantPoolBuilder#fieldRefEntry(ClassEntry, NameAndTypeEntry)" :
|
||||
* FieldRefEntry(
|
||||
* ClassEntry owner, // @link substring="owner" target="#owner()"
|
||||
* NameAndTypeEntry nameAndType // @link substring="nameAndType" target="#nameAndType()"
|
||||
* )
|
||||
* }
|
||||
* where the {@link #type() nameAndType.type()} represents a {@linkplain
|
||||
* #typeSymbol() field descriptor} string.
|
||||
*
|
||||
* @see ConstantPoolBuilder#fieldRefEntry ConstantPoolBuilder::fieldRefEntry
|
||||
* @jvms 4.4.2 The {@code CONSTANT_Fieldref_info}, {@code
|
||||
* CONSTANT_Methodref_info}, and {@code
|
||||
* CONSTANT_InterfaceMethodref_info} Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface FieldRefEntry extends MemberRefEntry
|
||||
permits AbstractPoolEntry.FieldRefEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the field's type}
|
||||
* {@return a symbolic descriptor for the {@linkplain #type() field type}}
|
||||
*/
|
||||
default ClassDesc typeSymbol() {
|
||||
return Util.fieldTypeSymbol(type());
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +29,17 @@ import java.lang.classfile.TypeKind;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Float_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.4 The CONSTANT_Integer_info and CONSTANT_Float_info Structures
|
||||
* Models a {@code CONSTANT_Float_info} structure, or a {@code float} constant,
|
||||
* in the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code FloatEntry} is modeled by a {@code float}. Conversions
|
||||
* are through {@link ConstantPoolBuilder#floatEntry} and {@link #floatValue()}.
|
||||
* In the conversions, all NaN values of the {@code float} may be collapsed into
|
||||
* a single {@linkplain Float#NaN "canonical" NaN value}.
|
||||
*
|
||||
* @see ConstantPoolBuilder#floatEntry ConstantPoolBuilder::floatEntry
|
||||
* @jvms 4.4.4 The {@code CONSTANT_Integer_info} and {@code CONSTANT_Float_info}
|
||||
* Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface FloatEntry
|
||||
|
@ -40,14 +47,12 @@ public sealed interface FloatEntry
|
|||
permits AbstractPoolEntry.FloatEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return the float value}
|
||||
* {@return the {@code float} value}
|
||||
*
|
||||
* @see ConstantPoolBuilder#floatEntry(float)
|
||||
*/
|
||||
|
||||
float floatValue();
|
||||
|
||||
/**
|
||||
* {@return the type of the constant}
|
||||
*/
|
||||
@Override
|
||||
default TypeKind typeKind() {
|
||||
return TypeKind.FLOAT;
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +29,15 @@ import java.lang.classfile.TypeKind;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Integer_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.4 The CONSTANT_Integer_info and CONSTANT_Float_info Structures
|
||||
* Models a {@code CONSTANT_Integer_info} structure, or an {@code int} constant,
|
||||
* in the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code IntegerEntry} is modeled by an {@code int}. Conversions
|
||||
* are through {@link ConstantPoolBuilder#intEntry(int)} and {@link #intValue()}.
|
||||
*
|
||||
* @see ConstantPoolBuilder#intEntry ConstantPoolBuilder::intEntry
|
||||
* @jvms 4.4.4 The {@code CONSTANT_Integer_info} and {@code CONSTANT_Float_info}
|
||||
* Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface IntegerEntry
|
||||
|
@ -40,13 +45,12 @@ public sealed interface IntegerEntry
|
|||
permits AbstractPoolEntry.IntegerEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return the integer value}
|
||||
* {@return the {@code int} value}
|
||||
*
|
||||
* @see ConstantPoolBuilder#intEntry(int)
|
||||
*/
|
||||
int intValue();
|
||||
|
||||
/**
|
||||
* {@return the type of the constant}
|
||||
*/
|
||||
@Override
|
||||
default TypeKind typeKind() {
|
||||
return TypeKind.INT;
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -30,10 +30,26 @@ import jdk.internal.classfile.impl.AbstractPoolEntry;
|
|||
import jdk.internal.classfile.impl.Util;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_InterfaceMethodRef_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.2 The CONSTANT_Fieldref_info, CONSTANT_Methodref_info, and CONSTANT_InterfaceMethodref_info Structures
|
||||
* Models a {@code CONSTANT_InterfaceMethodRef_info} structure, or a symbolic
|
||||
* reference to an interface method, in the constant pool of a {@code class}
|
||||
* file.
|
||||
* <p>
|
||||
* An interface method reference entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="InterfaceMethodRefEntry" target="ConstantPoolBuilder#interfaceMethodRefEntry(ClassEntry, NameAndTypeEntry)" :
|
||||
* InterfaceMethodRefEntry(
|
||||
* ClassEntry owner, // @link substring="owner" target="#owner()"
|
||||
* NameAndTypeEntry nameAndType // @link substring="nameAndType" target="#nameAndType()"
|
||||
* )
|
||||
* }
|
||||
* where the {@link #type() type} in the {@code nameAndType} is a {@linkplain
|
||||
* #typeSymbol() method descriptor} string.
|
||||
*
|
||||
* @see ConstantPoolBuilder#interfaceMethodRefEntry
|
||||
* ConstantPoolBuilder::interfaceMethodRefEntry
|
||||
* @jvms 4.4.2 The {@code CONSTANT_Fieldref_info}, {@code
|
||||
* CONSTANT_Methodref_info}, and {@code
|
||||
* CONSTANT_InterfaceMethodref_info} Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface InterfaceMethodRefEntry
|
||||
|
@ -41,7 +57,7 @@ public sealed interface InterfaceMethodRefEntry
|
|||
permits AbstractPoolEntry.InterfaceMethodRefEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the interface method's type}
|
||||
* {@return a symbolic descriptor for the {@linkplain #type() method type}}
|
||||
*/
|
||||
default MethodTypeDesc typeSymbol() {
|
||||
return Util.methodTypeSymbol(type());
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -32,9 +32,38 @@ import jdk.internal.classfile.impl.AbstractPoolEntry;
|
|||
import jdk.internal.classfile.impl.Util;
|
||||
|
||||
/**
|
||||
* Models a constant pool entry for a dynamic call site.
|
||||
* @jvms 4.4.10 The CONSTANT_Dynamic_info and CONSTANT_InvokeDynamic_info Structures
|
||||
* Models a {@code CONSTANT_InvokeDynamic_info} structure, or the symbolic
|
||||
* reference to a <dfn>{@index "dynamically-computed call site"}</dfn>, in the
|
||||
* constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code InvokeDynamicEntry} is modeled by a {@link
|
||||
* DynamicCallSiteDesc} symbolic descriptor. It can be obtained from {@link
|
||||
* #asSymbol() InvokeDynamicEntry::asSymbol} and converted back to a constant
|
||||
* pool entry through {@link ConstantPoolBuilder#invokeDynamicEntry(DynamicCallSiteDesc)
|
||||
* ConstantPoolBuilder::invokeDynamicEntry}.
|
||||
* <p>
|
||||
* An invoke dynamic entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="InvokeDynamicEntry" target="ConstantPoolBuilder#invokeDynamicEntry(BootstrapMethodEntry, NameAndTypeEntry)" :
|
||||
* InvokeDynamicEntry(
|
||||
* BootstrapMethodEntry bootstrap, // @link substring="bootstrap" target="#bootstrap()"
|
||||
* NameAndTypeEntry nameAndType // @link substring="nameAndType" target="#nameAndType()"
|
||||
* )
|
||||
* }
|
||||
* where the {@link #type() type} in the {@code nameAndType} is a {@linkplain
|
||||
* #typeSymbol() method descriptor} string.
|
||||
*
|
||||
* @apiNote
|
||||
* A dynamically-computed call site is frequently called a <dfn>{@index "dynamic
|
||||
* call site"}</dfn>, or an <dfn>{@index "indy"}</dfn>, from the abbreviation of
|
||||
* "invoke dynamic".
|
||||
*
|
||||
* @see ConstantPoolBuilder#invokeDynamicEntry
|
||||
* ConstantPoolBuilder::invokeDynamicEntry
|
||||
* @see DynamicCallSiteDesc
|
||||
* @see java.lang.invoke##indyinsn Dynamically-computed call sites
|
||||
* @jvms 4.4.10 The {@code CONSTANT_Dynamic_info} and {@code
|
||||
* CONSTANT_InvokeDynamic_info} Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface InvokeDynamicEntry
|
||||
|
@ -42,14 +71,18 @@ public sealed interface InvokeDynamicEntry
|
|||
permits AbstractPoolEntry.InvokeDynamicEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the call site's invocation type}
|
||||
* {@return a symbolic descriptor for the {@linkplain #type() invocation
|
||||
* type} of this dynamic call site}
|
||||
*/
|
||||
default MethodTypeDesc typeSymbol() {
|
||||
return Util.methodTypeSymbol(type());
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the dynamic call site}
|
||||
* {@return a symbolic descriptor for this dynamic call site}
|
||||
*
|
||||
* @see ConstantPoolBuilder#invokeDynamicEntry(DynamicCallSiteDesc)
|
||||
* ConstantPoolBuilder::invokeDynamicEntry(DynamicCallSiteDesc)
|
||||
*/
|
||||
default DynamicCallSiteDesc asSymbol() {
|
||||
return DynamicCallSiteDesc.of(bootstrap().bootstrapMethod().asSymbol(),
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -24,13 +24,22 @@
|
|||
*/
|
||||
package java.lang.classfile.constantpool;
|
||||
|
||||
import java.lang.classfile.CodeBuilder;
|
||||
import java.lang.classfile.Opcode;
|
||||
import java.lang.classfile.TypeKind;
|
||||
import java.lang.classfile.instruction.ConstantInstruction;
|
||||
import java.lang.constant.ConstantDesc;
|
||||
|
||||
/**
|
||||
* Marker interface for constant pool entries suitable for loading via the
|
||||
* {@code LDC} instructions.
|
||||
* {@link ConstantInstruction.LoadConstantInstruction ldc} instructions.
|
||||
* <p>
|
||||
* The use of a {@code LoadableConstantEntry} is modeled by a {@link ConstantDesc}.
|
||||
* Conversions are through {@link ConstantPoolBuilder#loadableConstantEntry(ConstantDesc)}
|
||||
* and {@link #constantValue()}.
|
||||
*
|
||||
* @see CodeBuilder#ldc(LoadableConstantEntry)
|
||||
* @jvms 4.4 The Constant Pool
|
||||
* @sealedGraph
|
||||
* @since 24
|
||||
*/
|
||||
|
@ -38,12 +47,19 @@ public sealed interface LoadableConstantEntry extends PoolEntry
|
|||
permits ClassEntry, ConstantDynamicEntry, ConstantValueEntry, MethodHandleEntry, MethodTypeEntry {
|
||||
|
||||
/**
|
||||
* {@return the constant described by this entry}
|
||||
* {@return a symbolic descriptor of this constant}
|
||||
*
|
||||
* @see ConstantPoolBuilder#loadableConstantEntry(ConstantDesc)
|
||||
*/
|
||||
ConstantDesc constantValue();
|
||||
|
||||
/**
|
||||
* {@return the type of the constant}
|
||||
* {@return the data type of this constant}
|
||||
* <p>
|
||||
* If the data type is of {@linkplain TypeKind#slotSize() category} 2, this
|
||||
* constant must be loaded with {@link Opcode#LDC2_W ldc2_w}; otherwise, the
|
||||
* data type is of category 1, and this constant must be loaded with {@link
|
||||
* Opcode#LDC ldc} or {@link Opcode#LDC_W ldc_w}.
|
||||
*/
|
||||
default TypeKind typeKind() {
|
||||
return TypeKind.REFERENCE;
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +29,18 @@ import java.lang.classfile.TypeKind;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Long_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.5 The CONSTANT_Long_info and CONSTANT_Double_info Structures
|
||||
* Models a {@code CONSTANT_Long_info} structure, or a {@code long} constant, in
|
||||
* the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code LongEntry} is modeled by a {@code long}. Conversions are
|
||||
* through {@link ConstantPoolBuilder#longEntry(long)} and {@link #longValue()}.
|
||||
* <p>
|
||||
* A long entry has a {@linkplain #width() width} of {@code 2}, making its
|
||||
* subsequent constant pool index valid and unusable.
|
||||
*
|
||||
* @see ConstantPoolBuilder#longEntry ConstantPoolBuilder::longEntry
|
||||
* @jvms 4.4.5 The {@code CONSTANT_Long_info} and {@code CONSTANT_Double_info}
|
||||
* Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface LongEntry
|
||||
|
@ -40,7 +48,10 @@ public sealed interface LongEntry
|
|||
permits AbstractPoolEntry.LongEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return the long value}
|
||||
* {@return the {@code long} value}
|
||||
*
|
||||
* @see ConstantPoolBuilder#longEntry(long)
|
||||
* ConstantPoolBuilder::longEntry(long)
|
||||
*/
|
||||
long longValue();
|
||||
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -24,24 +24,45 @@
|
|||
*/
|
||||
package java.lang.classfile.constantpool;
|
||||
|
||||
import java.lang.classfile.Opcode;
|
||||
|
||||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a member reference constant in the constant pool of a classfile,
|
||||
* which includes references to fields, methods, and interface methods.
|
||||
* Superinterface modeling symbolic references to a member of a class or interface
|
||||
* in the constant pool of a {@code class} file, which include references to
|
||||
* {@linkplain FieldRefEntry fields}, {@linkplain MethodRefEntry class methods},
|
||||
* and {@linkplain InterfaceMethodRefEntry interface methods}.
|
||||
* <p>
|
||||
* Different types of symbolic references to a member of a class or interface
|
||||
* bear structural similarities and share parts of the resolution processes, and
|
||||
* they can sometimes appear in the same locations. For example, both {@link
|
||||
* MethodRefEntry} and {@link InterfaceMethodRefEntry} can appear in an {@link
|
||||
* Opcode#INVOKESTATIC invokestatic} instruction.
|
||||
* <p>
|
||||
* A member reference entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* MemberRefEntry(
|
||||
* ClassEntry owner, // @link substring="owner" target="#owner()"
|
||||
* NameAndTypeEntry nameAndType // @link substring="nameAndType" target="#nameAndType()"
|
||||
* )
|
||||
* }
|
||||
*
|
||||
* @jvms 4.4.2 The {@code CONSTANT_Fieldref_info}, {@code
|
||||
* CONSTANT_Methodref_info}, and {@code
|
||||
* CONSTANT_InterfaceMethodref_info} Structures
|
||||
* @sealedGraph
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface MemberRefEntry extends PoolEntry
|
||||
permits FieldRefEntry, InterfaceMethodRefEntry, MethodRefEntry, AbstractPoolEntry.AbstractMemberRefEntry {
|
||||
/**
|
||||
* {@return the class in which this member ref lives}
|
||||
* {@return the class or interface which this member belongs to}
|
||||
*/
|
||||
ClassEntry owner();
|
||||
|
||||
/**
|
||||
* {@return the name and type of the member}
|
||||
* {@return the name and descriptor string of the member}
|
||||
*/
|
||||
NameAndTypeEntry nameAndType();
|
||||
|
||||
|
@ -53,7 +74,14 @@ public sealed interface MemberRefEntry extends PoolEntry
|
|||
}
|
||||
|
||||
/**
|
||||
* {@return the type of the member}
|
||||
* {@return the descriptor string of the member} This is a field descriptor
|
||||
* string if this entry is a {@link FieldRefEntry}, or a method descriptor
|
||||
* string if this entry is a {@link MethodRefEntry} or {@link
|
||||
* InterfaceMethodRefEntry}.
|
||||
*
|
||||
* @apiNote
|
||||
* Each subinterface defines a {@code typeSymbol()} accessor for the
|
||||
* symbolic descriptor for the member type.
|
||||
*/
|
||||
default Utf8Entry type() {
|
||||
return nameAndType().type();
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,13 +26,35 @@ package java.lang.classfile.constantpool;
|
|||
|
||||
import java.lang.constant.ConstantDesc;
|
||||
import java.lang.constant.DirectMethodHandleDesc;
|
||||
import java.lang.invoke.MethodHandle;
|
||||
import java.lang.invoke.MethodHandleInfo;
|
||||
|
||||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_MethodHandle_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.8 The CONSTANT_MethodHandle_info Structure
|
||||
* Models a {@code CONSTANT_MethodHandle_info} structure, or a symbolic
|
||||
* reference to a {@linkplain MethodHandle method handle}, in the constant pool
|
||||
* of a {@code class} file. The method handle directly accesses an accessible
|
||||
* method, field, or constructor.
|
||||
* <p>
|
||||
* The use of a {@code MethodHandleEntry} is modeled by a {@link
|
||||
* DirectMethodHandleDesc}. Conversions are through {@link
|
||||
* ConstantPoolBuilder#methodHandleEntry(DirectMethodHandleDesc)} and {@link
|
||||
* #asSymbol()}.
|
||||
* <p>
|
||||
* A method handle entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="MethodHandleEntry" target="ConstantPoolBuilder#methodHandleEntry(int, MemberRefEntry)" :
|
||||
* MethodHandleEntry(
|
||||
* int refKind, // @link substring="refKind" target="#kind()"
|
||||
* MemberRefEntry reference // @link substring="reference" target="#reference()"
|
||||
* )
|
||||
* }
|
||||
* where {@code refKind} is in the range {@code [1, 9]}.
|
||||
*
|
||||
* @see ConstantPoolBuilder#methodHandleEntry
|
||||
* ConstantPoolBuilder::methodHandleEntry
|
||||
* @jvms 4.4.8 The {@code CONSTANT_MethodHandle_info} Structure
|
||||
*
|
||||
* @since 24
|
||||
*/
|
||||
|
@ -40,6 +62,11 @@ public sealed interface MethodHandleEntry
|
|||
extends LoadableConstantEntry
|
||||
permits AbstractPoolEntry.MethodHandleEntryImpl {
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
* <p>
|
||||
* This is equivalent to {@link #asSymbol() asSymbol()}.
|
||||
*/
|
||||
@Override
|
||||
default ConstantDesc constantValue() {
|
||||
return asSymbol();
|
||||
|
@ -47,17 +74,22 @@ public sealed interface MethodHandleEntry
|
|||
|
||||
/**
|
||||
* {@return the reference kind of this method handle (JVMS {@jvms 4.4.8})}
|
||||
* @see java.lang.invoke.MethodHandleInfo
|
||||
*
|
||||
* @see MethodHandleInfo##refkinds Reference kinds
|
||||
*/
|
||||
int kind();
|
||||
|
||||
/**
|
||||
* {@return the constant pool entry describing the method}
|
||||
* {@return the constant pool entry describing the field or method,
|
||||
* according to the {@linkplain #kind() reference kind}}
|
||||
*/
|
||||
MemberRefEntry reference();
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for this method handle}
|
||||
*
|
||||
* @see ConstantPoolBuilder#methodHandleEntry(DirectMethodHandleDesc)
|
||||
* ConstantPoolBuilder::methodHandleEntry(DirectMethodHandleDesc)
|
||||
*/
|
||||
DirectMethodHandleDesc asSymbol();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -30,17 +30,31 @@ import jdk.internal.classfile.impl.AbstractPoolEntry;
|
|||
import jdk.internal.classfile.impl.Util;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_MethodRef_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.2 The CONSTANT_Fieldref_info, CONSTANT_Methodref_info, and CONSTANT_InterfaceMethodref_info Structures
|
||||
* Models a {@code CONSTANT_MethodRef_info} structure, or a symbolic reference
|
||||
* to a class method, in the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* A class method reference entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="MethodRefEntry" target="ConstantPoolBuilder#methodRefEntry(ClassEntry, NameAndTypeEntry)" :
|
||||
* MethodRefEntry(
|
||||
* ClassEntry owner, // @link substring="owner" target="#owner()"
|
||||
* NameAndTypeEntry nameAndType // @link substring="nameAndType" target="#nameAndType()"
|
||||
* )
|
||||
* }
|
||||
* where the type in the {@code NameAndTypeEntry} is a {@linkplain #typeSymbol()
|
||||
* method descriptor} string.
|
||||
*
|
||||
* @see ConstantPoolBuilder#methodRefEntry ConstantPoolBuilder::methodRefEntry
|
||||
* @jvms 4.4.2 The {@code CONSTANT_Fieldref_info}, {@code
|
||||
* CONSTANT_Methodref_info}, and {@code
|
||||
* CONSTANT_InterfaceMethodref_info} Structures
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface MethodRefEntry extends MemberRefEntry
|
||||
permits AbstractPoolEntry.MethodRefEntryImpl {
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the method's type}
|
||||
* {@return a symbolic descriptor for the {@linkplain #type() method type}}
|
||||
*/
|
||||
default MethodTypeDesc typeSymbol() {
|
||||
return Util.methodTypeSymbol(type());
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -30,28 +30,46 @@ import java.lang.constant.MethodTypeDesc;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_MethodType_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.9 The CONSTANT_MethodType_info Structure
|
||||
* Models a {@code CONSTANT_MethodType_info} structure, or a symbolic reference
|
||||
* to a method type, in the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code MethodTypeEntry} is modeled by a {@link MethodTypeDesc}.
|
||||
* Conversions are through {@link ConstantPoolBuilder#methodTypeEntry(MethodTypeDesc)}
|
||||
* and {@link #asSymbol()}.
|
||||
* <p>
|
||||
* A method type entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="MethodTypeEntry" target="ConstantPoolBuilder#methodTypeEntry(Utf8Entry)" :
|
||||
* MethodTypeEntry(Utf8Entry descriptor) // @link substring="descriptor" target="#descriptor()"
|
||||
* }
|
||||
* where {@code descriptor} is a {@linkplain #asSymbol() method descriptor}
|
||||
* string.
|
||||
*
|
||||
* @jvms 4.4.9 The {@code CONSTANT_MethodType_info} Structure
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface MethodTypeEntry
|
||||
extends LoadableConstantEntry
|
||||
permits AbstractPoolEntry.MethodTypeEntryImpl {
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
* <p>
|
||||
* This is equivalent to {@link #asSymbol() asSymbol()}.
|
||||
*/
|
||||
@Override
|
||||
default ConstantDesc constantValue() {
|
||||
return asSymbol();
|
||||
}
|
||||
|
||||
/**
|
||||
* {@return the constant pool entry describing the method type}
|
||||
* {@return the {@linkplain #asSymbol() method descriptor} string}
|
||||
*/
|
||||
Utf8Entry descriptor();
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the method type}
|
||||
* {@return a symbolic descriptor for the {@linkplain #descriptor() method
|
||||
* type}}
|
||||
*/
|
||||
MethodTypeDesc asSymbol();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,21 +29,32 @@ import java.lang.constant.ModuleDesc;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Module_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.11 The CONSTANT_Module_info Structure
|
||||
* Models a {@code CONSTANT_Module_info} structure, denoting a module, in the
|
||||
* constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code ModuleEntry} is modeled by a {@link ModuleDesc}.
|
||||
* Conversions are through {@link ConstantPoolBuilder#moduleEntry(ModuleDesc)}
|
||||
* and {@link #asSymbol()}.
|
||||
* <p>
|
||||
* A module entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="ModuleEntry" target="ConstantPoolBuilder#moduleEntry(Utf8Entry)" :
|
||||
* ModuleEntry(Utf8Entry name) // @link substring="name" target="#name()"
|
||||
* }
|
||||
* where {@code name} is a {@linkplain #asSymbol() module name}.
|
||||
*
|
||||
* @jvms 4.4.11 The {@code CONSTANT_Module_info} Structure
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface ModuleEntry extends PoolEntry
|
||||
permits AbstractPoolEntry.ModuleEntryImpl {
|
||||
/**
|
||||
* {@return the name of the module}
|
||||
* {@return the name of the {@linkplain #asSymbol() module}}
|
||||
*/
|
||||
Utf8Entry name();
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the module}
|
||||
* {@return a symbolic descriptor for the {@linkplain #name() module name}}
|
||||
*/
|
||||
ModuleDesc asSymbol();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -24,13 +24,36 @@
|
|||
*/
|
||||
package java.lang.classfile.constantpool;
|
||||
|
||||
import java.lang.constant.ClassDesc;
|
||||
import java.lang.constant.MethodTypeDesc;
|
||||
import java.lang.invoke.TypeDescriptor;
|
||||
|
||||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_NameAndType_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.6 The CONSTANT_NameAndType_info Structure
|
||||
* Models a {@code CONSTANT_NameAndType_info} structure, representing a field or
|
||||
* method, in the constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code NameAndTypeEntry} is symbolically represented as a
|
||||
* {@code String name}, and a {@link ConstantPoolBuilder#nameAndTypeEntry(String,
|
||||
* ClassDesc) ClassDesc} or a {@link ConstantPoolBuilder#nameAndTypeEntry(String,
|
||||
* MethodTypeDesc) MethodTypeDesc} {@code type}, depending on where this {@code
|
||||
* NameAndTypeEntry} appears. The accessors to the symbolic descriptors for the
|
||||
* {@code type} is defined on a per-use-site basis, such as {@link
|
||||
* FieldRefEntry#typeSymbol()} returning a {@code ClassDesc}, and {@link
|
||||
* MethodRefEntry#typeSymbol()} returning a {@code MethodTypeDesc}.
|
||||
* <p>
|
||||
* A name and type entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* NameAndTypeEntry( // @link substring="NameAndTypeEntry" target="ConstantPoolBuilder#nameAndTypeEntry(Utf8Entry, Utf8Entry)"
|
||||
* Utf8Entry name, // @link substring="name" target="#name()"
|
||||
* Utf8Entry type // @link substring="type" target="#type()"
|
||||
* )
|
||||
* }
|
||||
* where {@code name} is an unqualified name, and {@code type} is a field or
|
||||
* method descriptor string.
|
||||
*
|
||||
* @jvms 4.4.6 The {@code CONSTANT_NameAndType_info} Structure
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface NameAndTypeEntry extends PoolEntry
|
||||
|
@ -42,7 +65,10 @@ public sealed interface NameAndTypeEntry extends PoolEntry
|
|||
Utf8Entry name();
|
||||
|
||||
/**
|
||||
* {@return the field or method descriptor}
|
||||
* {@return the field or method {@linkplain TypeDescriptor descriptor}
|
||||
* string} It is a method descriptor strings if it starts with {@code (}.
|
||||
* Otherwise, it is a field descriptor string, and must start with one of
|
||||
* the {@code BCDFIJSZL[} characters.
|
||||
*/
|
||||
Utf8Entry type();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,21 +29,35 @@ import java.lang.constant.PackageDesc;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_Package_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.12 The CONSTANT_Package_info Structure
|
||||
* Models a {@code CONSTANT_Package_info}, representing a package, in the
|
||||
* constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code PackageEntry} is represented by a {@link PackageDesc}
|
||||
* that does not represent the unnamed package. Conversions are through
|
||||
* {@link ConstantPoolBuilder#packageEntry(PackageDesc)} and
|
||||
* {@link #asSymbol()}.
|
||||
* <p>
|
||||
* A package entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="PackageEntry" target="ConstantPoolBuilder#packageEntry(Utf8Entry)" :
|
||||
* PackageEntry(Utf8Entry name) // @link substring="name" target="#name()"
|
||||
* }
|
||||
* where {@code name} is the {@linkplain ClassEntry##internalname internal form}
|
||||
* of a binary package name and is not empty.
|
||||
*
|
||||
* @jvms 4.4.12 The {@code CONSTANT_Package_info} Structure
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface PackageEntry extends PoolEntry
|
||||
permits AbstractPoolEntry.PackageEntryImpl {
|
||||
/**
|
||||
* {@return the package name}
|
||||
* {@return the {@linkplain ClassEntry##internalname internal form} of the
|
||||
* {@linkplain #asSymbol() package} name}
|
||||
*/
|
||||
Utf8Entry name();
|
||||
|
||||
/**
|
||||
* {@return a symbolic descriptor for the package name}
|
||||
* {@return a symbolic descriptor for the {@linkplain #name() package name}}
|
||||
*/
|
||||
PackageDesc asSymbol();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -24,9 +24,28 @@
|
|||
*/
|
||||
package java.lang.classfile.constantpool;
|
||||
|
||||
import java.lang.classfile.Attribute;
|
||||
import java.lang.classfile.ClassFileBuilder;
|
||||
import java.lang.classfile.Opcode;
|
||||
import java.lang.classfile.TypeKind;
|
||||
|
||||
/**
|
||||
* Models an entry in the constant pool of a classfile.
|
||||
* Models an entry in the constant pool of a {@code class} file. Entries are
|
||||
* read from {@code class} files, and can be created with a {@link
|
||||
* ConstantPoolBuilder} to write to {@code class} files.
|
||||
*
|
||||
* @implNote
|
||||
* <h2 id="unbound">Unbound Constant Pool Entries</h2>
|
||||
* Implementations may create unbound constant pool entries not belonging to
|
||||
* an actual constant pool. They conveniently represent constant pool entries
|
||||
* referred by unbound {@linkplain Attribute attributes} not read from a {@code
|
||||
* class} file. Their {@link #index() index()} return a non-positive invalid
|
||||
* value, and behaviors of their {@link #constantPool() constantPool()} are
|
||||
* unspecified. They are considered alien to any {@linkplain
|
||||
* ClassFileBuilder#constantPool() contextual constant pool} and will be
|
||||
* converted when they are written to {@code class} files.
|
||||
*
|
||||
* @see ConstantPoolBuilder##alien Alien Constant Pool Entries
|
||||
* @sealedGraph
|
||||
* @since 24
|
||||
*/
|
||||
|
@ -88,6 +107,14 @@ public sealed interface PoolEntry
|
|||
|
||||
/**
|
||||
* {@return the constant pool this entry is from}
|
||||
*
|
||||
* @apiNote
|
||||
* Given a {@link ConstantPoolBuilder} {@code builder} and a {@code
|
||||
* PoolEntry entry}, use {@link ConstantPoolBuilder#canWriteDirect
|
||||
* builder.canWriteDirect(entry.constantPool())} instead of object equality
|
||||
* of the constant pool to determine if an entry belongs to the builder.
|
||||
*
|
||||
* @see ##unbound Unbound Constant Pool Entries
|
||||
*/
|
||||
ConstantPool constantPool();
|
||||
|
||||
|
@ -102,11 +129,32 @@ public sealed interface PoolEntry
|
|||
|
||||
/**
|
||||
* {@return the index within the constant pool corresponding to this entry}
|
||||
* A valid index is always positive; if the index is non-positive, this
|
||||
* entry is {@linkplain ##unbound unbound}.
|
||||
*
|
||||
* @see ##unbound Unbound Constant Pool Entries
|
||||
*/
|
||||
int index();
|
||||
|
||||
/**
|
||||
* {@return the number of constant pool slots this entry consumes}
|
||||
* <p>
|
||||
* All pool entries except {@link LongEntry CONSTANT_Long} and {@link
|
||||
* DoubleEntry CONSTANT_Double} have width {@code 1}. These two exceptions
|
||||
* have width {@code 2}, and their subsequent indices at {@link #index()
|
||||
* index() + 1} are considered unusable.
|
||||
*
|
||||
* @apiNote
|
||||
* If this entry is {@linkplain LoadableConstantEntry loadable}, the width
|
||||
* of this entry does not decide if this entry should be loaded with {@link
|
||||
* Opcode#LDC ldc} or {@link Opcode#LDC2_W ldc2_w}. For example, {@link
|
||||
* ConstantDynamicEntry} always has width {@code 1}, but it must be loaded
|
||||
* with {@code ldc2_w} if its {@linkplain ConstantDynamicEntry#typeKind()
|
||||
* type} is {@link TypeKind#LONG long} or {@link TypeKind#DOUBLE double}.
|
||||
* Use {@link LoadableConstantEntry#typeKind() typeKind().slotSize()} to
|
||||
* determine the loading instruction instead.
|
||||
*
|
||||
* @see ConstantPool##index Index in the Constant Pool
|
||||
*/
|
||||
int width();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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,10 +27,20 @@ package java.lang.classfile.constantpool;
|
|||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_String_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.3 The CONSTANT_String_info Structure
|
||||
* Models a {@code CONSTANT_String_info} structure, or a string constant, in the
|
||||
* constant pool of a {@code class} file.
|
||||
* <p>
|
||||
* The use of a {@code StringEntry} is represented by a {@link String}.
|
||||
* Conversions are through {@link ConstantPoolBuilder#stringEntry(String)} and
|
||||
* {@link #stringValue()}.
|
||||
* <p>
|
||||
* A string entry is composite:
|
||||
* {@snippet lang=text :
|
||||
* // @link substring="StringEntry" target="ConstantPoolBuilder#stringEntry(Utf8Entry)" :
|
||||
* StringEntry(Utf8Entry utf8) // @link substring="utf8" target="#utf8()"
|
||||
* }
|
||||
*
|
||||
* @jvms 4.4.3 The {@code CONSTANT_String_info} Structure
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface StringEntry
|
||||
|
@ -38,11 +48,15 @@ public sealed interface StringEntry
|
|||
permits AbstractPoolEntry.StringEntryImpl {
|
||||
/**
|
||||
* {@return the UTF constant pool entry describing the string contents}
|
||||
*
|
||||
* @see ConstantPoolBuilder#stringEntry(Utf8Entry)
|
||||
*/
|
||||
Utf8Entry utf8();
|
||||
|
||||
/**
|
||||
* {@return the string value for this entry}
|
||||
*
|
||||
* @see ConstantPoolBuilder#stringEntry(String)
|
||||
*/
|
||||
String stringValue();
|
||||
}
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2022, 2025, 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
|
||||
|
@ -24,13 +24,40 @@
|
|||
*/
|
||||
package java.lang.classfile.constantpool;
|
||||
|
||||
import java.io.DataInput;
|
||||
import java.lang.classfile.AnnotationValue;
|
||||
import java.lang.classfile.MethodModel;
|
||||
import java.lang.constant.ClassDesc;
|
||||
import java.lang.constant.MethodTypeDesc;
|
||||
import java.lang.invoke.TypeDescriptor;
|
||||
|
||||
import jdk.internal.classfile.impl.AbstractPoolEntry;
|
||||
|
||||
/**
|
||||
* Models a {@code CONSTANT_UTF8_info} constant in the constant pool of a
|
||||
* classfile.
|
||||
* @jvms 4.4.7 The CONSTANT_Utf8_info Structure
|
||||
* Models a {@code CONSTANT_UTF8_info} constant, representing strings, in the
|
||||
* constant pool of a {@code class} file. This describes strings in the
|
||||
* {@linkplain DataInput##modified-utf-8 Modified UTF-8} format.
|
||||
* <p>
|
||||
* The use of a {@code Utf8Entry} is represented by a {@link String}.
|
||||
* Conversions are through {@link ConstantPoolBuilder#utf8Entry(String)} and
|
||||
* {@link #stringValue()}.
|
||||
* <p>
|
||||
* Some uses of {@code Utf8Entry} represent field or method {@linkplain
|
||||
* TypeDescriptor#descriptorString() descriptor strings}, symbolically
|
||||
* represented as {@link ClassDesc} or {@link MethodTypeDesc}, depending on
|
||||
* where a {@code Utf8Entry} appear. Entries representing such uses are created
|
||||
* with {@link ConstantPoolBuilder#utf8Entry(ClassDesc)} and {@link
|
||||
* ConstantPoolBuilder#utf8Entry(MethodTypeDesc)}, and they can be converted to
|
||||
* symbolic descriptors on a per-use-site basis, such as in {@link
|
||||
* AnnotationValue.OfClass#classSymbol()} and {@link MethodModel#methodTypeSymbol()}.
|
||||
* <p>
|
||||
* Unlike most constant pool entries, a UTF-8 entry is of flexible length: it is
|
||||
* represented as an array structure, with an {@code u2} for the data length in
|
||||
* bytes, followed by that number of bytes of Modified UTF-8 data. It can
|
||||
* represent at most 65535 bytes of data due to the physical restrictions.
|
||||
*
|
||||
* @jvms 4.4.7 The {@code CONSTANT_Utf8_info} Structure
|
||||
* @see DataInput##modified-utf-8 Modified UTF-8
|
||||
* @since 24
|
||||
*/
|
||||
public sealed interface Utf8Entry
|
||||
|
@ -39,6 +66,15 @@ public sealed interface Utf8Entry
|
|||
|
||||
/**
|
||||
* {@return the string value for this entry}
|
||||
*
|
||||
* @apiNote
|
||||
* A {@code Utf8Entry} can be used directly as a {@link CharSequence} if
|
||||
* {@code String} functionalities are not strictly desired. If only string
|
||||
* equivalence is desired, {@link #equalsString(String) equalsString} should
|
||||
* be used. Reduction of string processing can significantly improve {@code
|
||||
* class} file reading performance.
|
||||
*
|
||||
* @see ConstantPoolBuilder#utf8Entry(String)
|
||||
*/
|
||||
String stringValue();
|
||||
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2023, 2025, 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
|
||||
|
@ -24,11 +24,59 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* <h2>Provides interfaces describing classfile constant pool entries for the {@link java.lang.classfile} library.</h2>
|
||||
* <h2>Provides interfaces describing constant pool entries for the {@link java.lang.classfile} library.</h2>
|
||||
*
|
||||
* The {@code java.lang.classfile.constantpool} package contains interfaces describing classfile constant pool entries.
|
||||
* The {@code java.lang.classfile.constantpool} package contains interfaces describing constant pool entries in the
|
||||
* {@code class} file format. Constant pool entries are low-level models to faithfully represent the exact structure
|
||||
* of a {@code class} file.
|
||||
* <p>
|
||||
* Unless otherwise specified, passing {@code null} or an array or collection containing a {@code null} element as an
|
||||
* argument to a constructor or method of any Class-File API class or interface will cause a {@link NullPointerException}
|
||||
* to be thrown.
|
||||
*
|
||||
* <h2 id="reading">Reading the constant pool entries</h2>
|
||||
* When read from {@code class} files, the pool entries are lazily inflated; the contents of these entries, besides the
|
||||
* bare structure, are not evaluated to speed up parsing. Entries to users interest, usually accessed from other models
|
||||
* and elements, have their contents read on demand. For example, to search for methods, a user should filter first by
|
||||
* access flags and then by method name, and use {@link Utf8Entry#equalsString(String)} instead of checking equality
|
||||
* against {@link Utf8Entry#stringValue()}. This avoids inflation of UTF-8 entries as much as possible:
|
||||
* {@snippet lang="java" class="PackageSnippets" region="isStaticWorkMethod"}
|
||||
* <p>
|
||||
* The entries also define accessors to validated symbolic information with nominal descriptor abstractions from the
|
||||
* {@link java.lang.constant} package. These symbolic information accessors perform validation against the read
|
||||
* {@code class} files, and throw {@link IllegalArgumentException} when the accessed constant pool entry contains
|
||||
* invalid data. The nominal descriptors represent validated data, which saves users from extra validations in future
|
||||
* processing.
|
||||
* <p>
|
||||
* Due to the lazy nature of {@code class} file parsing, {@link IllegalArgumentException} indicating malformed
|
||||
* {@code class} file data can be thrown at any method invocation. For example, an exception may come from a {@link
|
||||
* ClassEntry} when it is first read from the constant pool (referring to an invalid index or wrong type of entry), when
|
||||
* its referred UTF-8 entry is expanded (malformed UTF-8 data), or when its symbolic information is accessed (the string
|
||||
* is not valid for a class entry).
|
||||
*
|
||||
* <h2 id="writing">Writing the constant pool entries</h2>
|
||||
* In general, users do not need to worry about working with the constant pool and its entries when writing {@code
|
||||
* class} files. Most Class-File API models and elements have two sets of factory methods: one that accepts symbolic
|
||||
* information representing the uses, and another that accepts constant pool entries. The constant pool builder
|
||||
* associated with {@code class} file builders, {@link ClassFileBuilder#constantPool}, automatically creates or reuses
|
||||
* pool entries from the symbolic information. Validated data in symbolic information helps {@code class} file
|
||||
* generation by avoiding extraneous parsing of raw constant pool entry data.
|
||||
* <p>
|
||||
* As always, users can use factories that accept constant pool entries if they already have them by hand, or if they
|
||||
* desire fine-grained control over {@code class} file generation.
|
||||
* <p>
|
||||
* If many models and elements are reused from another {@link ClassModel} in class building, the class building process
|
||||
* can use a constant pool builder that extends from the given {@code ClassModel}, available through {@link
|
||||
* ConstantPoolBuilder#of(ClassModel) ConstantPoolBuilder::of(ClassModel)}, so that byte data with constant pool
|
||||
* references can be copied in batch, speeding up class building. This is especially applicable to class transformations,
|
||||
* and {@link ClassFile.ConstantPoolSharingOption ConstantPoolSharingOption} exists to control this behavior.
|
||||
*
|
||||
* @jvms 4.4 The Constant Pool
|
||||
* @since 24
|
||||
*/
|
||||
package java.lang.classfile.constantpool;
|
||||
|
||||
import java.lang.classfile.ClassFile;
|
||||
import java.lang.classfile.ClassFileBuilder;
|
||||
import java.lang.classfile.ClassModel;
|
||||
import java.lang.classfile.MethodModel;
|
||||
|
|
|
@ -0,0 +1,43 @@
|
|||
/*
|
||||
* Copyright (c) 2025, 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 java.lang.classfile.constantpool.snippet;
|
||||
|
||||
import java.lang.classfile.ClassFile;
|
||||
import java.lang.classfile.MethodModel;
|
||||
import java.lang.classfile.constantpool.Utf8Entry;
|
||||
|
||||
class PackageSnippets {
|
||||
|
||||
// @start region=isStaticWorkMethod
|
||||
boolean isStaticWorkMethod(MethodModel method) {
|
||||
// check static flag first to avoid unnecessary evaluation of UTF-8 entry
|
||||
return (method.flags().flagsMask() & ClassFile.ACC_STATIC) != 0
|
||||
// use equalsString to avoid full conversion to String for comparison
|
||||
// the Utf8Entry can also act as a basic CharSequence without full conversion
|
||||
// @link substring="methodName" target="MethodModel#methodName" :
|
||||
&& method.methodName().equalsString("work"); // @link substring="equalsString" target="Utf8Entry#equalsString"
|
||||
}
|
||||
// @end
|
||||
}
|
Loading…
Add table
Add a link
Reference in a new issue