/*
 * 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
 * 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.
 */

/**
 * <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 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;