io.github.dmlloyd.classfile.components.package-info Maven / Gradle / Ivy
/*
* Copyright (c) 2022, 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.
*/
/**
* Provides specific components, transformations, and tools built on top of the
* {@link io.github.dmlloyd.classfile} library.
*
* The {@code jdk.internal.classfile.components} package contains specific
* transformation components and utility classes helping to compose very complex
* tasks with minimal effort.
*
* {@link ClassPrinter}
*
* {@link ClassPrinter} is a helper class providing seamless export of a {@link
* io.github.dmlloyd.classfile.ClassModel}, {@link io.github.dmlloyd.classfile.FieldModel},
* {@link io.github.dmlloyd.classfile.MethodModel}, or {@link
* io.github.dmlloyd.classfile.CodeModel} into human-readable structured text in
* JSON, XML, or YAML format, or into a tree of traversable and printable nodes.
*
* Primary purpose of {@link ClassPrinter} is to provide human-readable class
* info for debugging, exception handling and logging purposes. The printed
* class also conforms to a standard format to support automated offline
* processing.
*
* The most frequent use case is to simply print a class:
* {@snippet lang="java" class="PackageSnippets" region="printClass"}
*
* {@link ClassPrinter} allows to traverse tree of simple printable nodes to
* hook custom printer:
* {@snippet lang="java" class="PackageSnippets" region="customPrint"}
*
* Another use case for {@link ClassPrinter} is to simplify writing of automated
* tests:
* {@snippet lang="java" class="PackageSnippets" region="printNodesInTest"}
*
*
{@link ClassRemapper}
* ClassRemapper is a {@link io.github.dmlloyd.classfile.ClassTransform}, {@link
* io.github.dmlloyd.classfile.FieldTransform}, {@link
* io.github.dmlloyd.classfile.MethodTransform} and {@link
* io.github.dmlloyd.classfile.CodeTransform} deeply re-mapping all class references
* in any form, according to given map or map function.
*
* The re-mapping is applied to superclass, interfaces, all kinds of descriptors
* and signatures, all attributes referencing classes in any form (including all
* types of annotations), and to all instructions referencing to classes.
*
* Primitive types and arrays are never subjects of mapping and are not allowed
* targets of mapping.
*
* Arrays of reference types are always decomposed, mapped as the base reference
* types and composed back to arrays.
*
* Single class remapping example:
* {@snippet lang="java" class="PackageSnippets" region="singleClassRemap"}
*
* Remapping of all classes under specific package:
* {@snippet lang="java" class="PackageSnippets" region="allPackageRemap"}
*
*
{@link CodeLocalsShifter}
* {@link CodeLocalsShifter} is a {@link io.github.dmlloyd.classfile.CodeTransform}
* shifting locals to newly allocated positions to avoid conflicts during code
* injection. Locals pointing to the receiver or to method arguments slots are
* never shifted. All locals pointing beyond the method arguments are re-indexed
* in order of appearance.
*
* Sample of code transformation shifting all locals in all methods:
* {@snippet lang="java" class="PackageSnippets" region="codeLocalsShifting"}
*
*
{@link CodeRelabeler}
* {@link CodeRelabeler} is a {@link io.github.dmlloyd.classfile.CodeTransform}
* replacing all occurrences of {@link io.github.dmlloyd.classfile.Label} in the
* transformed code with new instances.
* All {@link io.github.dmlloyd.classfile.instruction.LabelTarget} instructions are
* adjusted accordingly.
* Relabeled code graph is identical to the original.
*
* Primary purpose of {@link CodeRelabeler} is for repeated injections of the
* same code blocks.
* Repeated injection of the same code block must be relabeled, so each instance
* of {@link io.github.dmlloyd.classfile.Label} is bound in the target bytecode
* exactly once.
*
* Sample transformation relabeling all methods:
* {@snippet lang="java" class="PackageSnippets" region="codeRelabeling"}
*
*
Class Instrumentation Sample
* Following snippet is sample composition of {@link ClassRemapper}, {@link
* CodeLocalsShifter} and {@link CodeRelabeler} into fully functional class
* instrumenting transformation:
* {@snippet lang="java" class="PackageSnippets" region="classInstrumentation"}
*
* @since 22
*/
@PreviewFeature(feature = PreviewFeature.Feature.CLASSFILE_API)
package io.github.dmlloyd.classfile.components;
import io.github.dmlloyd.classfile.extras.PreviewFeature;