001/*
002 * Cobertura - http://cobertura.sourceforge.net/
003 *
004 * Copyright (C) 2011 Piotr Tabor
005 *
006 * Note: This file is dual licensed under the GPL and the Apache
007 * Source License (so that it can be used from both the main
008 * Cobertura classes and the ant tasks).
009 *
010 * Cobertura is free software; you can redistribute it and/or modify
011 * it under the terms of the GNU General Public License as published
012 * by the Free Software Foundation; either version 2 of the License,
013 * or (at your option) any later version.
014 *
015 * Cobertura is distributed in the hope that it will be useful, but
016 * WITHOUT ANY WARRANTY; without even the implied warranty of
017 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
018 * General Public License for more details.
019 *
020 * You should have received a copy of the GNU General Public License
021 * along with Cobertura; if not, write to the Free Software
022 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
023 * USA
024 */
025
026package net.sourceforge.cobertura.instrument;
027
028import org.objectweb.asm.Label;
029import org.objectweb.asm.MethodVisitor;
030
031/**
032 * <p>Interfaces of listener that is called if interesting 'place' is found in instrumented/analyzed code</p>
033 * 
034 * It is guaranteed that the same 'eventIds' will be used for the same events (in the case of identical source byte-code), 
035 * so you can use this ids to identify the same places between different passes of instrumentation.   
036 * 
037 * @author piotr.tabor@gmail.com
038 */
039public interface TouchPointListener {
040        /**
041         * Event called when a new method have been just started for instrumentation. It is called
042         * after method declaration has been read, but before 'a real' code has been processed.  
043         * 
044         * @param nextMethodVisitor  - sink for instrumented code 
045         */
046        public void afterMethodStart(MethodVisitor nextMethodVisitor);
047        
048        /**
049         * <p>Before code responsible for realizing 'interesting' JUMP </p>
050         * 
051         * <p>JUMP event is not called in case of GOTO and RETURN instruction (not conditional JUMPS)</p>
052         * 
053         * @param eventId     - id of the detected event. 
054         * @param label       - destination label of the jump 
055         * @param currentLine - number of currently visited line
056         * @param nextMethodVisitor - sink for instrumented code
057         */
058        public void afterJump(int eventId, Label label,int currentLine, MethodVisitor nextMethodVisitor);
059        
060        /**
061         * <p>Called after code responsible for realizing 'interesting' JUMP </p>
062         * 
063         * <p>JUMP event is not called in case of GOTO and RETURN instruction (not conditional JUMPS)</p>
064         * 
065         * @param eventId     - id of the detected event. 
066         * @param label       - destination label of the jump 
067         * @param currentLine - number of currently visited line
068         * @param nextMethodVisitor - sink for instrumented code
069         */
070        public void beforeJump(int eventId, Label label,int currentLine, MethodVisitor nextMethodVisitor);
071        
072        /**
073         * after LINENUMBER instruction was processed. 
074         * 
075         * @param eventId            - id of the detected event.
076         * @param label              - label connected to the line 
077         * @param currentLine        - number of currently visited line
078         * @param nextMethodVisitor  - sink for instrumented code
079         * @param methodName         - name  of currently being instrumented method
080         * @param methodSignature    - signature (params and returned value type) of currently being instrumented method 
081         */
082        public void afterLineNumber(int eventId,Label label, int currentLine, MethodVisitor nextMethodVisitor,String methodName, String methodSignature);
083        
084        /**
085         * <p>If we determined that some line should be not 'counted' by cobertura (for example the line might be specified in {@link AbstractFindTouchPointsClassInstrumenter#ignoreRegexp})
086         * we call this method.</p>   
087         * 
088         * It's possible that {@link #afterLineNumber(int, Label, int, MethodVisitor, String, String)} event will be (or has been already) fired.
089         * 
090         * @param eventId            - id of the event connected to the line (the same eventId that might be used for the line in {@link #afterLineNumber(int, Label, int, MethodVisitor, String, String)})  
091         * @param currentLine            - number of line that should be ignored. 
092         */
093        public void ignoreLine(int eventId,int currentLine);
094        
095        /**
096         * Called befere processing switch statement. 
097         * 
098         * @param eventId     - id of the detected event.
099         * @param def         - label of 'default' target label that will be used when none of given values match the switch 
100         * @param labels      - table of labels connected to switch 'values' (different switch branches). There might be duplicates in the table (fall-through in switch statement)
101         * @param currentLine - number of line in which the 'switch' keyword has been found (number of line currently being processed)  
102         * @param mv          - sink for instrumented (injected) code
103         * @param conditionType - NULL (if undetected) or signature of variable used as a switch condition.      *                                               
104         */
105        public void beforeSwitch(int eventId,Label def, Label[] labels, int currentLine, MethodVisitor mv, String conditionType);
106        
107        /**
108         * Called before processing 'label' directive
109         * 
110         * @param eventId     - id of the detected event.
111         * @param label       - internal identifier of label being found (single pass of instrumentation valid only)
112         * @param currentLine - number of line in which the 'switch' keyword has been found (number of line currently being processed)  
113         * @param mv          - sink for instrumented (injected) code
114         */
115        public void beforeLabel(int eventId, Label label, int currentLine, MethodVisitor mv);
116
117        /**
118         * Called before processing 'label' directive
119         * 
120         * @param eventId     - id of the detected event.
121         * @param label       - internal identifier of label being found (single pass of instrumentation valid only)
122         * @param currentLine - number of line in which the 'switch' keyword has been found (number of line currently being processed)  
123         * @param mv          - sink for instrumented (injected) code
124         */
125        public void afterLabel(int eventId,Label label, int currentLine, MethodVisitor mv);
126
127}