| /* Copyright (C) 2003 Vladimir Roubtsov. All rights reserved. |
| * |
| * This program and the accompanying materials are made available under |
| * the terms of the Common Public License v1.0 which accompanies this distribution, |
| * and is available at http://www.eclipse.org/legal/cpl-v10.html |
| * |
| * $Id: IConstantCollection.java,v 1.1.1.1 2004/05/09 16:57:46 vlad_r Exp $ |
| */ |
| package com.vladium.jcd.cls; |
| |
| import com.vladium.jcd.cls.constant.*; |
| import com.vladium.jcd.compiler.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 |
| */ |
| public |
| interface IConstantCollection extends Cloneable, IClassFormatOutput |
| { |
| // public: ................................................................ |
| |
| /** |
| * A custom fail-fast iterator class returned by {@link IConstantCollection#iterator()}. |
| * It allows iterating over all entries in a way that steps over all |
| * 'invalid' inner slots (extra slots consumed by CONSTANT_Long and |
| * CONSTANT_Double entries). |
| */ |
| interface IConstantIterator |
| { |
| /** |
| * Returns the next entry slot index. |
| * |
| * @return int next valid slot index [always positive for a valid slot; |
| * -1 when the enumeration is exhausted] |
| */ |
| public int nextIndex (); |
| |
| /** |
| * Returns the next entry. This is a convenience method for doing |
| * get(nextIndex()) and avoiding index bound violation exceptions. |
| * |
| * @return CONSTANT_info next valid entry [null when the enumeration is |
| * exhausted] |
| */ |
| public CONSTANT_info nextConstant (); |
| |
| /** |
| * A convenience method that is equivalent to {@link IConstantCollection#set} |
| * and replaces the entry that was visited last without invalidating |
| * the iterator. |
| */ |
| CONSTANT_info set (CONSTANT_info constant); |
| |
| } // end of nested interface |
| |
| |
| /** |
| * A simple interface to express custom semantics of constant equality. |
| * |
| * @see IConstantCollection#find(int, IConstantComparator) |
| */ |
| interface IConstantComparator |
| { |
| boolean equals (CONSTANT_info constant); |
| |
| } // end of nested interface |
| |
| |
| // ACCESSORS: |
| |
| /** |
| * 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 {@link #iterator()} to iterate only over valid entries |
| * in a transparent fashion. |
| * |
| * @param index constant pool index [must be in [1, size()] range] |
| * @return CONSTANT_info constant pool entry at this index [never null] |
| * |
| * @throws IllegalStateException if an attempt is made to reference |
| * an invalid slot index |
| * @throws IndexOutOfBoundsException if an attempt is made to reference |
| * a slot outside of the valid range |
| */ |
| CONSTANT_info get (int index); |
| |
| /** |
| * 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. |
| * |
| * @return IConstantIterator iterator over all entries in the collection [never null] |
| */ |
| IConstantIterator iterator (); |
| |
| /** |
| * 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). |
| * |
| * @param type type of constants to filter by [not validated] |
| * @param comparator [may not be null] |
| * @return index of the first found entry [-1 if not found] |
| * |
| * @throws IllegalArgumentException if 'comparator' is null |
| */ |
| int find (int type, IConstantComparator comparator); |
| |
| /** |
| * 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). |
| * |
| * @param value string value on which to match [may not be null] |
| * @return index of the first found entry [-1 if not found] |
| * |
| * @throws IllegalArgumentException if 'value' is null |
| */ |
| int findCONSTANT_Utf8 (String value); |
| |
| /** |
| * Returns the number of CONSTANT_info entries in this collection. |
| * |
| * @return the number of constants in this pool [can be 0] |
| */ |
| int size (); |
| |
| // Cloneable: adjust the access level of Object.clone(): |
| Object clone (); |
| |
| // Visitor: |
| void accept (IClassDefVisitor visitor, Object ctx); |
| |
| |
| // MUTATORS: |
| |
| /** |
| * Appends 'constant' to the end of the collection. No duplicate checks |
| * are made. |
| * |
| * @param constant new constant [may not be null; input unchecked] |
| * @return the pool index of the newly added entry [always positive] |
| */ |
| int add (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. |
| * |
| * @param index constant pool index [must be in [1, size()] range] |
| * @param constant new entry to set [may not be null; input unchecked] |
| * @return CONSTANT_info previous contents at this pool index [never null] |
| * |
| * @throws IllegalArgumentException if the new constant's width is different |
| * from the current entry's |
| * @throws IllegalStateException if an attempt is made to reference |
| * an invalid slot index [see {@link #get(int)}] |
| * @throws IndexOutOfBoundsException if an attempt is made to reference |
| * a slot outside of the valid range |
| */ |
| CONSTANT_info set (int index, CONSTANT_info constant); |
| |
| } // end of interface |
| // ---------------------------------------------------------------------------- |