ExceptionalGraph


1   /* Soot - a J*va Optimization Framework
2    * Copyright (C) 2004 John Jorgensen
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 2.1 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the
16   * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17   * Boston, MA 02111-1307, USA.
18   */
19  
20  /*
21   * Modified by the Sable Research Group and others 1997-2004.  
22   * See the 'credits' file distributed with Soot for the complete list of
23   * contributors.  (Soot is distributed at http://www.sable.mcgill.ca/soot)
24   */
25  
26  
27   
28  
29  
30  
31  package soot.toolkits.graph;
32  
33  import soot.toolkits.graph.DirectedGraph;
34  import soot.Body;
35  import soot.Trap;
36  import java.util.List  ;
37  import java.util.Collection  ;
38  import soot.toolkits.exceptions.ThrowableSet;
39  
40  
41  /**
42   *  <p>Defines the interface for navigating a control flow graph which
43   *  distinguishes exceptional control flow.</p>
44   */
45  public interface ExceptionalGraph extends DirectedGraph
46  {
47      /**
48       * <p>Data structure to represent the fact that
49       * a given {@link Trap} will catch some subset of the exceptions
50       * which may be thrown by a given graph node.</p>
51       *
52       * <p>Note that these ``destinations'' are different from the
53       * edges in the CFG proper which are returned by
54       * <code>getSuccsOf()</code> and <code>getPredsOf()</code>. An
55       * edge from <code>a</code> to <code>b</code> in the CFG
56       * represents the fact that after node <code>a</code> executes
57       * (perhaps only partially, if it throws an exception after
58       * producing a side effect), execution may proceed to
59       * node <code>b</code>.  An ExceptionDest from <code>a</code> to
60       * <code>b</code>, on the other hand, says that when
61       * <code>a</code> fails to execute, execution may proceed
62       * to <code>b</code> instead.</p>
63       */
64      public interface ExceptionDest {
65  
66      /**
67       * Returns the trap corresponding to this destination.
68       *
69       * @return either a {@link Trap} representing the handler that
70       * catches the exceptions, if there is such a handler within
71       * the method, or <code>null</code> if there is no such
72       * handler and the exceptions cause the method to terminate
73       * abruptly.
74       */
75      public Trap getTrap();
76  
77      /**
78       * Returns the exceptions thrown to this destination.
79       *
80       * @return a {@link ThrowableSet} representing
81       * the exceptions which may be caught by this 
82       * <code>ExceptionDest</code>'s trap.
83       */
84      public ThrowableSet getThrowables();
85  
86      /**
87       * Returns the CFG node corresponding to the beginning of
88       * the exception handler that catches the exceptions (that is,
89       * the node that includes {@link trap().getBeginUnit()}).
90       *
91       * @return the node in this graph which represents the
92       * beginning of the handler which catches these exceptions, or
93       * <code>null</code> if there is no such handler and the
94       * exceptions cause the method to terminate abruptly.
95       */
96      // Maybe we should define an interface for Unit and Block to
97      // implement, and return an instance of that, rather than
98      // an Object.  We chose Object because that's what DirectedGraph
99      // deals in.
100     public Object   getHandlerNode();
101     }
102 
103 
104     /**
105      * Returns the {@link Body} from which this graph was built.
106      *
107      * @return the <code>Body</code> from which this graph was built.
108      */
109     public Body getBody();
110 
111 
112     /**
113      * Returns a list of nodes which are predecessors of a given
114      * node when only unexceptional control flow is considered.
115      *
116      * @param n The node whose predecessors are to be returned.
117      *
118      * @return a {@link List} of the nodes in this graph from which
119      *         there is an unexceptional edge to <code>n</code>.
120      */
121     public List   getUnexceptionalPredsOf(Object   n);
122 
123 
124     /**
125      * Returns a list of nodes which are successors of a given
126      * node when only unexceptional control flow is considered.
127      *
128      * @param n The node whose successors are to be returned.
129      *
130      * @return a {@link List} of nodes in this graph to which 
131      *         there is an unexceptional edge from <code>n</code>.
132      */
133     public List   getUnexceptionalSuccsOf(Object   n);
134 
135 
136     /**
137      * Returns a list of nodes which are predecessors of a given
138      * node when only exceptional control flow is considered.
139      *
140      * @param n The node whose predecessors are to be returned.
141      *
142      * @return a {@link List} of nodes in this graph from which 
143      *         there is an exceptional edge to <code>n</code>.
144      */
145     public List   getExceptionalPredsOf(Object   n);
146 
147 
148     /**
149      * Returns a list of nodes which are successors of a given
150      * node when only exceptional control flow is considered.
151      *
152      * @param n The node whose successors are to be returned.
153      *
154      * @return a {@link List} of nodes in this graph to which 
155      *         there is an exceptional edge from <code>n</code>.
156      */
157     public List   getExceptionalSuccsOf(Object   n);
158 
159 
160     /**
161      * Returns a collection of 
162      * {@link ExceptionalGraph.ExceptionDest ExceptionDest}
163      * objects which represent how exceptions thrown by a specified
164      * node will be handled.
165      *
166      * @param n The node for which to provide exception information.
167      *
168      * @return a collection of <code>ExceptionDest</code> objects describing
169      *         the traps and handlers, if any, which catch the exceptions
170      *         which may be thrown by <code>n</code>.
171      */
172     public Collection   getExceptionDests(Object   n);
173 }
174
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags