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 2019/09/09 14:57:24 UTC
[commons-bcel] 02/02: Javadoc and better param names.
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 1fab454ef0501571d575ae6fb0c8367fd03f8a85
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Mon Sep 9 10:57:17 2019 -0400
Javadoc and better param names.
---
.../org/apache/bcel/classfile/LocalVariable.java | 39 +++++++--------
.../org/apache/bcel/generic/LocalVariableGen.java | 6 +--
.../bcel/verifier/statics/LocalVariableInfo.java | 57 +++++++++++++---------
.../bcel/verifier/statics/LocalVariablesInfo.java | 25 +++++++---
.../bcel/verifier/structurals/LocalVariables.java | 50 ++++++++++++-------
.../bcel/verifier/structurals/Subroutine.java | 16 +++---
6 files changed, 115 insertions(+), 78 deletions(-)
diff --git a/src/main/java/org/apache/bcel/classfile/LocalVariable.java b/src/main/java/org/apache/bcel/classfile/LocalVariable.java
index f8100cf..7ad67e4 100644
--- a/src/main/java/org/apache/bcel/classfile/LocalVariable.java
+++ b/src/main/java/org/apache/bcel/classfile/LocalVariable.java
@@ -45,7 +45,7 @@ public final class LocalVariable implements Cloneable, Node, Constants {
// Technically, a decscriptor_index for a local variable table entry
// and a signature_index for a local variable type table entry.
private int signature_index; // Index of variable signature
- private int index; /* Variable is `index'th local variable on
+ private int index; /* Variable is index'th local variable on
* this method's frame.
*/
private ConstantPool constant_pool;
@@ -53,18 +53,19 @@ public final class LocalVariable implements Cloneable, Node, Constants {
/**
- * Initialize from another object. Note that both objects use the same
+ * Initializes from another LocalVariable. Note that both objects use the same
* references (shallow copy). Use copy() for a physical copy.
+ *
+ * @param localVariable Another LocalVariable.
*/
- public LocalVariable(final LocalVariable c) {
- this(c.getStartPC(), c.getLength(), c.getNameIndex(), c.getSignatureIndex(), c.getIndex(),
- c.getConstantPool());
- this.orig_index = c.getOrigIndex();
+ public LocalVariable(final LocalVariable localVariable) {
+ this(localVariable.getStartPC(), localVariable.getLength(), localVariable.getNameIndex(),
+ localVariable.getSignatureIndex(), localVariable.getIndex(), localVariable.getConstantPool());
+ this.orig_index = localVariable.getOrigIndex();
}
-
/**
- * Construct object from file stream.
+ * Constructs object from file stream.
* @param file Input stream
* @throws IOException
*/
@@ -129,20 +130,20 @@ public final class LocalVariable implements Cloneable, Node, Constants {
/**
- * Dump local variable to file stream in binary format.
+ * Dumps local variable to file stream in binary format.
*
- * @param file Output file stream
- * @throws IOException
+ * @param dataOutputStream Output file stream
+ * @exception IOException if an I/O error occurs.
+ * @see java.io.FilterOutputStream#out
*/
- public void dump( final DataOutputStream file ) throws IOException {
- file.writeShort(start_pc);
- file.writeShort(length);
- file.writeShort(name_index);
- file.writeShort(signature_index);
- file.writeShort(index);
+ public void dump(final DataOutputStream dataOutputStream) throws IOException {
+ dataOutputStream.writeShort(start_pc);
+ dataOutputStream.writeShort(length);
+ dataOutputStream.writeShort(name_index);
+ dataOutputStream.writeShort(signature_index);
+ dataOutputStream.writeShort(index);
}
-
/**
* @return Constant pool used by this object.
*/
@@ -212,7 +213,7 @@ public final class LocalVariable implements Cloneable, Node, Constants {
/**
- * @return Start of range where he variable is valid
+ * @return Start of range where the variable is valid
*/
public int getStartPC() {
return start_pc;
diff --git a/src/main/java/org/apache/bcel/generic/LocalVariableGen.java b/src/main/java/org/apache/bcel/generic/LocalVariableGen.java
index b7722af..d2316df 100644
--- a/src/main/java/org/apache/bcel/generic/LocalVariableGen.java
+++ b/src/main/java/org/apache/bcel/generic/LocalVariableGen.java
@@ -21,7 +21,7 @@ import org.apache.bcel.Const;
import org.apache.bcel.classfile.LocalVariable;
/**
- * This class represents a local variable within a method. It contains its
+ * Represents a local variable within a method. It contains its
* scope, name and type. The generated LocalVariable object can be obtained
* with getLocalVariable which needs the instruction list and the constant
* pool as parameters.
@@ -66,7 +66,7 @@ public class LocalVariableGen implements InstructionTargeter, NamedAndTyped, Clo
/**
- * Generate a local variable that with index `index'. Note that double and long
+ * Generates a local variable that with index `index'. Note that double and long
* variables need two indexs. Index indices have to be provided by the user.
*
* @param index index of local variable
@@ -84,7 +84,7 @@ public class LocalVariableGen implements InstructionTargeter, NamedAndTyped, Clo
/**
- * Get LocalVariable object.
+ * Gets LocalVariable object.
*
* This relies on that the instruction list has already been dumped to byte code or
* or that the `setPositions' methods has been called for the instruction list.
diff --git a/src/main/java/org/apache/bcel/verifier/statics/LocalVariableInfo.java b/src/main/java/org/apache/bcel/verifier/statics/LocalVariableInfo.java
index 9779cc8..3db76d6 100644
--- a/src/main/java/org/apache/bcel/verifier/statics/LocalVariableInfo.java
+++ b/src/main/java/org/apache/bcel/verifier/statics/LocalVariableInfo.java
@@ -28,12 +28,12 @@ import org.apache.bcel.verifier.exc.LocalVariableInfoInconsistentException;
* the name and the type of a local variable in
* a given slot (== index). This information
* often changes in course of byte code offsets.
- *
*/
public class LocalVariableInfo{
/** The types database. KEY: String representing the offset integer. */
private final Hashtable<String, Type> types = new Hashtable<>();
+
/** The names database. KEY: String representing the offset integer. */
private final Hashtable<String, String> names = new Hashtable<>();
@@ -44,6 +44,7 @@ public class LocalVariableInfo{
private void setName(final int offset, final String name) {
names.put(Integer.toString(offset), name);
}
+
/**
* Adds a type of a local variable and a certain slot to our 'types'
* (Hashtable) database.
@@ -53,54 +54,64 @@ public class LocalVariableInfo{
}
/**
- * Returns the type of the local variable that uses this local
- * variable slot at the given bytecode offset.
- * Care for legal bytecode offsets yourself, otherwise the return value
- * might be wrong.
- * May return 'null' if nothing is known about the type of this local
- * variable slot at the given bytecode offset.
+ * Returns the type of the local variable that uses this local variable slot at the given bytecode offset. Care for
+ * legal bytecode offsets yourself, otherwise the return value might be wrong. May return 'null' if nothing is known
+ * about the type of this local variable slot at the given bytecode offset.
+ *
+ * @param offset bytecode offset.
+ * @return the type of the local variable that uses this local variable slot at the given bytecode offset.
*/
public Type getType(final int offset) {
return types.get(Integer.toString(offset));
}
+
/**
- * Returns the name of the local variable that uses this local
- * variable slot at the given bytecode offset.
- * Care for legal bytecode offsets yourself, otherwise the return value
- * might be wrong.
- * May return 'null' if nothing is known about the type of this local
- * variable slot at the given bytecode offset.
+ * Returns the name of the local variable that uses this local variable slot at the given bytecode offset. Care for
+ * legal bytecode offsets yourself, otherwise the return value might be wrong. May return 'null' if nothing is known
+ * about the type of this local variable slot at the given bytecode offset.
+ *
+ * @param offset bytecode offset.
+ * @return the name of the local variable that uses this local variable slot at the given bytecode offset.
*/
public String getName(final int offset) {
return names.get(Integer.toString(offset));
}
+
/**
* Adds some information about this local variable (slot).
+ *
+ * @param name variable name
+ * @param startPc Range in which the variable is valid.
+ * @param length length of ...
+ * @param type variable type
+ *
* @throws LocalVariableInfoInconsistentException if the new information conflicts
* with already gathered information.
*/
- public void add(final String name, final int startpc, final int length, final Type t) throws LocalVariableInfoInconsistentException{
- for (int i=startpc; i<=startpc+length; i++) { // incl/incl-notation!
- add(i,name,t);
+ public void add(final String name, final int startPc, final int length, final Type type)
+ throws LocalVariableInfoInconsistentException {
+ for (int i = startPc; i <= startPc + length; i++) { // incl/incl-notation!
+ add(i, name, type);
}
}
/**
* Adds information about name and type for a given offset.
+ *
* @throws LocalVariableInfoInconsistentException if the new information conflicts
* with already gathered information.
*/
- private void add(final int offset, final String name, final Type t) throws LocalVariableInfoInconsistentException{
+ private void add(final int offset, final String name, final Type t) throws LocalVariableInfoInconsistentException {
if (getName(offset) != null) {
- if (! getName(offset).equals(name)) {
- throw new LocalVariableInfoInconsistentException("At bytecode offset '"+offset+
- "' a local variable has two different names: '"+getName(offset)+"' and '"+name+"'.");
+ if (!getName(offset).equals(name)) {
+ throw new LocalVariableInfoInconsistentException("At bytecode offset '" + offset
+ + "' a local variable has two different names: '" + getName(offset) + "' and '" + name + "'.");
}
}
if (getType(offset) != null) {
- if (! getType(offset).equals(t)) {
- throw new LocalVariableInfoInconsistentException("At bytecode offset '"+offset+
- "' a local variable has two different types: '"+getType(offset)+"' and '"+t+"'.");
+ if (!getType(offset).equals(t)) {
+ throw new LocalVariableInfoInconsistentException("At bytecode offset '" + offset
+ + "' a local variable has two different types: '" + getType(offset) + "' and '" + t + "'.");
}
}
setName(offset, name);
diff --git a/src/main/java/org/apache/bcel/verifier/statics/LocalVariablesInfo.java b/src/main/java/org/apache/bcel/verifier/statics/LocalVariablesInfo.java
index 14479e7..069efa6 100644
--- a/src/main/java/org/apache/bcel/verifier/statics/LocalVariablesInfo.java
+++ b/src/main/java/org/apache/bcel/verifier/statics/LocalVariablesInfo.java
@@ -26,7 +26,6 @@ import org.apache.bcel.verifier.exc.LocalVariableInfoInconsistentException;
* A utility class holding the information about
* the names and the types of the local variables in
* a given method.
- *
*/
public class LocalVariablesInfo{
@@ -41,7 +40,12 @@ public class LocalVariablesInfo{
}
}
- /** Returns the LocalVariableInfo for the given slot. */
+ /**
+ * Returns the LocalVariableInfo for the given slot.
+ *
+ * @param slot Slot to query.
+ * @return The LocalVariableInfo for the given slot.
+ */
public LocalVariableInfo getLocalVariableInfo(final int slot) {
if (slot < 0 || slot >= localVariableInfos.length) {
throw new AssertionViolatedException("Slot number for local variable information out of range.");
@@ -52,22 +56,27 @@ public class LocalVariablesInfo{
/**
* Adds information about the local variable in slot 'slot'. Automatically
* adds information for slot+1 if 't' is Type.LONG or Type.DOUBLE.
+ *
+ * @param name variable name
+ * @param startPc Range in which the variable is valid.
+ * @param length length of ...
+ * @param type variable type
* @throws LocalVariableInfoInconsistentException if the new information conflicts
* with already gathered information.
*/
- public void add(final int slot, final String name, final int startpc, final int length, final Type t) throws LocalVariableInfoInconsistentException{
+ public void add(final int slot, final String name, final int startPc, final int length, final Type type) throws LocalVariableInfoInconsistentException{
// The add operation on LocalVariableInfo may throw the '...Inconsistent...' exception, we don't throw it explicitely here.
if (slot < 0 || slot >= localVariableInfos.length) {
throw new AssertionViolatedException("Slot number for local variable information out of range.");
}
- localVariableInfos[slot].add(name, startpc, length, t);
- if (t == Type.LONG) {
- localVariableInfos[slot+1].add(name, startpc, length, LONG_Upper.theInstance());
+ localVariableInfos[slot].add(name, startPc, length, type);
+ if (type == Type.LONG) {
+ localVariableInfos[slot+1].add(name, startPc, length, LONG_Upper.theInstance());
}
- if (t == Type.DOUBLE) {
- localVariableInfos[slot+1].add(name, startpc, length, DOUBLE_Upper.theInstance());
+ if (type == Type.DOUBLE) {
+ localVariableInfos[slot+1].add(name, startPc, length, DOUBLE_Upper.theInstance());
}
}
}
diff --git a/src/main/java/org/apache/bcel/verifier/structurals/LocalVariables.java b/src/main/java/org/apache/bcel/verifier/structurals/LocalVariables.java
index fd3b237..f884749 100644
--- a/src/main/java/org/apache/bcel/verifier/structurals/LocalVariables.java
+++ b/src/main/java/org/apache/bcel/verifier/structurals/LocalVariables.java
@@ -29,15 +29,18 @@ import org.apache.bcel.verifier.exc.StructuralCodeConstraintException;
*
*/
public class LocalVariables implements Cloneable {
+
/** The Type[] containing the local variable slots. */
private final Type[] locals;
/**
* Creates a new LocalVariables object.
+ *
+ * @param localVariableCount local variable count.
*/
- public LocalVariables(final int maxLocals) {
- locals = new Type[maxLocals];
- for (int i=0; i<maxLocals; i++) {
+ public LocalVariables(final int localVariableCount) {
+ locals = new Type[localVariableCount];
+ for (int i=0; i<localVariableCount; i++) {
locals[i] = Type.UNKNOWN;
}
}
@@ -57,23 +60,29 @@ public class LocalVariables implements Cloneable {
}
/**
- * Returns the type of the local variable slot i.
+ * Returns the type of the local variable slot index.
+ *
+ * @param slotIndex Slot to look up.
+ * @return the type of the local variable slot index.
*/
- public Type get(final int i) {
- return locals[i];
+ public Type get(final int slotIndex) {
+ return locals[slotIndex];
}
/**
* Returns a (correctly typed) clone of this object.
* This is equivalent to ((LocalVariables) this.clone()).
+ *
+ * @return a (correctly typed) clone of this object.
*/
public LocalVariables getClone() {
return (LocalVariables) this.clone();
}
/**
- * Returns the number of local variable slots this
- * LocalVariables instance has.
+ * Returns the number of local variable slots.
+ *
+ * @return the number of local variable slots.
*/
public int maxLocals() {
return locals.length;
@@ -81,12 +90,15 @@ public class LocalVariables implements Cloneable {
/**
* Sets a new Type for the given local variable slot.
+ *
+ * @param slotIndex Target slot index.
+ * @param type Type to save at the given slot index.
*/
- public void set(final int i, final Type type) { // TODO could be package-protected?
+ public void set(final int slotIndex, final Type type) { // TODO could be package-protected?
if (type == Type.BYTE || type == Type.SHORT || type == Type.BOOLEAN || type == Type.CHAR) {
throw new AssertionViolatedException("LocalVariables do not know about '"+type+"'. Use Type.INT instead.");
}
- locals[i] = type;
+ locals[slotIndex] = type;
}
/** @return a hash code value for the object.
@@ -118,15 +130,17 @@ public class LocalVariables implements Cloneable {
/**
* Merges two local variables sets as described in the Java Virtual Machine Specification,
* Second Edition, section 4.9.2, page 146.
+ *
+ * @param localVariable other local variable.
*/
- public void merge(final LocalVariables lv) {
+ public void merge(final LocalVariables localVariable) {
- if (this.locals.length != lv.locals.length) {
+ if (this.locals.length != localVariable.locals.length) {
throw new AssertionViolatedException("Merging LocalVariables of different size?!? From different methods or what?!?");
}
for (int i=0; i<locals.length; i++) {
- merge(lv, i);
+ merge(localVariable, i);
}
}
@@ -204,13 +218,15 @@ public class LocalVariables implements Cloneable {
}
/**
- * Replaces all occurences of u in this local variables set
+ * Replaces all occurrences of {@code uninitializedObjectType} in this local variables set
* with an "initialized" ObjectType.
+ *
+ * @param uninitializedObjectType the object to match.
*/
- public void initializeObject(final UninitializedObjectType u) {
+ public void initializeObject(final UninitializedObjectType uninitializedObjectType) {
for (int i=0; i<locals.length; i++) {
- if (locals[i] == u) {
- locals[i] = u.getInitialized();
+ if (locals[i] == uninitializedObjectType) {
+ locals[i] = uninitializedObjectType.getInitialized();
}
}
}
diff --git a/src/main/java/org/apache/bcel/verifier/structurals/Subroutine.java b/src/main/java/org/apache/bcel/verifier/structurals/Subroutine.java
index ee6cffd..ea60415 100644
--- a/src/main/java/org/apache/bcel/verifier/structurals/Subroutine.java
+++ b/src/main/java/org/apache/bcel/verifier/structurals/Subroutine.java
@@ -22,13 +22,13 @@ import org.apache.bcel.generic.InstructionHandle;
/**
* This interface defines properties of JVM bytecode subroutines. Note that it is 'abused' to maintain the top-level
* code in a consistent fashion, too.
- *
*/
public interface Subroutine {
+
/**
* Returns all the JsrInstructions that have the first instruction of this subroutine as their target. <B>Must not
* be invoked on the 'top-level subroutine'.</B>
- *
+ *
* @return The JsrInstructions that have the first instruction of this subroutine as their target.
*/
InstructionHandle[] getEnteringJsrInstructions();
@@ -36,7 +36,7 @@ public interface Subroutine {
/**
* Returns the one and only RET that leaves the subroutine. Note that JustIce has a pretty rigid notion of a
* subroutine. <B>Must not be invoked on the 'top-level subroutine'.</B>
- *
+ *
* @return The one and only RET that leaves the subroutine.
*
* @see Subroutines
@@ -47,7 +47,7 @@ public interface Subroutine {
* Returns all instructions that together form this subroutine. Note that an instruction is part of exactly one
* subroutine (the top-level code is considered to be a special subroutine) - else it is not reachable at all (dead
* code).
- *
+ *
* @return All instructions that together form this subroutine.
*/
InstructionHandle[] getInstructions();
@@ -55,7 +55,7 @@ public interface Subroutine {
/**
* Returns if the given InstructionHandle refers to an instruction that is part of this subroutine. This is a
* convenience method that saves iteration over the InstructionHandle objects returned by getInstructions().
- *
+ *
* @param inst The InstructionHandle to test.
* @return Whether the given InstructionHandle refers to an instruction that is part of this subroutine.
*
@@ -66,7 +66,7 @@ public interface Subroutine {
/**
* Returns an int[] containing the indices of the local variable slots accessed by this Subroutine (read-accessed,
* write-accessed or both); local variables referenced by subroutines of this subroutine are not included.
- *
+ *
* @return An int[] containing the indices of the local variable slots.
* @see #getRecursivelyAccessedLocalsIndices()
*/
@@ -75,7 +75,7 @@ public interface Subroutine {
/**
* Returns an int[] containing the indices of the local variable slots accessed by this Subroutine (read-accessed,
* write-accessed or both); local variables referenced by subroutines of this subroutine are included.
- *
+ *
* @return An int[] containing the indices of the local variable slots.
* @see #getAccessedLocalsIndices()
*/
@@ -83,7 +83,7 @@ public interface Subroutine {
/**
* Returns the subroutines that are directly called from this subroutine.
- *
+ *
* @return The subroutines that are directly called from this subroutine.
*/
Subroutine[] subSubs();