/*
 * Bytecode Analysis Framework
 * Copyright (C) 2003-2007 University of Maryland
 * 
 * This library 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 library 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
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package edu.umd.cs.findbugs.ba;

import org.apache.bcel.generic.InstructionHandle;

import edu.umd.cs.findbugs.annotations.CheckForNull;

/**
 * A dataflow analysis to be used with the {@link Dataflow} class.
 * 
 * <p>
 * In order to avoid duplicating
 * functionality (such as caching of start and result facts),
 * most analyses should extend the {@link BasicAbstractDataflowAnalysis}
 * or {@link AbstractDataflowAnalysis} classes rather than
 * directly implementing this interface.
 * </p>
 *
 * @author David Hovemeyer
 * @see Dataflow
 */
public interface DataflowAnalysis <Fact> {
	/**
	 * Create empty (uninitialized) dataflow facts for one program point.
	 * A valid value will be copied into it before it is used.
	 */
	public Fact createFact();

	/**
	 * Get the start fact for given basic block.
	 *
	 * @param block the basic block
	 */
	public Fact getStartFact(BasicBlock block);

	/**
	 * Get the result fact for given basic block.
	 *
	 * @param block the basic block
	 */
	public Fact getResultFact(BasicBlock block);
	
	/**
	 * Get dataflow fact at (just before) given Location.
	 * Note "before" is meant in the logical sense, so for backward analyses,
	 * before means after the location in the control flow sense.
	 * 
	 * @param location the Location
	 * @return the dataflow value at given Location
	 * @throws DataflowAnalysisException
	 */
	public Fact getFactAtLocation(Location location) throws DataflowAnalysisException;
	
	/**
	 * Get the dataflow fact representing the point just after given Location.
	 * Note "after" is meant in the logical sense, so for backward analyses,
	 * after means before the location in the control flow sense.
	 * 
	 * @param location the Location
	 * @return the dataflow value after given Location
	 * @throws DataflowAnalysisException
	 */
	public Fact getFactAfterLocation(Location location) throws DataflowAnalysisException;
	
	/**
	 * Get the fact that is true on the given control edge.
	 * 
	 * @param edge the edge
	 * @return the fact that is true on the edge
	 * @throws DataflowAnalysisException 
	 */
	public Fact getFactOnEdge(Edge edge) throws DataflowAnalysisException;

	/**
	 * Copy dataflow facts.
	 */
	public void copy(Fact source, Fact dest);

	/**
	 * Initialize the "entry" fact for the graph.
	 */
	public void initEntryFact(Fact result) throws DataflowAnalysisException;

	/**
	 * Make given fact the top value.
	 */
	public void makeFactTop(Fact fact);

	/**
	 * Is the given fact the top value.
	 */
	public boolean isTop(Fact fact);
	/**
	 * Returns true if the analysis is forwards, false if backwards.
	 */
	public boolean isForwards();

	/**
	 * Return the BlockOrder specifying the order in which BasicBlocks
	 * should be visited in the main dataflow loop.
	 *
	 * @param cfg the CFG upon which we're performing dataflow analysis
	 */
	public BlockOrder getBlockOrder(CFG cfg);

	/**
	 * Are given dataflow facts the same?
	 */
	public boolean same(Fact fact1, Fact fact2);

	/**
	 * Transfer function for the analysis.
	 * Taking dataflow facts at start (which might be either the entry or
	 * exit of the block, depending on whether the analysis is forwards
	 * or backwards), modify result to be the facts at the other end
	 * of the block.
	 *
	 * @param basicBlock the basic block
	 * @param end        if nonnull, stop before considering this instruction;
	 *                   otherwise, consider all of the instructions in the basic block
	 * @param start      dataflow facts at beginning of block (if forward analysis)
	 *                   or end of block (if backwards analysis)
	 * @param result     resulting dataflow facts at other end of block
	 */
	public void transfer(BasicBlock basicBlock, @CheckForNull InstructionHandle end, Fact start, Fact result) throws DataflowAnalysisException;

	/**
	 * Edge transfer function.
	 * Modify the given fact that is true on the (logical) edge source
	 * to modify it so that it is true at the (logical) edge target.
	 * 
	 * <p>
	 * A do-nothing implementation is legal, and appropriate for
	 * analyses where branches are not significant.
	 * </p>
	 * 
	 * @param edge the Edge
	 * @param fact a dataflow fact
	 * @throws DataflowAnalysisException
	 */
	public void edgeTransfer(Edge edge, Fact fact) throws DataflowAnalysisException;

	/**
	 * Meet a dataflow fact associated with an incoming edge into another fact.
	 * This is used to determine the start fact for a basic block.
	 *
	 * @param fact   the predecessor fact (incoming edge)
	 * @param edge   the edge from the predecessor
	 * @param result the result fact
	 */
	public void meetInto(Fact fact, Edge edge, Fact result) throws DataflowAnalysisException;

	/**
	 * Called before beginning an iteration of analysis.
	 * Each iteration visits every basic block in the CFG.
	 */
	public void startIteration();

	/**
	 * Called after finishing an iteration of analysis. 
	 */
	public void finishIteration();

	public int getLastUpdateTimestamp(Fact fact);

	public void setLastUpdateTimestamp(Fact fact, int timestamp);
	
	/**
	 * Return a String representation of given Fact.
	 * For debugging purposes.
	 * 
	 * @param fact a dataflow fact
	 * @return String representation of the fact
	 */
	public String factToString(Fact fact);
}

// vim:ts=4