ThrowableSet (Soot API)

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

```
public final class ThrowableSet
extends java.lang.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

Nested Classes
Modifier and Type	Class and Description
`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

Methods
Modifier and Type	Method and Description
`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`.
`boolean`	`equals(java.lang.Object obj)`
`int`	`hashCode()`
`java.lang.String`	`toAbbreviatedString()` Produce an abbreviated representation of this `ThrowableSet`, suitable for human consumption.
`java.lang.String`	`toBriefString()` Returns a cryptic identifier for this `ThrowableSet`, used to identify a set when it appears in a collection.
`java.lang.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, finalize, getClass, 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 java.lang.String toString()
```
    Returns a string representation of this ThrowableSet.
    
    Overrides:
    
    toString in class java.lang.Object
  - toBriefString
```
public java.lang.String toBriefString()
```
    Returns a cryptic identifier for this ThrowableSet, used to identify a set when it appears in a collection.
  - toAbbreviatedString
```
public java.lang.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.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Overrides:
    
    equals in class java.lang.Object

Class ThrowableSet

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

add

add

add

catchableAs

whichCatchableAs

toString

toBriefString

toAbbreviatedString

hashCode

equals