/*
 * Copyright (c) 2002 - 2014 IBM Corporation.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 */

package com.ibm.wala.cfg.exc;

import com.ibm.wala.cfg.ControlFlowGraph;
import com.ibm.wala.cfg.IBasicBlock;
import com.ibm.wala.cfg.exc.intra.NullPointerState;
import com.ibm.wala.util.CancelException;
import com.ibm.wala.util.MonitorUtil.IProgressMonitor;
import com.ibm.wala.util.graph.GraphIntegrity.UnsoundGraphException;

/**
 * This abstract class is used as interface for analysis that remove impossible control flow from a
 * CFG. This is done by detecting exceptions that may always (or never) appear.
 *
 * @author Juergen Graf &lt;graf@kit.edu&gt;
 */
public interface ExceptionPruningAnalysis<I, T extends IBasicBlock<I>> {

  /**
   * Computes impossible control flow that is due to exceptions that definitely will not appear or
   * that will always be thrown. You have to run this method before using getPruned() to extract the
   * result of the analysis.
   *
   * @param progress A progress monitor that is used to display the progress of the analysis. It can
   *     also be used to detect a cancel request from the user. The common behavior is to cancel the
   *     method if progress.isCanceled() is true by throwing a CancelException.
   * @return Number of edges that have been removed from the cfg.
   * @throws UnsoundGraphException Thrown if the original CFG contains inconsistencies.
   * @throws CancelException Thrown if the user requested cancellation through the progress monitor.
   */
  int compute(IProgressMonitor progress) throws UnsoundGraphException, CancelException;

  /**
   * Returns the result of the analysis: A control flow graph where impossible control flow has been
   * removed. The way how and which impossible flow is detected may vary between different
   * implementations of this class. Run compute(IProgressMonitor) first.
   *
   * @return The improved CFG without edges that were detected as impossible flow.
   */
  ControlFlowGraph<I, T> getCFG();

  /**
   * Returns true if the corresponding method contains instructions that may throw an exception
   * which is not caught in the same method. Run compute(IPrograssMonitor) first.
   *
   * @return true if the corresponding method contains instructions that may throw an exception
   *     which is not caught in the same method
   */
  boolean hasExceptions();

  /**
   * Returns the state of a node. The node has to be part of the cfg.
   *
   * @param bb Node
   * @return NullPointerState
   */
  NullPointerState getState(T bb);
}
