soot.toolkits.exceptions
Class ThrowableSet

java.lang.Object
  soot.toolkits.exceptions.ThrowableSet

public final class ThrowableSet
extends Object

A class for representing the set of exceptions that an instruction may throw.

ThrowableSet does not implement the Set interface, so perhaps it is misnamed. Instead, it provides only the operations that we require for determining whether a given statement might throw an exception that would be caught by a given handler.

There is a limitation on the combinations of operations permitted on a ThrowableSet. The ThrowableSets returned by whichCatchableAs(RefType) cannot be involved in subsequent add() or whichCatchableAs() operations. That is, given

p = s.whichCatchableAs(r)

for any ThrowableSet s and RefType r, and

t == p.getUncaught() or t == p.getCaught()

then calls to t.add(r), t.add(a), and s.add(t), will throw an ThrowableSet.AlreadyHasExclusionsException, for any RefType r, AnySubType a, and ThrowableSet t.

Actually the restrictions implemented are not quite so strict (there are some combinations of whichCatchableAs() followed by add() which will not raise an exception), but a more accurate description would require reference to the internals of the current implementation. The restrictions should not be too onerous for ThrowableSet's anticipated uses: we expect ThrowableSets to grow by accumulating all the exception types that a given Unit may throw, then, shrink as the types caught by different exception handlers are removed to yield the sets representing exceptions which escape those handlers.

The ThrowableSet class is intended to be immutable (hence the final modifier on its declaration). It does not take the step of guaranteeing immutability by cloning the RefLikeType objects it contains, though, because we trust Scene to enforce the existence of only one RefLikeType instance with a given name.

Nested Class Summary

static class	ThrowableSet.AlreadyHasExclusionsException
static class	ThrowableSet.Manager Singleton class for fields and initializers common to all ThrowableSet objects (i.e., these would be static fields and initializers, in the absence of soot's G and Singletons classes).
static class	ThrowableSet.Pair The return type for whichCatchableAs(RefType), consisting of a pair of ThrowableSets.

Method Summary

ThrowableSet	add(AnySubType e) Returns a ThrowableSet which contains e and all of its subclasses as well as the exceptions in this set.
ThrowableSet	add(RefType e) Returns a ThrowableSet which contains e in addition to the exceptions in this ThrowableSet.
ThrowableSet	add(ThrowableSet s) Returns a ThrowableSet which contains all the exceptions in s in addition to those in this ThrowableSet.
boolean	catchableAs(RefType catcher) Indicates whether this ThrowableSet includes some exception that might be caught by a handler argument of the type catcher.
String	toAbbreviatedString() Produce an abbreviated representation of this ThrowableSet, suitable for human consumption.
String	toBriefString() Returns a cryptic identifier for this ThrowableSet, used to identify a set when it appears in a collection.
String	toString() Returns a string representation of this ThrowableSet.
ThrowableSet.Pair	whichCatchableAs(RefType catcher) Partitions the exceptions in this ThrowableSet into those which would be caught by a handler with the passed catch parameter type and those which would not.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

add

public ThrowableSet add(RefType e)
                 throws ThrowableSet.AlreadyHasExclusionsException

Returns a ThrowableSet which contains e in addition to the exceptions in this ThrowableSet.

Add e as a RefType when you know that the run-time class of the exception you are representing is necessarily e and cannot be a subclass of e.

For example, if you were recording the type of the exception thrown by

 throw new IOException("Permission denied");
 

you would call

 add(Scene.v().getRefType("java.lang.Exception.IOException"))
 

since the class of the exception is necessarily IOException.

Parameters:

e - the exception class

Returns:

a set containing e as well as the exceptions in this set.

Throws:

{@link - ThrowableSet.IllegalStateException} if this ThrowableSet is the result of a whichCatchableAs(RefType) operation and, thus, unable to represent the addition of e.

ThrowableSet.AlreadyHasExclusionsException

add

public ThrowableSet add(AnySubType e)
                 throws ThrowableSet.AlreadyHasExclusionsException

Returns a ThrowableSet which contains e and all of its subclasses as well as the exceptions in this set.

e should be an instance of AnySubType if you know that the compile-time type of the exception you are representing is e, but the exception may be instantiated at run-time by a subclass of e.

For example, if you were recording the type of the exception thrown by

 catch (IOException e) {
    throw e;
 }
 

you would call

 add(AnySubtype.v(Scene.v().getRefType("java.lang.Exception.IOException")))
 

since the handler might rethrow any subclass of IOException.

Parameters:

e - represents a subtree of the exception class hierarchy to add to this set.

Returns:

a set containing e and all its subclasses, as well as the exceptions represented by this set.

Throws:

ThrowableSet.AlreadyHasExclusionsException - if this ThrowableSet is the result of a whichCatchableAs(RefType) operation and, thus, unable to represent the addition of e.

add

public ThrowableSet add(ThrowableSet s)
                 throws ThrowableSet.AlreadyHasExclusionsException

Returns a ThrowableSet which contains all the exceptions in s in addition to those in this ThrowableSet.

Parameters:

s - set of exceptions to add to this set.

Returns:

the union of this set with s

Throws:

ThrowableSet.AlreadyHasExclusionsException - if this ThrowableSet or s is the result of a whichCatchableAs(RefType) operation, so that it is not possible to represent the addition of s to this ThrowableSet.

catchableAs

public boolean catchableAs(RefType catcher)

Indicates whether this ThrowableSet includes some exception that might be caught by a handler argument of the type catcher.

Parameters:

catcher - type of the handler parameter to be tested.

Returns:

true if this set contains an exception type that might be caught by catcher, false if it does not.

whichCatchableAs

public ThrowableSet.Pair whichCatchableAs(RefType catcher)

Partitions the exceptions in this ThrowableSet into those which would be caught by a handler with the passed catch parameter type and those which would not.

Parameters:

catcher - type of the handler parameter to be tested.

Returns:

a pair of ThrowableSets, one containing the types in this ThrowableSet which would be be caught as catcher and the other containing the types in this ThrowableSet which would not be caught as catcher.

toString

public String toString()

Returns a string representation of this ThrowableSet.

Overrides:

toString in class Object

toBriefString

public String toBriefString()

Returns a cryptic identifier for this ThrowableSet, used to identify a set when it appears in a collection.

toAbbreviatedString

public String toAbbreviatedString()

Produce an abbreviated representation of this ThrowableSet, suitable for human consumption. The abbreviations include:

• The strings “java.lang.” is stripped from the beginning of exception names.
• The string “Exception” is stripped from the ends of exception names.
• Instances of AnySubType are indicated by surrounding the base type name with parentheses, rather than with the string “Any_subtype_of_”
• If this ThrowableSet includes all the elements of VM_ERRORS, they are abbreviated as “vmErrors” rather than listed individually.

Returns:

An abbreviated representation of the contents of this set.