com.vladium.jcd.cls
Interface IConstantCollection

All Superinterfaces:
java.lang.Cloneable, IClassFormatOutput
All Known Implementing Classes:
ConstantCollection

public interface IConstantCollection
extends java.lang.Cloneable, IClassFormatOutput

An abstraction of constant pool in .class format. This interface disallows any pool mutation that invalidates already existing pool indices.

Author:
(C) 2001, Vlad Roubtsov

Nested Class Summary
static interface IConstantCollection.IConstantComparator
          A simple interface to express custom semantics of constant equality.
static interface IConstantCollection.IConstantIterator
          A custom fail-fast iterator class returned by iterator().
 
Method Summary
 void accept(IClassDefVisitor visitor, java.lang.Object ctx)
           
 int add(CONSTANT_info constant)
          Appends 'constant' to the end of the collection.
 java.lang.Object clone()
           
 int find(int type, IConstantCollection.IConstantComparator comparator)
          Searches the pool for a matching constant of given type with equality semantics expressed by 'comparator'.
 int findCONSTANT_Utf8(java.lang.String value)
          Convenience method that can lookup CONSTANT_Utf8 entries in O(1) time on average.
 CONSTANT_info get(int index)
          Returns a CONSTANT_info at a given pool index.
 IConstantCollection.IConstantIterator iterator()
          Returns a fail-fast iterator over all valid entries in the pool.
 CONSTANT_info set(int index, CONSTANT_info constant)
          Replaces an existing constant pool entry.
 int size()
          Returns the number of CONSTANT_info entries in this collection.
 
Methods inherited from interface com.vladium.jcd.compiler.IClassFormatOutput
writeInClassFormat
 

Method Detail

get

public CONSTANT_info get(int index)
Returns a CONSTANT_info at a given pool index. Note that 'index' is 1-based [the way an index would be embedded in bytecode instructions]. Note that because CONSTANT_Long and CONSTANT_Double entries occupy two consequitive index slots certain index values inside the valid range can be invalid; use iterator() to iterate only over valid entries in a transparent fashion.

Parameters:
index - constant pool index [must be in [1, size()] range]
Returns:
CONSTANT_info constant pool entry at this index [never null]
Throws:
java.lang.IllegalStateException - if an attempt is made to reference an invalid slot index
java.lang.IndexOutOfBoundsException - if an attempt is made to reference a slot outside of the valid range

iterator

public IConstantCollection.IConstantIterator iterator()
Returns a fail-fast iterator over all valid entries in the pool. The resulting object would be invalidated by simultaneous mutation to the underlying collection pool.

Returns:
IConstantIterator iterator over all entries in the collection [never null]

find

public int find(int type,
                IConstantCollection.IConstantComparator comparator)
Searches the pool for a matching constant of given type with equality semantics expressed by 'comparator'. This method guarantees that when comparator.equals(c) is called c.type() is 'type'. The cost is O(pool size). When multiple matches exist, the location of the first one found will be returned (chosen in some indeterministic way).

Parameters:
type - type of constants to filter by [not validated]
comparator - [may not be null]
Returns:
index of the first found entry [-1 if not found]
Throws:
java.lang.IllegalArgumentException - if 'comparator' is null

findCONSTANT_Utf8

public int findCONSTANT_Utf8(java.lang.String value)
Convenience method that can lookup CONSTANT_Utf8 entries in O(1) time on average. Note that .class format does not guarantee that all such entries are not duplicated in the pool. When multiple matches exist, the location of the first one found will be returned (chosen in some indeterministic way).

Parameters:
value - string value on which to match [may not be null]
Returns:
index of the first found entry [-1 if not found]
Throws:
java.lang.IllegalArgumentException - if 'value' is null

size

public int size()
Returns the number of CONSTANT_info entries in this collection.

Returns:
the number of constants in this pool [can be 0]

clone

public java.lang.Object clone()

accept

public void accept(IClassDefVisitor visitor,
                   java.lang.Object ctx)

add

public int add(CONSTANT_info constant)
Appends 'constant' to the end of the collection. No duplicate checks are made.

Parameters:
constant - new constant [may not be null; input unchecked]
Returns:
the pool index of the newly added entry [always positive]

set

public CONSTANT_info set(int index,
                         CONSTANT_info constant)
Replaces an existing constant pool entry. A replacement can be made only for a constant of the same width as the constant currently occupying the slot.

Parameters:
index - constant pool index [must be in [1, size()] range]
constant - new entry to set [may not be null; input unchecked]
Returns:
CONSTANT_info previous contents at this pool index [never null]
Throws:
java.lang.IllegalArgumentException - if the new constant's width is different from the current entry's
java.lang.IllegalStateException - if an attempt is made to reference an invalid slot index [see get(int)]
java.lang.IndexOutOfBoundsException - if an attempt is made to reference a slot outside of the valid range