/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.bcel.classfile;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.DataInput;
import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.util.Arrays;
import org.apache.bcel.util.Args;
/**
* Represents one type annotation of a {@link TypeAnnotations} attribute (JVMS 4.7.20): an annotation, the kind of program element it applies to
* (the target type and its target info), and the path to the annotated type inside that element.
*
* @see <a href="https://docs.oracle.com/javase/specs/jvms/se21/html/jvms-4.html#jvms-4.7.20">JVMS 4.7.20 The RuntimeVisibleTypeAnnotations attribute</a>
* @since 6.14.0
*/
public class TypeAnnotationEntry {
/** Target type: type parameter declaration of a generic class or interface. */
public static final int TARGET_CLASS_TYPE_PARAMETER = 0x00;
/** Target type: type parameter declaration of a generic method or constructor. */
public static final int TARGET_METHOD_TYPE_PARAMETER = 0x01;
/** Target type: type in an extends or implements clause of a class or interface declaration. */
public static final int TARGET_CLASS_EXTENDS = 0x10;
/** Target type: bound of a type parameter of a generic class or interface. */
public static final int TARGET_CLASS_TYPE_PARAMETER_BOUND = 0x11;
/** Target type: bound of a type parameter of a generic method or constructor. */
public static final int TARGET_METHOD_TYPE_PARAMETER_BOUND = 0x12;
/** Target type: type in a field or record component declaration. */
public static final int TARGET_FIELD = 0x13;
/** Target type: return type of a method, or type of a newly constructed object. */
public static final int TARGET_METHOD_RETURN = 0x14;
/** Target type: receiver type of a method or constructor. */
public static final int TARGET_METHOD_RECEIVER = 0x15;
/** Target type: type in a formal parameter declaration of a method, constructor, or lambda expression. */
public static final int TARGET_METHOD_FORMAL_PARAMETER = 0x16;
/** Target type: type in a throws clause of a method or constructor. */
public static final int TARGET_THROWS = 0x17;
/** Target type: type in a local variable declaration. */
public static final int TARGET_LOCAL_VARIABLE = 0x40;
/** Target type: type in a resource variable declaration. */
public static final int TARGET_RESOURCE_VARIABLE = 0x41;
/** Target type: type in an exception parameter declaration. */
public static final int TARGET_EXCEPTION_PARAMETER = 0x42;
/** Target type: type in an instanceof expression. */
public static final int TARGET_INSTANCEOF = 0x43;
/** Target type: type in a new expression. */
public static final int TARGET_NEW = 0x44;
/** Target type: type in a method reference expression using ::new. */
public static final int TARGET_CONSTRUCTOR_REFERENCE = 0x45;
/** Target type: type in a method reference expression using ::Identifier. */
public static final int TARGET_METHOD_REFERENCE = 0x46;
/** Target type: type in a cast expression. */
public static final int TARGET_CAST = 0x47;
/** Target type: type argument for a generic constructor in a new expression or an explicit constructor invocation. */
public static final int TARGET_CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT = 0x48;
/** Target type: type argument for a generic method in a method invocation expression. */
public static final int TARGET_METHOD_INVOCATION_TYPE_ARGUMENT = 0x49;
/** Target type: type argument for a generic constructor in a method reference expression using ::new. */
public static final int TARGET_CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT = 0x4A;
/** Target type: type argument for a generic method in a method reference expression using ::Identifier. */
public static final int TARGET_METHOD_REFERENCE_TYPE_ARGUMENT = 0x4B;
/**
* Empty array of TypeAnnotationEntry objects.
*/
public static final TypeAnnotationEntry[] EMPTY_ARRAY = {};
/** Maximum number of steps of a type path, which its length of one byte limits. */
private static final int MAX_TYPE_PATH_LENGTH = 255;
/** Number of bytes of a {@code localvar_target} entry: start_pc, length and index. */
private static final int LOCAL_VARIABLE_RANGE_SIZE = 6;
private static void checkTargetInfo(final int targetType, final byte[] targetInfo) {
final int size = targetInfoSize(targetType); if (size >= 0) { if (targetInfo.length != size) { throw new IllegalArgumentException("The target info of the target type 0x" + Integer.toHexString(targetType) + " must have " + size
+ " bytes, not " + targetInfo.length);
}
} else if (targetInfo.length < 2 || targetInfo.length != 2 + ((targetInfo[0] & 0xFF) << 8 | targetInfo[1] & 0xFF) * LOCAL_VARIABLE_RANGE_SIZE) { throw new IllegalArgumentException("The target info of the target type 0x" + Integer.toHexString(targetType)
+ " must be a length followed by that many ranges of 6 bytes");
}
}
/**
* Factory method to create a TypeAnnotationEntry from a DataInput.
*
* @param input The input stream.
* @param constantPool The constant pool.
* @param isRuntimeVisible whether the annotation is runtime visible.
* @return The entry.
* @throws IOException Thrown if an I/O error occurs.
*/
public static TypeAnnotationEntry read(final DataInput input, final ConstantPool constantPool, final boolean isRuntimeVisible) throws IOException {
final int targetType = input.readUnsignedByte(); final int size = targetInfoSize(targetType);
final byte[] targetInfo;
if (size >= 0) { targetInfo = new byte[size]; input.readFully(targetInfo);
} else {
final int tableLength = input.readUnsignedShort(); targetInfo = new byte[2 + tableLength * LOCAL_VARIABLE_RANGE_SIZE]; targetInfo[0] = (byte) (tableLength >>> 8); targetInfo[1] = (byte) tableLength; input.readFully(targetInfo, 2, targetInfo.length - 2);
}
final byte[] typePath = new byte[input.readUnsignedByte() * 2]; input.readFully(typePath); return new TypeAnnotationEntry(targetType, targetInfo, typePath, AnnotationEntry.read(input, constantPool, isRuntimeVisible));
}
/**
* Gets the number of bytes of the target info that follows a target type.
*
* @param targetType The target type.
* @return the size of the target info, or -1 if it depends on its content (the table of a {@code localvar_target}).
* @throws ClassFormatException Thrown if the target type is not defined.
*/
private static int targetInfoSize(final int targetType) {
switch (targetType) {
case TARGET_CLASS_TYPE_PARAMETER:
case TARGET_METHOD_TYPE_PARAMETER:
case TARGET_METHOD_FORMAL_PARAMETER:
return 1;
case TARGET_CLASS_EXTENDS:
case TARGET_CLASS_TYPE_PARAMETER_BOUND:
case TARGET_METHOD_TYPE_PARAMETER_BOUND:
case TARGET_THROWS:
case TARGET_EXCEPTION_PARAMETER:
case TARGET_INSTANCEOF:
case TARGET_NEW:
case TARGET_CONSTRUCTOR_REFERENCE:
case TARGET_METHOD_REFERENCE:
return 2;
case TARGET_FIELD:
case TARGET_METHOD_RETURN:
case TARGET_METHOD_RECEIVER:
return 0;
case TARGET_LOCAL_VARIABLE:
case TARGET_RESOURCE_VARIABLE:
return -1;
case TARGET_CAST:
case TARGET_CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT:
case TARGET_METHOD_INVOCATION_TYPE_ARGUMENT:
case TARGET_CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT:
case TARGET_METHOD_REFERENCE_TYPE_ARGUMENT:
return 3;
default:
throw new ClassFormatException("Invalid type annotation target type: 0x" + Integer.toHexString(targetType));
}
}
private final int targetType;
private final byte[] targetInfo;
private final byte[] typePath;
private final AnnotationEntry annotationEntry;
/**
* Constructs a TypeAnnotationEntry.
*
* @param targetType The target type, one of the {@code TARGET_*} constants.
* @param targetInfo The target info, as it is stored in the class file.
* @param typePath The type path, as it is stored in the class file without its length: a pair of bytes (path kind, type argument index) per step.
* @param annotationEntry The annotation.
* @throws ClassFormatException Thrown if the target type is not defined.
* @throws IllegalArgumentException Thrown if the target info does not have the size its target type requires, or if the type path is not a sequence of pairs
* of bytes of at most 255 steps.
*/
public TypeAnnotationEntry(final int targetType, final byte[] targetInfo, final byte[] typePath, final AnnotationEntry annotationEntry) { checkTargetInfo(targetType, targetInfo); if (typePath.length % 2 != 0 || typePath.length > MAX_TYPE_PATH_LENGTH * 2) { throw new IllegalArgumentException("The type path must be at most " + MAX_TYPE_PATH_LENGTH + " pairs of bytes (kind, argument index), not "
+ typePath.length + " bytes");
}
this.targetType = targetType; this.targetInfo = targetInfo.clone(); this.typePath = typePath.clone(); this.annotationEntry = annotationEntry; }
/**
* Creates a deep copy of this entry, whose annotation is independent of this one and refers to the given constant pool. The indexes it holds are kept, as they
* are in {@link Attribute#copy(ConstantPool)}: the constant pool must have the same constants as the one of this entry at these indexes.
*
* @param constantPool The constant pool of the copy.
* @return A deep copy of this entry.
*/
public TypeAnnotationEntry copy(final ConstantPool constantPool) {
final ByteArrayOutputStream out = new ByteArrayOutputStream();
try {
try (DataOutputStream dos = new DataOutputStream(out)) { dump(dos);
}
return read(new DataInputStream(new ByteArrayInputStream(out.toByteArray())), constantPool, annotationEntry.isRuntimeVisible()); } catch (final IOException e) { throw new UncheckedIOException(e);
}
}
/**
* Writes this entry to a DataOutputStream.
*
* @param dos The data output stream.
* @throws IOException Thrown if an I/O error occurs.
*/
public void dump(final DataOutputStream dos) throws IOException {
dos.writeByte(targetType); dos.write(targetInfo); dos.writeByte(Args.requireU1(typePath.length / 2, "typePath.length")); dos.write(typePath); annotationEntry.dump(dos); }
/**
* Gets the annotation.
*
* @return The annotation.
*/
public AnnotationEntry getAnnotationEntry() {
return annotationEntry;
}
/**
* Gets the target info, which depends on the target type (JVMS table 4.7.20-A): for instance the index of the type parameter for
* {@link #TARGET_CLASS_TYPE_PARAMETER}, the index of the type parameter then the index of the bound for {@link #TARGET_CLASS_TYPE_PARAMETER_BOUND}, or the
* index of the parameter for {@link #TARGET_METHOD_FORMAL_PARAMETER}.
*
* @return A copy of the target info, as it is stored in the class file.
*/
public byte[] getTargetInfo() {
return targetInfo.clone();
}
/**
* Gets the kind of program element the annotation applies to.
*
* @return One of the {@code TARGET_*} constants.
*/
public int getTargetType() {
return targetType;
}
/**
* Gets the index of the type argument for a step of the type path of kind 3, else 0.
*
* @param step Index of the step, from 0 to {@link #getTypePathLength()} excluded.
* @return The index of the type argument.
*/
public int getTypePathArgumentIndex(final int step) {
return typePath[step * 2 + 1] & 0xFF;
}
/**
* Gets the kind of a step of the type path: 0 deeper in an array type, 1 deeper in a nested type, 2 on the bound of a wildcard type argument, 3 on a type
* argument of a parameterized type.
*
* @param step Index of the step, from 0 to {@link #getTypePathLength()} excluded.
* @return The kind of the step.
*/
public int getTypePathKind(final int step) {
return typePath[step * 2] & 0xFF;
}
/**
* Gets the number of steps in the type path.
*
* <p>
* The path leads from the type of the target to the part of it that is annotated. An empty path identifies the outermost part of the type where an
* annotation is allowed. For a non-static inner class, {@code @A Outer.Inner} has an empty path, while {@code Outer.@A Inner} requires one step.
* For a static nested class, {@code Outer.@A Nested} has an empty path.
* </p>
*
* @return The number of steps of the type path.
*/
public int getTypePathLength() {
return typePath.length / 2;
}
@Override
public String toString() {
return "TypeAnnotationEntry(target=0x" + Integer.toHexString(targetType) + ", info=" + Arrays.toString(targetInfo) + ", path=" + Arrays.toString(typePath)
+ ", " + annotationEntry + ")";
}
}