Package soot.toolkits.exceptions

Class ThrowableSet

  • public 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.

    • Field Detail

      • exceptionsIncluded

        protected final Set<RefLikeType> exceptionsIncluded
        Set of exception types included within the set.

      • exceptionsExcluded

        protected final Set<AnySubType> exceptionsExcluded
        Set of exception types which, though members of exceptionsIncluded, are to be excluded from the types represented by this ThrowableSet. To simplify the implementation, once a ThrowableSet has any excluded types, the various add() methods of this class must bar additions of subtypes of those excluded types.

      • memoizedAdds

        protected Map<Object,​ThrowableSet> memoizedAdds
        A map from (RefLikeType \\union ThrowableSet) to ThrowableSet. If the mapping (k,v) is in memoizedAdds and k is a ThrowableSet, then v is the set that results from adding all elements in k to this. If (k,v) is in memoizedAdds and k is a RefLikeType, then v is the set that results from adding k to this.

    • Constructor Detail

      • ThrowableSet

        protected ThrowableSet​(Set<RefLikeType> include,
                       Set<AnySubType> exclude)
        Constructs a ThrowableSet which contains the exception types represented in include, except for those which are also in exclude. The constructor is private to ensure that the only way to get a new ThrowableSet is by adding elements to or removing them from an existing set.
        Parameters:
        include - The set of RefType and AnySubType objects representing the types to be included in the set.
        exclude - The set of AnySubType objects representing the types to be excluded from the set.

    • 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:
        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.

      • isEmpty

        public boolean isEmpty()
        Returns true if the throwable set is empty and false otherwise.
        Returns:
        true if the throwable set is empty.

      • remove

        public ThrowableSet remove​(ThrowableSet s)
        Returns a ThrowableSet which contains all the exceptions from the current set except for those in the given ThrowableSet.
        Parameters:
        s - The set containing the exceptions to exclude from the new set
        Returns:
        The exceptions that are only in this set, but not in the given set
        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.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object