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

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

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

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

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

int size()

Returns the number of CONSTANT_info entries in this collection.

Returns:

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

clone

java.lang.Object clone()

accept

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

add

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

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