1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
/* 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
// ----------------------------------------------------------------------------
|
