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: IDeclaredExceptionTable.java,v 1.1.1.1.2.1 2004/07/10 03:34:52 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 {@link ExceptionsAttribute_info}
16 * structure. It is a table of unsigned 16-bit indexes into constant pool. Each
17 * index points to a {@link com.vladium.jcd.cls.constant.CONSTANT_Class_info}
18 * entry representing an exception a method can throw [in unspecified order].
19 *
20 * @author (C) 2001, Vlad Roubtsov
21 */
22public
23interface IDeclaredExceptionTable extends Cloneable, IClassFormatOutput
24{
25    // public: ................................................................
26
27    // ACCESSORS:
28
29    /**
30     * Returns the {@link com.vladium.jcd.cls.constant.CONSTANT_Class_info} constant
31     * pool index for offset'th exception type thrown by the method that contains
32     * this this exception index table in its ExceptionsAttribute_info attribute.
33     *
34     * @param offset thrown exception class number [must be in [0, size()) range]
35     * @return constant pool index [always positive]
36     *
37     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
38     */
39    int get (int offset);
40
41    /**
42     * Returns the number of exception types the containing method professes
43     * to throw.
44     */
45    int size ();
46
47    /**
48     * Returns the total length of this table when converted to
49     * .class format [including 2 count bytes]
50     */
51    long length ();
52
53    // Cloneable: adjust the access level of Object.clone():
54    Object clone ();
55
56
57    // MUTATORS:
58
59    /**
60     * Appends a new exception class pointer to the collection. No duplicate checks
61     * are made.
62     *
63     * @param exception_index constant pool index [must be positive; input not validated]
64     * @return offset of the new pointer [same as {@link #size()}-1 when called
65     * after this method]
66     */
67    int add (int exception_index);
68
69    /**
70     * Replaces exception class pointer number 'offset' with new value 'interface_index'.
71     * No duplicate checks are made. It is the responsibility of the caller to
72     * ensure that the relevant CONSTANT_Class_info descriptor will be found
73     * in the constant pool, in the slot pointed to by 'exception_index'.
74     *
75     * @param offset thrown exception class number [must be in [0, size()) range]
76     * @param exception_index constant pool index [must be positive; input not validated]
77     * @return previous value at the given index [always positive]
78     *
79     * @throws IndexOutOfBoundsException if 'offset' is outside of valid range
80     */
81    int set (int offset, int exception_index);
82
83} // end of interface
84// ----------------------------------------------------------------------------
85