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: IExceptionHandlerTable.java,v 1.1.1.1 2004/05/09 16:57:48 vlad_r Exp $
8 */
9package com.vladium.jcd.cls.attribute;
10
11import com.vladium.jcd.compiler.IClassFormatOutput;
12
13// ----------------------------------------------------------------------------
14/**
15 * This table is a structure nested within the {@link CodeAttribute_info}.
16 * It is a table of {@link Exception_info} entries, each entry representing an
17 * exception handler range. The order of these entries is the order in which
18 * a JVM will check for a matching exception handler when the parent method
19 * throws an exception.
20 *
21 * @author (C) 2001, Vlad Roubtsov
22 */
23public
24interface IExceptionHandlerTable extends Cloneable, IClassFormatOutput
25{
26    // public: ................................................................
27
28    // ACCESSORS:
29
30    /**
31     * Returns {@link Exception_info} descriptor at a given offset.
32     *
33     * @param offset exception offset [must be in [0, size()) range; input not checked]
34     * @return Exception_info descriptor [never null]
35     *
36     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
37     */
38    Exception_info get (int offset);
39
40    /**
41     * Returns the number of descriptors in this collection [can be 0].
42     */
43    int size ();
44
45    /**
46     * Returns the total length of this table when converted to
47     * .class format [including 2 count bytes]
48     */
49    long length ();
50
51    // Cloneable: adjust the access level of Object.clone():
52    Object clone ();
53
54
55    // MUTATORS:
56
57    /**
58     * Adds a new Exception_info descriptor to this collection. No duplicate
59     * checks are made. It is the responsibility of the caller to ensure
60     * that all data referenced in 'exception' will eventually be consistent
61     * with method's bytecode and the class's constant pool.
62     *
63     * @param exception new exception descriptor [may not be null]
64     */
65    int add (Exception_info exception);
66
67    /**
68     * Replaces the Exception_info descriptor at a given offset. No duplicate
69     * checks are made. No exception type compatibility checks are made. It is
70     * the responsibility of the caller to ensure that all data referenced
71     * in 'exception' will eventually be consistent with method's bytecode and
72     * the class's constant pool.
73     *
74     * @param offset exception offset [must be in [0, size()) range; input not checked]
75     * @param exception new exception descriptor [may not be null]
76     * @return previous exception descriptor at this offset [never null]
77     *
78     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
79     */
80    Exception_info set (int offset, Exception_info exception);
81
82} // end of interface
83// ----------------------------------------------------------------------------
84