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: IMethodCollection.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 'methods' component of .class format. The contents
16 * are {@link Method_info} structures corresponding to all methods 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 IMethodCollection extends Cloneable, IClassFormatOutput
24{
25    // public: ................................................................
26
27    // ACCESSORS:
28
29    /**
30     * Returns {@link Method_info} descriptor at a given offset.
31     *
32     * @param offset method offset [must be in [0, size()) range; input not checked]
33     * @return Method_info descriptor [never null]
34     *
35     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
36     */
37    Method_info get (int offset);
38
39    /**
40     * Returns an array of offsets for methods named 'name' (empty array if no
41     * matching fields found).
42     *
43     * @param cls class definition providing the constant pool against which to
44     * resolve names [may not be null]
45     * @param name method name [null or empty will result in no matches]
46     * @return array of method offsets in no particular order [never null; could be empty]
47     *
48     * @throws IllegalArgumentException if 'cls' is null
49     */
50    int [] get (ClassDef cls, String name);
51
52    /**
53     * Returns the number of methods in this collection [can be 0].
54     */
55    int size ();
56
57    // Cloneable: adjust the access level of Object.clone():
58    Object clone ();
59
60    // Visitor:
61    void accept (IClassDefVisitor visitor, Object ctx);
62
63
64    // MUTATORS:
65
66    /**
67     * Adds a new Method_info descriptor to this collection. No duplicate
68     * checks are made. It is the responsibility of the caller to ensure
69     * that all data referenced in 'method' will eventually appear in the
70     * constant pool.
71     *
72     * @param method new method descriptor [may not be null]
73     */
74    int add (Method_info method);
75
76    /**
77     * Replaces the Method_info descriptor at a given offset. No duplicate
78     * checks are made. No method type compatibility checks are made.  It is
79     * the responsibility of the caller to ensure that all data referenced
80     * in 'method' will eventually appear in the constant pool.
81     *
82     * @param offset method offset [must be in [0, size()) range; input not checked]
83     * @param method new method descriptor [may not be null]
84     * @return previous method descriptor at this offset [never null]
85     *
86     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
87     */
88    Method_info set (int offset, Method_info method);
89
90    // TODO: support this via iterators instead
91    /**
92     * Removes the Method_info descriptor at a given offset. It is
93     * the responsibility of the caller to ensure that the class definition
94     * remains consistent after this change.
95     *
96     * @param offset method offset [must be in [0, size()) range; input not checked]
97     * @return method descriptor at this offset [never null]
98     *
99     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
100     */
101    Method_info remove (int offset);
102
103} // end of interface
104// ----------------------------------------------------------------------------
105