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 <gardgreg...@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();