001: /*
002: * Bytecode Analysis Framework
003: * Copyright (C) 2003-2005 University of Maryland
004: *
005: * This library is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU Lesser General Public
007: * License as published by the Free Software Foundation; either
008: * version 2.1 of the License, or (at your option) any later version.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General Public
016: * License along with this library; if not, write to the Free Software
017: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018: */
019:
020: package edu.umd.cs.findbugs.ba;
021:
022: import org.apache.bcel.generic.ConstantPoolGen;
023: import org.apache.bcel.generic.InstructionHandle;
024:
025: /**
026: * A ResourceTracker is used with ResourceValueAnalysis to determine
027: * where in a method a certain kind of resource is created, and
028: * to model the effect of instructions on the state of that resource.
029: *
030: * @author David Hovemeyer
031: * @see ResourceValueAnalysis
032: */
033: public interface ResourceTracker<Resource> {
034: /**
035: * Determine if the given instruction is the site where a resource
036: * is created.
037: *
038: * @param basicBlock basic block containing the instruction
039: * @param handle the instruction
040: * @param cpg the ConstantPoolGen for the method
041: * @return an opaque Resource object if it is a creation site, or
042: * null if it is not a creation site
043: */
044: public Resource isResourceCreation(BasicBlock basicBlock,
045: InstructionHandle handle, ConstantPoolGen cpg)
046: throws DataflowAnalysisException;
047:
048: /**
049: * Determine if the given instruction is the site where a resource
050: * is closed.
051: *
052: * @param basicBlock basic block containing the instruction
053: * @param handle the instruction
054: * @param cpg the ConstantPoolGen for the method
055: * @param resource the resource, as returned by isResourceCreation()
056: * @param frame the ResourceValueFrame representing the stack prior to executing
057: * the instruction
058: * @return true if the resource is closed here, false otherwise
059: */
060: public boolean isResourceClose(BasicBlock basicBlock,
061: InstructionHandle handle, ConstantPoolGen cpg,
062: Resource resource, ResourceValueFrame frame)
063: throws DataflowAnalysisException;
064:
065: /**
066: * Create a ResourceValueFrameModelingVisitor to model the effect
067: * of instructions on the state of the resource.
068: *
069: * @param resource the resource we are tracking
070: * @param cpg the ConstantPoolGen of the method
071: * @return a ResourceValueFrameModelingVisitor
072: */
073: public ResourceValueFrameModelingVisitor createVisitor(
074: Resource resource, ConstantPoolGen cpg);
075:
076: /**
077: * Determine whether the analysis should ignore exception edges
078: * on which only implicit exceptions are propagated.
079: * This allows different resource types to be tracked
080: * with varying precision. For example, we might want
081: * to ignore implicit exceptions for stream objects,
082: * but treat them as significant for database resources.
083: *
084: * @param resource the resource being tracked
085: * @return true if implicit exceptions are significant,
086: * false if they should be ignore
087: */
088: public boolean ignoreImplicitExceptions(Resource resource);
089:
090: /**
091: * Determine whether the analysis should ignore given exception edge.
092: * This allows the analysis to customize which kinds of exceptions are
093: * significant.
094: *
095: * @param edge the exception edge
096: * @param resource the resource
097: * @param cpg the ConstantPoolGen
098: * @return true if exception edge should be ignored, false if it should be considered
099: */
100: public boolean ignoreExceptionEdge(Edge edge, Resource resource,
101: ConstantPoolGen cpg);
102:
103: /**
104: * Return if the given parameter slot contains the
105: * resource instance upon entry to the method.
106: * This is for resources passed as parameters.
107: *
108: * @param resource the resource
109: * @param slot the local variable slot
110: * @return true if the slot contains the resource instance,
111: * false otherwise
112: */
113: public boolean isParamInstance(Resource resource, int slot);
114: }
115:
116: // vim:ts=4
|