1/* Copyright (C) 2003 Vladimir Roubtsov. All rights reserved.
2 *
3 * This program and the accompanying materials are made available under
4 * the terms of the Common Public License v1.0 which accompanies this distribution,
5 * and is available at http://www.eclipse.org/legal/cpl-v10.html
6 *
7 * $Id: IFieldCollection.java,v 1.1.1.1 2004/05/09 16:57:46 vlad_r Exp $
8 */
9package com.vladium.jcd.cls;
10
11import com.vladium.jcd.compiler.IClassFormatOutput;
12
13// ----------------------------------------------------------------------------
14/**
15 * An abstraction of the 'fields' component of .class format. The contents
16 * are {@link Field_info} structures corresponding to all fields directly
17 * declared by this class/interface. The order in which they appear is
18 * unspecified.
19 *
20 * @author (C) 2001, Vlad Roubtsov
21 */
22public
23interface IFieldCollection extends Cloneable, IClassFormatOutput
24{
25    // public: ................................................................
26
27    // ACCESSORS:
28
29    /**
30     * Returns {@link Field_info} descriptor at a given offset.
31     *
32     * @param offset field offset [must be in [0, size()) range; input not checked]
33     * @return Field_info descriptor [never null]
34     *
35     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
36     */
37    Field_info get (int offset);
38
39    /**
40     * Returns an array of offsets for fields named 'name' (empty array if no
41     * matching fields found). Note: even though Java syntax disallows for a class
42     * to have multiple fields with the same name it is possible at the bytecode
43     * level (as long as the type descriptors disambiguate).
44     *
45     * @param cls class definition providing the constant pool against which to
46     * resolve names [may not be null]
47     * @param name field name [null or empty will result in no matches]
48     * @return array of field offsets in no particular order [never null; could be empty]
49     *
50     * @throws IllegalArgumentException if 'cls' is null
51     */
52    int [] get (ClassDef cls, String name);
53
54    /**
55     * Returns the number of fields in this collection [can be 0].
56     */
57    int size ();
58
59    // Cloneable: adjust the access level of Object.clone():
60    Object clone ();
61
62    // Visitor:
63    void accept (IClassDefVisitor visitor, Object ctx);
64
65
66    // MUTATORS:
67
68    /**
69     * Adds a new Field_info descriptor to this collection. No duplicate
70     * checks are made. It is the responsibility of the caller to ensure
71     * that all data referenced in 'field' will eventually appear in the
72     * constant pool.
73     *
74     * @param field new field descriptor [may not be null]
75     * @return new field's offset
76     */
77    int add (Field_info field);
78
79    /**
80     * Replaces the Field_info descriptor at a given offset. No duplicate
81     * checks are made. No field type compatibility checks are made.  It is
82     * the responsibility of the caller to ensure that all data referenced
83     * in 'field' will eventually appear in the constant pool.
84     *
85     * @param offset field offset [must be in [0, size()) range; input not checked]
86     * @param field new field descriptor [may not be null]
87     * @return previous field descriptor at this offset [never null]
88     *
89     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
90     */
91    Field_info set (int offset, Field_info field);
92
93} // end of interface
94// ----------------------------------------------------------------------------
95