001    /*
002      Copyright (C) 2001 Renaud Pawlak
003    
004      This program is free software; you can redistribute it and/or modify
005      it under the terms of the GNU Lesser General Public License as
006      published by the Free Software Foundation; either version 2 of the
007      License, or (at your option) any later version.
008    
009      This program is distributed in the hope that it will be useful,
010      but WITHOUT ANY WARRANTY; without even the implied warranty of
011      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012      GNU Lesser General Public License for more details.
013    
014      You should have received a copy of the GNU Lesser General Public License
015      along with this program; if not, write to the Free Software
016      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */
017    
018    package org.objectweb.jac.aspects.tracing;
019    
020    /**
021     * This sample aspect component traces the calls on all the objects of
022     * the program.
023     *
024     * <p>To be active this aspect component must be configured with the
025     * <code>addTrace</code> method.
026     * @see TracingAC
027     * @see org.objectweb.jac.wrappers.VerboseWrapper */
028    
029    public interface TracingConf {
030    
031       /**
032        * This configuration method makes a method call to be traced by a
033        * verbose wrapper.
034        *
035        * By default no method is verbose.
036        *
037        * @param wrappeeExpr a regular expression that matches the
038        * wrappee(s) name(s) that contain the method(s) to be traced
039        * @param wrappeeClassExpr a regular expression that matches the
040        * wrappee(s) class(es) name(s) that contain the method(s) to be
041        * traced
042        * @param wrappeeMethodExpr a regular expression that matches the
043        * method(s) to be traced (within the classes or objects denoted by
044        * the previous parameters)
045        * @see org.objectweb.jac.wrappers.VerboseWrapper */
046    
047       void addTrace(String wrappeeExpr, 
048                     String wrappeeClassExpr, 
049                     String wrappeeMethodExpr);
050    
051       /**
052        * This configuration method makes a method call to be traced. The
053        * names of parameters are printed if configured by the Gui aspect.
054        *
055        * @param wrappeeExpr a regular expression that matches the
056        * wrappee(s) name(s) that contain the method(s) to be traced
057        * @param wrappeeClassExpr a regular expression that matches the
058        * wrappee(s) class(es) name(s) that contain the method(s) to be
059        * traced
060        * @param wrappeeMethodExpr a regular expression that matches the
061        * method(s) to be traced (within the classes or objects denoted by
062        * the previous parameters)
063        * @see org.objectweb.jac.wrappers.VerboseWrapper */
064       void addNamedTrace(String wrappeeExpr, 
065                          String wrappeeClassExpr, 
066                          String wrappeeMethodExpr);
067    
068       /**
069        * This configuration method makes a method call to be traced by a
070        * verbose wrapper. For each call, the stack is dumped.
071        *
072        * By default no method is verbose.
073        *
074        * @param wrappeeExpr a regular expression that matches the
075        * wrappee(s) name(s) that contain the method(s) to be traced
076        * @param wrappeeClassExpr a regular expression that matches the
077        * wrappee(s) class(es) name(s) that contain the method(s) to be
078        * traced
079        * @param wrappeeMethodExpr a regular expression that matches the
080        * method(s) to be traced (within the classes or objects denoted by
081        * the previous parameters)
082        * @see org.objectweb.jac.wrappers.VerboseWrapper */
083       void addStackTrace(String wrappeeExpr, 
084                          String wrappeeClassExpr, 
085                          String wrappeeMethodExpr);
086    
087    
088    
089       /**
090        * This configuration method makes a method call to be traced by a
091        * verbose wrapper. For each call, the wrapping methods are printed.
092        *
093        * By default no method is verbose.
094        *
095        * @param wrappeeExpr a regular expression that matches the
096        * wrappee(s) name(s) that contain the method(s) to be traced
097        * @param wrappeeClassExpr a regular expression that matches the
098        * wrappee(s) class(es) name(s) that contain the method(s) to be
099        * traced
100        * @param wrappeeMethodExpr a regular expression that matches the
101        * method(s) to be traced (within the classes or objects denoted by
102        * the previous parameters)
103        * @see org.objectweb.jac.wrappers.VerboseWrapper */
104       void addWrappersTrace(String wrappeeExpr, 
105                             String wrappeeClassExpr, 
106                             String wrappeeMethodExpr);
107    
108       /**
109        * This configuration method creates a new recording on a set of
110        * methods.
111        *
112        * @param wrappeeExpr a pointcut expression that matches the
113        * wrappee(s) name(s) that contain the method(s) to be traced
114        * @param wrappeeClassExpr a pointcut expression that matches the
115        * wrappee(s) class(es) name(s) that contain the method(s) to be
116        * traced
117        * @param wrappeeMethodExpr a pointcut expression that matches the
118        * method(s) to be traced (within the classes or objects denoted by
119        * the previous parameters) */
120    
121       void addRecording(String wrappeeExpr, 
122                         String wrappeeClassExpr, 
123                         String wrappeeMethodExpr);
124    
125       /**
126        * This configuration method makes all the matching methods
127        * invocations to be counted.
128        *
129        * @param name the name of the counter that is used (can be
130        * shared)
131        * @param wrappeeExpr a regular expression that matches the
132        * wrappee(s) name(s) that contain the method(s) to be counted
133        * @param wrappeeClassExpr a regular expression that matches the
134        * wrappee(s) class(es) name(s) that contain the method(s) to be
135        * counted
136        * @param wrappeeMethodExpr a regular expression that matches the
137        * method(s) to be counted (within the classes or objects denoted
138        * by the previous parameters)
139        * @see SimpleCountingWrapper 
140        */
141    
142       void addCounter(String name,
143                       String wrappeeExpr,
144                       String wrappeeClassExpr, 
145                       String wrappeeMethodExpr);
146       
147       /**
148        * This configuration method makes all the matching methods
149        * invocations to be counted in an optimized fashion.
150        *
151        * @param name the name of the counter that is used (can be
152        * shared)
153        * @param wrappeeExpr a regular expression that matches the
154        * wrappee(s) name(s) that contain the method(s) to be counted
155        * @param wrappeeClassExpr a regular expression that matches the
156        * wrappee(s) class(es) name(s) that contain the method(s) to be
157        * counted
158        * @param wrappeeMethodExpr a regular expression that matches the
159        * method(s) to be counted (within the classes or objects denoted
160        * by the previous parameters)
161        * @param fieldName the name of the field that is used to optimize
162        * the counting (the counter is incremented with its value), an
163        * empty string has no effect
164        * @param argNumber the argument's index that is used to optimize
165        * the counting (the counter is incremented with its value), an
166        * empty string has no effect 
167        * @see OptimizedCountingWrapper */
168    
169       void addOptimizedCounter(String name,
170                                String wrappeeExpr, 
171                                String wrappeeClassExpr, 
172                                String wrappeeMethodExpr,
173                                String fieldName,
174                                String argNumber);
175    
176    }
177    
178    
179    
180    
181    
182