soot.toolkits.exceptions.ThrowAnalysis Maven / Gradle / Ivy

package soot.toolkits.exceptions;

/*-
 * #%L
 * Soot - a J*va Optimization Framework
 * %%
 * Copyright (C) 2003 John Jorgensen
 * %%
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 2.1 of the
 * License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Lesser Public License for more details.
 * 
 * You should have received a copy of the GNU General Lesser Public
 * License along with this program.  If not, see
 * .
 * #L%
 */

import soot.Unit;
import soot.baf.ThrowInst;
import soot.jimple.ThrowStmt;

/**
 * 
 * A source of information about the exceptions that {@link Unit}s might throw.
 * 
 *
 * 
 * The Units corresponding to athrow instructions may throw exceptions either
 * explicitly—because the exception is the athrow's argument— or implicitly—because some error
 * arises in the course of executing the instruction (only implicit exceptions are possible for bytecode instructions other
 * than athrow). The mightThrowExplicitly() and mightThrowImplicitly() methods allow
 * analyses to exploit any extra precision that may be gained by distinguishing between an athrow's implicit and
 * explicit exceptions.
 * 
 */

public interface ThrowAnalysis {
  /**
   * Returns a set representing the {@link Throwable} types that the specified unit might throw.
   *
   * @param u
   *          {@link Unit} whose exceptions are to be returned.
   *
   * @return a representation of the Throwable types that u might throw.
   */
  ThrowableSet mightThrow(Unit u);

  /**
   * Returns a set representing the {@link Throwable} types that the specified throw instruction might throw explicitly, that
   * is, the possible types for its Throwable argument.
   *
   * @param t
   *          {@link ThrowInst} whose explicit exceptions are to be returned.
   *
   * @return a representation of the possible types of t's Throwable operand.
   */
  ThrowableSet mightThrowExplicitly(ThrowInst t);

  /**
   * Returns a set representing the {@link Throwable} types that the specified throw statement might throw explicitly, that
   * is, the possible types for its Throwable argument.
   *
   * @param t
   *          {@link ThrowStmt} whose explicit exceptions are to be returned.
   *
   * @return a representation of the possible types of t's Throwable operand.
   */
  ThrowableSet mightThrowExplicitly(ThrowStmt t);

  /**
   * Returns a set representing the {@link Throwable} types that the specified throw instruction might throw implicitly, that
   * is, the possible types of errors which might arise in the course of executing the throw instruction, rather
   * than the type of the throw's operand.
   *
   * @param t
   *          {@link ThrowStmt} whose implicit exceptions are to be returned.
   *
   * @return a representation of the types of exceptions that t might throw implicitly.
   */
  ThrowableSet mightThrowImplicitly(ThrowInst t);

  /**
   * Returns a set representing the {@link Throwable} types that the specified throw statement might throw implicitly, that
   * is, the possible types of errors which might arise in the course of executing the throw statement, rather
   * than the type of the throw's operand.
   *
   * @param t
   *          {@link ThrowStmt} whose implicit exceptions are to be returned.
   *
   * @return a representation of the types of exceptions that t might throw implicitly.
   */
  ThrowableSet mightThrowImplicitly(ThrowStmt t);

}