You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2026/01/09 20:03:16 UTC
(commons-bcel) 02/11: Javadoc
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-bcel.git
commit 0f8dedc0a3817a2aa9ae9d2348c30af5e63385f4
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Fri Jan 9 14:46:16 2026 -0500
Javadoc
---
.../apache/bcel/generic/AnnotationEntryGen.java | 53 ++++++++++++++++++++++
.../apache/bcel/generic/ArithmeticInstruction.java | 4 +-
.../apache/bcel/generic/ArrayElementValueGen.java | 38 ++++++++++++++--
.../java/org/apache/bcel/generic/ArrayType.java | 12 +++--
src/main/java/org/apache/bcel/generic/BIPUSH.java | 4 +-
.../java/org/apache/bcel/generic/BasicType.java | 7 +++
.../bcel/generic/ConstantPushInstruction.java | 5 ++
.../org/apache/bcel/generic/ElementValueGen.java | 5 ++
.../org/apache/bcel/generic/ReferenceType.java | 14 ++++--
.../org/apache/bcel/generic/ReturnInstruction.java | 4 +-
.../org/apache/bcel/generic/StoreInstruction.java | 8 ++--
src/main/java/org/apache/bcel/generic/Type.java | 20 ++++++--
12 files changed, 156 insertions(+), 18 deletions(-)
diff --git a/src/main/java/org/apache/bcel/generic/AnnotationEntryGen.java b/src/main/java/org/apache/bcel/generic/AnnotationEntryGen.java
index 0e66dbe4..fa343f46 100644
--- a/src/main/java/org/apache/bcel/generic/AnnotationEntryGen.java
+++ b/src/main/java/org/apache/bcel/generic/AnnotationEntryGen.java
@@ -201,6 +201,15 @@ public class AnnotationEntryGen {
return null;
}
+ /**
+ * Reads an AnnotationEntryGen from a DataInput.
+ *
+ * @param dis the data input stream.
+ * @param cpool the constant pool generator.
+ * @param b whether the annotation is runtime visible.
+ * @return the annotation entry generator.
+ * @throws IOException if an I/O error occurs.
+ */
public static AnnotationEntryGen read(final DataInput dis, final ConstantPoolGen cpool, final boolean b) throws IOException {
final AnnotationEntryGen a = new AnnotationEntryGen(cpool);
a.typeIndex = dis.readUnsignedShort();
@@ -246,6 +255,14 @@ public class AnnotationEntryGen {
this.cpool = cpool;
}
+ /**
+ * Constructs an AnnotationEntryGen.
+ *
+ * @param type the object type.
+ * @param elements the element value pairs.
+ * @param vis whether the annotation is visible.
+ * @param cpool the constant pool generator.
+ */
public AnnotationEntryGen(final ObjectType type, final List<ElementValuePairGen> elements, final boolean vis, final ConstantPoolGen cpool) {
this.cpool = cpool;
this.typeIndex = cpool.addUtf8(type.getSignature());
@@ -253,6 +270,11 @@ public class AnnotationEntryGen {
isRuntimeVisible = vis;
}
+ /**
+ * Adds an element name value pair.
+ *
+ * @param evp the element value pair generator.
+ */
public void addElementNameValuePair(final ElementValuePairGen evp) {
if (evs == null) {
evs = new ArrayList<>();
@@ -264,6 +286,12 @@ public class AnnotationEntryGen {
return Streams.of(in).map(nvp -> new ElementValuePairGen(nvp, cpool, copyPoolEntries)).collect(Collectors.toList());
}
+ /**
+ * Dumps this annotation entry to a DataOutputStream.
+ *
+ * @param dos the data output stream.
+ * @throws IOException if an I/O error occurs.
+ */
public void dump(final DataOutputStream dos) throws IOException {
dos.writeShort(typeIndex); // u2 index of type name in cpool
dos.writeShort(evs.size()); // u2 element_value pair count
@@ -285,15 +313,30 @@ public class AnnotationEntryGen {
return a;
}
+ /**
+ * Gets the type index.
+ *
+ * @return the type index.
+ */
public int getTypeIndex() {
return typeIndex;
}
+ /**
+ * Gets the type name.
+ *
+ * @return the type name.
+ */
public final String getTypeName() {
return getTypeSignature(); // BCELBUG: Should I use this instead?
// Utility.signatureToString(getTypeSignature());
}
+ /**
+ * Gets the type signature.
+ *
+ * @return the type signature.
+ */
public final String getTypeSignature() {
// ConstantClass c = (ConstantClass) cpool.getConstant(typeIndex);
final ConstantUtf8 utf8 = (ConstantUtf8) cpool.getConstant(typeIndex/* c.getNameIndex() */);
@@ -309,6 +352,11 @@ public class AnnotationEntryGen {
return evs;
}
+ /**
+ * Gets whether this annotation is runtime visible.
+ *
+ * @return true if this annotation is runtime visible.
+ */
public boolean isRuntimeVisible() {
return isRuntimeVisible;
}
@@ -317,6 +365,11 @@ public class AnnotationEntryGen {
isRuntimeVisible = b;
}
+ /**
+ * Returns a short string representation of this annotation.
+ *
+ * @return a short string representation of this annotation.
+ */
public String toShortString() {
final StringBuilder s = new StringBuilder();
s.append("@").append(getTypeName()).append("(");
diff --git a/src/main/java/org/apache/bcel/generic/ArithmeticInstruction.java b/src/main/java/org/apache/bcel/generic/ArithmeticInstruction.java
index 32bb93c2..797be007 100644
--- a/src/main/java/org/apache/bcel/generic/ArithmeticInstruction.java
+++ b/src/main/java/org/apache/bcel/generic/ArithmeticInstruction.java
@@ -32,7 +32,9 @@ public abstract class ArithmeticInstruction extends Instruction implements Typed
}
/**
- * @param opcode of instruction
+ * Constructs an ArithmeticInstruction.
+ *
+ * @param opcode of instruction.
*/
protected ArithmeticInstruction(final short opcode) {
super(opcode, (short) 1);
diff --git a/src/main/java/org/apache/bcel/generic/ArrayElementValueGen.java b/src/main/java/org/apache/bcel/generic/ArrayElementValueGen.java
index ace560e1..27496f18 100644
--- a/src/main/java/org/apache/bcel/generic/ArrayElementValueGen.java
+++ b/src/main/java/org/apache/bcel/generic/ArrayElementValueGen.java
@@ -39,8 +39,11 @@ public class ArrayElementValueGen extends ElementValueGen {
private final List<ElementValueGen> evalues;
/**
- * @param value
- * @param cpool
+ * Constructs an ArrayElementValueGen.
+ *
+ * @param value the array element value.
+ * @param cpool the constant pool generator.
+ * @param copyPoolEntries whether to copy pool entries.
*/
public ArrayElementValueGen(final ArrayElementValue value, final ConstantPoolGen cpool, final boolean copyPoolEntries) {
super(ARRAY, cpool);
@@ -51,11 +54,23 @@ public class ArrayElementValueGen extends ElementValueGen {
}
}
+ /**
+ * Constructs an ArrayElementValueGen.
+ *
+ * @param cp the constant pool generator.
+ */
public ArrayElementValueGen(final ConstantPoolGen cp) {
super(ARRAY, cp);
evalues = new ArrayList<>();
}
+ /**
+ * Constructs an ArrayElementValueGen.
+ *
+ * @param type the type.
+ * @param elementValues the element values.
+ * @param cpool the constant pool generator.
+ */
public ArrayElementValueGen(final int type, final ElementValue[] elementValues, final ConstantPoolGen cpool) {
super(type, cpool);
if (type != ARRAY) {
@@ -64,6 +79,11 @@ public class ArrayElementValueGen extends ElementValueGen {
this.evalues = Streams.of(elementValues).map(e -> copy(e, cpool, true)).collect(Collectors.toList());
}
+ /**
+ * Adds an element.
+ *
+ * @param gen the element value generator.
+ */
public void addElement(final ElementValueGen gen) {
evalues.add(gen);
}
@@ -78,7 +98,9 @@ public class ArrayElementValueGen extends ElementValueGen {
}
/**
- * Return immutable variant of this ArrayElementValueGen
+ * Return immutable variant of this ArrayElementValueGen.
+ *
+ * @return immutable variant of this ArrayElementValueGen.
*/
@Override
public ElementValue getElementValue() {
@@ -90,10 +112,20 @@ public class ArrayElementValueGen extends ElementValueGen {
return new ArrayElementValue(super.getElementValueType(), immutableData, getConstantPool().getConstantPool());
}
+ /**
+ * Gets the element values.
+ *
+ * @return the element values.
+ */
public List<ElementValueGen> getElementValues() {
return evalues;
}
+ /**
+ * Gets the element values size.
+ *
+ * @return the element values size.
+ */
public int getElementValuesSize() {
return evalues.size();
}
diff --git a/src/main/java/org/apache/bcel/generic/ArrayType.java b/src/main/java/org/apache/bcel/generic/ArrayType.java
index f76e9a64..05267e59 100644
--- a/src/main/java/org/apache/bcel/generic/ArrayType.java
+++ b/src/main/java/org/apache/bcel/generic/ArrayType.java
@@ -93,7 +93,9 @@ public final class ArrayType extends ReferenceType {
}
/**
- * @return basic type of array, i.e., for int[][][] the basic type is int
+ * Gets the basic type of array, i.e., for int[][][] the basic type is int.
+ *
+ * @return basic type of array, i.e., for int[][][] the basic type is int.
*/
public Type getBasicType() {
return basicType;
@@ -111,14 +113,18 @@ public final class ArrayType extends ReferenceType {
}
/**
- * @return number of dimensions of array
+ * Gets the number of dimensions of array.
+ *
+ * @return number of dimensions of array.
*/
public int getDimensions() {
return dimensions;
}
/**
- * @return element type of array, i.e., for int[][][] the element type is int[][]
+ * Gets the element type of array, i.e., for int[][][] the element type is int[][].
+ *
+ * @return element type of array, i.e., for int[][][] the element type is int[][].
*/
public Type getElementType() {
if (dimensions == 1) {
diff --git a/src/main/java/org/apache/bcel/generic/BIPUSH.java b/src/main/java/org/apache/bcel/generic/BIPUSH.java
index a118ac15..40c9378f 100644
--- a/src/main/java/org/apache/bcel/generic/BIPUSH.java
+++ b/src/main/java/org/apache/bcel/generic/BIPUSH.java
@@ -41,7 +41,9 @@ public class BIPUSH extends Instruction implements ConstantPushInstruction {
}
/**
- * Push byte on stack
+ * Push byte on stack.
+ *
+ * @param b the byte value to push.
*/
public BIPUSH(final byte b) {
super(org.apache.bcel.Const.BIPUSH, (short) 2);
diff --git a/src/main/java/org/apache/bcel/generic/BasicType.java b/src/main/java/org/apache/bcel/generic/BasicType.java
index 3963c4f0..a7407866 100644
--- a/src/main/java/org/apache/bcel/generic/BasicType.java
+++ b/src/main/java/org/apache/bcel/generic/BasicType.java
@@ -25,6 +25,13 @@ import org.apache.bcel.Const;
*/
public final class BasicType extends Type {
+ /**
+ * Gets the BasicType for the given type constant.
+ *
+ * @param type the type constant.
+ * @return the BasicType.
+ * @since 6.0
+ */
// @since 6.0 no longer final
public static BasicType getType(final byte type) {
switch (type) {
diff --git a/src/main/java/org/apache/bcel/generic/ConstantPushInstruction.java b/src/main/java/org/apache/bcel/generic/ConstantPushInstruction.java
index ed904efc..9d16d7fb 100644
--- a/src/main/java/org/apache/bcel/generic/ConstantPushInstruction.java
+++ b/src/main/java/org/apache/bcel/generic/ConstantPushInstruction.java
@@ -27,5 +27,10 @@ package org.apache.bcel.generic;
*/
public interface ConstantPushInstruction extends PushInstruction, TypedInstruction {
+ /**
+ * Gets the value to be pushed onto the stack.
+ *
+ * @return the value to be pushed onto the stack.
+ */
Number getValue();
}
diff --git a/src/main/java/org/apache/bcel/generic/ElementValueGen.java b/src/main/java/org/apache/bcel/generic/ElementValueGen.java
index b1dc9d47..635fda5e 100644
--- a/src/main/java/org/apache/bcel/generic/ElementValueGen.java
+++ b/src/main/java/org/apache/bcel/generic/ElementValueGen.java
@@ -177,5 +177,10 @@ public abstract class ElementValueGen {
return type;
}
+ /**
+ * Returns a string representation of the element value.
+ *
+ * @return a string representation of the element value.
+ */
public abstract String stringifyValue();
}
diff --git a/src/main/java/org/apache/bcel/generic/ReferenceType.java b/src/main/java/org/apache/bcel/generic/ReferenceType.java
index 05783ae7..f78be865 100644
--- a/src/main/java/org/apache/bcel/generic/ReferenceType.java
+++ b/src/main/java/org/apache/bcel/generic/ReferenceType.java
@@ -46,6 +46,8 @@ public abstract class ReferenceType extends Type {
* interface, then {@link #OBJECT} is returned. If not all of the two classes' superclasses cannot be found, "null" is
* returned. See the JVM specification edition 2, "�4.9.2 The Bytecode Verifier".
*
+ * @param t the other type.
+ * @return the first common superclass.
* @throws ClassNotFoundException on failure to find superclasses of this type, or the type passed as a parameter.
* @deprecated Use getFirstCommonSuperclass(ReferenceType t) which has slightly changed semantics.
*/
@@ -79,7 +81,9 @@ public abstract class ReferenceType extends Type {
* the two classes' superclasses cannot be found, "null" is returned. See the JVM specification edition 2, "�4.9.2 The
* Bytecode Verifier".
*
- * @throws ClassNotFoundException on failure to find superclasses of this type, or the type passed as a parameter
+ * @param t the other type.
+ * @return the first common superclass.
+ * @throws ClassNotFoundException on failure to find superclasses of this type, or the type passed as a parameter.
*/
public ReferenceType getFirstCommonSuperclass(final ReferenceType t) throws ClassNotFoundException {
if (equals(NULL)) {
@@ -148,8 +152,10 @@ public abstract class ReferenceType extends Type {
* Return true iff this is assignment compatible with another type t as defined in the JVM specification; see the
* AASTORE definition there.
*
+ * @param t the other type.
+ * @return true iff this is assignment compatible with another type t.
* @throws ClassNotFoundException if any classes or interfaces required to determine assignment compatibility can't be
- * found
+ * found.
*/
public boolean isAssignmentCompatibleWith(final Type t) throws ClassNotFoundException {
if (!(t instanceof ReferenceType)) {
@@ -247,8 +253,10 @@ public abstract class ReferenceType extends Type {
* {@link #NULL} is not defined (see the CHECKCAST definition in the JVM specification). However, because for example CHECKCAST
* doesn't throw a ClassCastException when casting a null reference to any Object, true is returned in this case.
*
+ * @param t the other type.
+ * @return true iff this type is castable to another type t.
* @throws ClassNotFoundException if any classes or interfaces required to determine assignment compatibility can't be
- * found
+ * found.
*/
public boolean isCastableTo(final Type t) throws ClassNotFoundException {
if (equals(NULL)) {
diff --git a/src/main/java/org/apache/bcel/generic/ReturnInstruction.java b/src/main/java/org/apache/bcel/generic/ReturnInstruction.java
index 3ce41f71..50fbeb75 100644
--- a/src/main/java/org/apache/bcel/generic/ReturnInstruction.java
+++ b/src/main/java/org/apache/bcel/generic/ReturnInstruction.java
@@ -33,7 +33,9 @@ public abstract class ReturnInstruction extends Instruction implements Exception
}
/**
- * @param opcode of instruction
+ * Constructs a ReturnInstruction.
+ *
+ * @param opcode of instruction.
*/
protected ReturnInstruction(final short opcode) {
super(opcode, (short) 1);
diff --git a/src/main/java/org/apache/bcel/generic/StoreInstruction.java b/src/main/java/org/apache/bcel/generic/StoreInstruction.java
index f9647b08..4eaa2757 100644
--- a/src/main/java/org/apache/bcel/generic/StoreInstruction.java
+++ b/src/main/java/org/apache/bcel/generic/StoreInstruction.java
@@ -32,9 +32,11 @@ public abstract class StoreInstruction extends LocalVariableInstruction implemen
}
/**
- * @param opcode Instruction opcode
- * @param cTag Instruction number for compact version, ASTORE_0, for example
- * @param n local variable index (unsigned short)
+ * Constructs a StoreInstruction.
+ *
+ * @param opcode Instruction opcode.
+ * @param cTag Instruction number for compact version, ASTORE_0, for example.
+ * @param n local variable index (unsigned short).
*/
protected StoreInstruction(final short opcode, final short cTag, final int n) {
super(opcode, cTag, n);
diff --git a/src/main/java/org/apache/bcel/generic/Type.java b/src/main/java/org/apache/bcel/generic/Type.java
index 91ec9aa1..a406efc5 100644
--- a/src/main/java/org/apache/bcel/generic/Type.java
+++ b/src/main/java/org/apache/bcel/generic/Type.java
@@ -346,11 +346,18 @@ public abstract class Type {
return false;
}
+ /**
+ * Gets the class name.
+ *
+ * @return the class name.
+ */
public String getClassName() {
return toString();
}
/**
+ * Gets the signature for this type.
+ *
* @return signature for given type.
*/
public String getSignature() {
@@ -358,7 +365,9 @@ public abstract class Type {
}
/**
- * @return stack size of this type (2 for long and double, 0 for void, 1 otherwise)
+ * Gets the stack size of this type.
+ *
+ * @return stack size of this type (2 for long and double, 0 for void, 1 otherwise).
*/
public int getSize() {
switch (type) {
@@ -373,14 +382,18 @@ public abstract class Type {
}
/**
- * @return type as defined in Constants
+ * Gets the type as defined in Constants.
+ *
+ * @return type as defined in Constants.
*/
public byte getType() {
return type;
}
/**
- * @return hash code of Type
+ * Gets the hash code of this Type.
+ *
+ * @return hash code of Type.
*/
@Override
public int hashCode() {
@@ -391,6 +404,7 @@ public abstract class Type {
* boolean, short and char variable are considered as int in the stack or local variable area. Returns {@link #INT}
* for {@link #BOOLEAN}, {@link #SHORT} or {@link #CHAR}, otherwise returns the given type.
*
+ * @return the normalized type.
* @since 6.0
*/
public Type normalizeForStackOrLocal() {