/*
* 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.generic;
import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
import org.apache.bcel.classfile.Utility;
/**
* Instances of this class give users a handle to the instructions contained in an InstructionList. Instruction objects
* may be used more than once within a list, this is useful because it saves memory and may be much faster.
*
* Within an InstructionList an InstructionHandle object is wrapped around all instructions, that is, it implements a cell
* in a doubly-linked list. From the outside only the next and the previous instruction (handle) are accessible. One can
* traverse the list via an Enumeration returned by InstructionList.elements().
*
* @see Instruction
* @see BranchHandle
* @see InstructionList
*/
public class InstructionHandle {
/**
* Empty array.
*
* @since 6.6.0
*/
public static final InstructionHandle[] EMPTY_ARRAY = {};
/**
* Empty array.
*/
static final InstructionTargeter[] EMPTY_INSTRUCTION_TARGETER_ARRAY = {};
/**
* Gets a new instruction handle for the given instruction.
*/
static InstructionHandle getInstructionHandle(final Instruction i) {
return new InstructionHandle(i);
}
private InstructionHandle next;
private InstructionHandle prev;
private Instruction instruction;
/**
* @deprecated (since 6.0) will be made private; do not access directly, use getter/setter
*/
@Deprecated
protected int i_position = -1; // byte code offset of instruction
private Set<InstructionTargeter> targeters;
private Map<Object, Object> attributes;
/**
* Constructs an InstructionHandle.
*
* @param i The instruction.
*/
protected InstructionHandle(final Instruction i) { setInstruction(i); }
/**
* Convenience method, simply calls accept() on the contained instruction.
*
* @param v Visitor object.
*/
public void accept(final Visitor v) {
instruction.accept(v); }
/**
* Add an attribute to an instruction handle.
*
* @param key The key object to store/retrieve the attribute.
* @param attr The attribute to associate with this handle.
*/
public void addAttribute(final Object key, final Object attr) {
if (attributes == null) { attributes = new HashMap<>(3);
}
attributes.put(key, attr); }
/**
* Does nothing.
*
* @deprecated Does nothing as of 6.3.1.
*/
@Deprecated
protected void addHandle() {
// noop
}
/**
* Denote this handle is being referenced by t.
*
* @param t The instruction targeter.
*/
public void addTargeter(final InstructionTargeter t) {
if (targeters == null) { targeters = new HashSet<>();
}
// if (!targeters.contains(t))
targeters.add(t); }
/**
* Delete contents, removes user access.
*/
void dispose() {
next = prev = null; instruction.dispose(); instruction = null; i_position = -1; attributes = null; removeAllTargeters(); }
/**
* Gets an attribute of an instruction handle.
*
* @param key The key object to store/retrieve the attribute.
* @return The attribute value.
*/
public Object getAttribute(final Object key) {
return attributes != null ? attributes.get(key) : null;
}
/**
* Gets all attributes associated with this handle.
*
* @return all attributes associated with this handle.
*/
public Collection<Object> getAttributes() {
if (attributes == null) { attributes = new HashMap<>(3);
}
return attributes.values();
}
/**
* Gets the instruction.
*
* @return The instruction.
*/
public final Instruction getInstruction() {
return instruction;
}
/**
* Gets the next instruction handle.
*
* @return The next instruction handle.
*/
public final InstructionHandle getNext() {
return next;
}
/**
* Gets the position.
*
* @return The position, the byte code offset of the contained instruction. This is accurate only after
* InstructionList.setPositions() has been called.
*/
public int getPosition() {
return i_position;
}
/**
* Gets the previous instruction handle.
*
* @return The previous instruction handle.
*/
public final InstructionHandle getPrev() {
return prev;
}
/**
* Gets the targeters.
*
* @return null, if there are no targeters.
*/
public InstructionTargeter[] getTargeters() {
if (!hasTargeters()) { return EMPTY_INSTRUCTION_TARGETER_ARRAY;
}
final InstructionTargeter[] t = new InstructionTargeter[targeters.size()]; targeters.toArray(t); return t;
}
/**
* Tests whether this handle has targeters.
*
* @return true if this handle has targeters, false otherwise.
*/
public boolean hasTargeters() {
return targeters != null && !targeters.isEmpty();
}
/**
* Remove all targeters, if any.
*/
public void removeAllTargeters() {
if (targeters != null) { targeters.clear();
}
}
/**
* Delete an attribute of an instruction handle.
*
* @param key The key object to retrieve the attribute.
*/
public void removeAttribute(final Object key) {
if (attributes != null) { attributes.remove(key);
}
}
/**
* Denote this handle isn't referenced anymore by t.
*
* @param t The instruction targeter.
*/
public void removeTargeter(final InstructionTargeter t) {
if (targeters != null) { targeters.remove(t);
}
}
/**
* Sets the instruction contained in this handle. The old instruction is disposed of using Instruction.dispose().
*
* @param i The new instruction.
*/
public void setInstruction(final Instruction i) { // Overridden in BranchHandle TODO could be package-protected?
if (i == null) { throw new ClassGenException("Assigning null to handle");
}
if (this.getClass() != BranchHandle.class && i instanceof BranchInstruction) { throw new ClassGenException("Assigning branch instruction " + i + " to plain handle");
}
if (instruction != null) { instruction.dispose();
}
instruction = i; }
/**
* Sets the next instruction handle.
*
* @param next The next to set.
* @return The next instruction handle.
* @since 6.0
*/
final InstructionHandle setNext(final InstructionHandle next) {
this.next = next; return next;
}
/**
* Sets the position, the byte code offset of the contained instruction.
*
* @param pos The position.
*/
void setPosition(final int pos) {
i_position = pos; }
/**
* Sets the previous instruction handle.
*
* @param prev The prev to set.
* @return The previous instruction handle.
* @since 6.0
*/
final InstructionHandle setPrev(final InstructionHandle prev) {
this.prev = prev; return prev;
}
/**
* Temporarily swap the current instruction, without disturbing anything. Meant to be used by a debugger, implementing
* breakpoints. Current instruction is returned.
* <p>
* Warning: if this is used on a BranchHandle then some methods such as getPosition() will still refer to the original
* cached instruction, whereas other BH methods may affect the cache and the replacement instruction.
*
* @param i The replacement instruction.
* @return The old instruction.
*/
// See BCEL-273
// TODO remove this method in any redesign of BCEL
public Instruction swapInstruction(final Instruction i) {
final Instruction oldInstruction = instruction; instruction = i; return oldInstruction;
}
/**
* Gets a string representation of the contained instruction.
*
* @return A string representation of the contained instruction.
*/
@Override
public String toString() {
return toString(true);
}
/**
* Gets a verbose string representation of the contained instruction.
*
* @param verbose whether to be verbose.
* @return A (verbose) string representation of the contained instruction.
*/
public String toString(final boolean verbose) {
return Utility.format(i_position, 4, false, ' ') + ": " + instruction.toString(verbose);
}
/**
* Called by InstructionList.setPositions when setting the position for every instruction. In the presence of variable
* length instructions 'setPositions()' performs multiple passes over the instruction list to calculate the correct
* (byte) positions and offsets by calling this function.
*
* @param offset additional offset caused by preceding (variable length) instructions.
* @param maxOffset The maximum offset that may be caused by these instructions.
* @return additional offset caused by possible change of this instruction's length.
*/
protected int updatePosition(final int offset, final int maxOffset) {
i_position += offset; return 0;
}
}