From 38af9949c6ffd1b07aaab3271cd57f83ce247286 Mon Sep 17 00:00:00 2001 From: wisberg Date: Fri, 3 Nov 2006 07:47:16 +0000 Subject: to pdguide added XLint list, more control options, debugging pointcuts, and more hand-holding. --- docs/pdGuideDB/ajcore.xml | 15 +-- docs/pdGuideDB/ltwdump.xml | 55 ++++---- docs/pdGuideDB/messages.xml | 299 +++++++++++++++++++++++++++++++++---------- docs/pdGuideDB/pdguide.xml | 43 ++++++- docs/pdGuideDB/pointcuts.xml | 162 +++++++++++++++++++++++ docs/pdGuideDB/trace.xml | 31 +++-- 6 files changed, 484 insertions(+), 121 deletions(-) create mode 100644 docs/pdGuideDB/pointcuts.xml (limited to 'docs/pdGuideDB') diff --git a/docs/pdGuideDB/ajcore.xml b/docs/pdGuideDB/ajcore.xml index f1cf17681..838c6d7b4 100644 --- a/docs/pdGuideDB/ajcore.xml +++ b/docs/pdGuideDB/ajcore.xml @@ -1,4 +1,4 @@ - + AspectJ Core Files @@ -10,12 +10,11 @@ the date and time that the file was produced e.g. ajcore.20060810.173655.626.txt. The file contains details of the problem such as the exception thrown as well as information about the - environement such as operating system and Java version. - - - + environment such as operating system and Java version. When submitting a bug, + include this file whenever it is available. + - Configuration + Configuring dump files By default AspectJ will only create an ajcore file when an unexpected exception is thrown by the weaver or an @@ -61,8 +60,8 @@ - - Examples + + AJCore File Examples Below is an extract from an ajcore file. You will see details of the dump configuration as well as the exception (with stack trace) that diff --git a/docs/pdGuideDB/ltwdump.xml b/docs/pdGuideDB/ltwdump.xml index 36b1bea3a..049f2e4f5 100644 --- a/docs/pdGuideDB/ltwdump.xml +++ b/docs/pdGuideDB/ltwdump.xml @@ -1,38 +1,35 @@ - - LTW Dump + + Dumping classes during load-time weaving Introduction - Occasionally problems may be encountered with classes that have been load-time woven. - Symptoms will include incorrect program function or a Java exception such as - java.lang.VerifyError. Problems can be caused by the way - an aspect or class is built, incompatibilities between AspectJ and - generated byte-code - e.g. CGLIB - or a bug in the weaver. - When these problems occur it may be necessary to attach the class files concerned - to a bug report. AspectJ can be configured to dump byte-code to disk using - META-INF/aop.xml. The _ajdump subdirectory the the current - working directory is used. - - - Configuration - - See the + + Very rarely, problems present not at build-time but at run-time, + with java.lang.VerifyError or incorrect behavior. + In these situations, it's most helpful to include the offending class + in the bug report. But with load-time weaving, the woven classes are + in memory only; to save classes woven at load-time, configure + META-INF/aop.xml to dump the classes (by default + to an _ajdump subdirectory of the current working + directory). Also, if the input class file is not available (e.g., if + the AspectJ weaver is after another bytecode weaver), you can + also configure the weaver to dump the input classes. + + + Configuring bytecode dumping in load-time weaving + + For details of how to configure byte-code dumping, see the + AspectJ Development Environment Guide section on - Development Environment Guide - for details of how to configure byte-code dumping. - + Configuring Load-time Weaving. + Following is a simple example. + + - - Examples - - By default AspectJ will dump byte-code only after it is woven. This - is because usually the original class file is already available. However - byte-code is sometimes generated by frameworks or downloaded over the network - in which case AsepctJ can dump the byte-code before it is woven too. - + + LTW Dump Examples + The following META-INF/aop.xml will weave classes in the com.foo package (and subpackages) but not CGLIB generated classes in the com.foo.bar package (and subpackages). diff --git a/docs/pdGuideDB/messages.xml b/docs/pdGuideDB/messages.xml index 44b1189bd..cadb2a0df 100644 --- a/docs/pdGuideDB/messages.xml +++ b/docs/pdGuideDB/messages.xml @@ -3,49 +3,53 @@ Introduction - - By default only warning and error messages are issued by the compiler whether it is - being used for source code compilation, weaving, binary weaving or load-time weaving. Informational, - debug and weaving messages can also be obtained using compiler options - or System properties. Also as well as being able to soften or ignore - certain error messages the various -Xlint - options can be used to - notify you of conditions that would otherwise be ignored. - - It is often difficult to determine, especially when using load-time weaving (LTW), - why advice has not been woven. Here is a quick guide to the messages to - look for. Firstly if you use the -verbose option you - should see the following message when your aspect is registered: - - - - Secondly if you use the -debug option you should - see a message indicating that you class is being woven: - - - - However this does not mean that advice has actually been woven into - your class merely that the class has been passed to the weaver. To determine - whether your pointcuts match you can use the -showWeaveInfo - option which will cause a message to be issued each time a piece of advice is woven: - - - - - Configuration + + Messages point out potential problems in the input program; some + are clearly problems (errors), but many more may depend on what + the programmer intends. To keep the noise down, the latter are treated + as warnings that can be ignored by the programmer or information + hidden from the programmer. However, when investigating + unexpected behavior, it's helpful to show them. This describes how + to configure messages, presents some problem scenarios when + compiling or doing load-time weaving, and summarizes some of the + more relevant messages. + + + Configuring Messages + + The compiler offers -verbose, + -warning, and -XLint options + when invoked using the command-line, Ant, or embedded in an IDE. + All options are listed in the AspectJ Development Environment Guide + sections for + Ajc and + Ant Tasks. + The Load-time Weaving + section describes how to use XML configuration files and + system properties to pass options to the weaver. (You can also + pass options to the weaver using system properties in build- + time weaving.) + The -verbose option has the effect of including + messages level "info", which are normally ignored. + Both warning and XLint + enable you to identify specific messages to emit, but warning + messages tend to be the same provided by the underlying Eclipse + JDT (Java) compiler, while XLint messages are emitted by the + AspectJ compiler or weaver. Obviously, during load-time weaving + only weaver messages will be emitted. Similarly, if aspects + are compiled but not woven, then only compiler messages will be + emitted. However, the usual case for the compiler/weaver working + at build time is to emit both compiler and weaver messages. + - The table below lists the options used to control AspectJ messages. The method + The table below lists some options used to control AspectJ messages. The method of configuration depends on your environment so refer to the relevant documentation for ajc, - Ant or - LTW. + Ant or + LTW. + @@ -71,6 +75,8 @@ (Load-time weaving only). Show debugging messages such as which classes are being woven or those that are excluded. + (This is not related to the compiler -g option to + include debug information in the output .class files.) @@ -89,47 +95,65 @@ Control level of lint messages. - - - - - The table below lists some useful -Xlint messages. - - - - Message - Default - Description + + messageHolderClass + + + In Ant tasks, specify the class to receive all messages. + See + + iajc task options. + - - - aspectExcludedByConfiguration + rg.aspectj.tools.Main.setMessageHolder(..) - ignore + Programmatic access for setting the message holder + outside of Ant. + + - If an aspect is not being woven, despite being - registered, it could be that it has been excluded - by either an include or exclude - element in the - aspects section of META-INF/aop.xml. - Enable this message to determine whether an aspect has - been excluded. + org.aspectj.weaving.messages + + + Set this system property to redirect compiler/weaver + messages to logging facilities, as described in + . + + + + + @SuppressAjWarnings + + + Include this is Java 5 code to suppress AspectJ + warnings associated with the next line of code. - - + + + + Message scenarios + + + Compile-time weaving scenarios + + Advice not woven + This means that the pointcut for the advice did not match, + and it should be debugged as described in + . + - - - Examples + + + Load-time weaving scenarios You can use META-INF/aop.xml to control which messages are produced during LTW. The following example will produce @@ -143,7 +167,7 @@ ]]> - Notice that you are told exactly which META-INF/aop.xml + The messages indicate which META-INF/aop.xml configurations file(s) are being used. Each message is also preceeded by the name of the defining class loader associated with weaver. You can use this information in a large system to distinguish between different applications each @@ -157,6 +181,147 @@ [AppClassLoader@92e78c] info register aspect ExceptionHandler [AppClassLoader@92e78c] info processing reweavable type ExceptionHandler: ExceptionHandler.aj ]]> + + + Advice not woven + It is often difficult to determine, especially when using load-time weaving (LTW), + why advice has not been woven. Here is a quick guide to the messages to + look for. Firstly if you use the -verbose option you + should see the following message when your aspect is registered: + + + + Secondly if you use the -debug option you should + see a message indicating that you class is being woven: + + + + However this does not mean that advice has actually been woven into + your class; it says that the class has been passed to the weaver. To determine + whether your pointcuts match you can use the -showWeaveInfo + option which will cause a message to be issued each time a join point is woven: + + + + If advice should be woven at this join point, you should get a + corresponding message. + + + + Lint messages + + The table below lists some useful -Xlint messages. + + + + + Message + Default + Description + + + + + + aspectExcludedByConfiguration + + + ignore + + + If an aspect is not being woven, despite being + registered, it could be that it has been excluded + by either an include or exclude + element in the + aspects section of META-INF/aop.xml. + Enable this message to determine whether an aspect has + been excluded. + + + + + adviceDidNotMatch + + + warning + + + Issued when advice did not potentially affect any join points. + This means the corresponding pointcut did not match any join + points in the program. This may be valid e.g., in library + aspects or code picking up error conditions, but often the + programmer simply made a mistake in the pointcut. The best + approach is to debug the pointcut. + + + + + invalidAbsoluteTypeName + + + warning + + + Issued when an exact type in a pointcut does not match any type + in the system. Note that this can interact with the rules for + resolving simple types, which permit unqualified names if they + are imported. + + + + + typeNotExposedToWeaver + + + warning + + + This means that a type which could be affected by an aspect + is not available for weaving. This happens when a class on + the classpath should be woven. + + + + + runtimeExceptionNotSoftened + + + warning + + + Before AspectJ 5, declare soft used to soften runtime exceptions + (unnecessarily). Since then, it does not but does issue this + warning in case the programmer did intend for the exception + to be wrapped. + + + + + unmatchedSuperTypeInCall + + + warning + + + Issued when a call pointcut specifies a defining type which + is not matched at the call site (where the declared type of + the reference is used, not the actual runtime type). Most + people should use + 'target(Foo) && call(void foo())' + instead. + + + + + + + diff --git a/docs/pdGuideDB/pdguide.xml b/docs/pdGuideDB/pdguide.xml index dab3070bf..5581d5395 100644 --- a/docs/pdGuideDB/pdguide.xml +++ b/docs/pdGuideDB/pdguide.xml @@ -4,6 +4,7 @@ "../../lib/docbook/docbook-dtd/docbookx.dtd" [ + @@ -28,16 +29,46 @@ - This guide describes how to gather and interpret information from the AspectJ compiler - to diagnosing problems in AspectJ programs, configuring the load-time weaving - framework or reporting bugs on Bugzilla. Some information e.g. messages is intended to - help you solve coding or configuration problems. Other information is intended to be - be used by the AspectJ team when trying to fix bugs. + This describes how to configure the AspectJ compiler/weaver to provide + information for diagnosing problems in the input programs or in the + compiler/weaver itself. - + + The AspectJ compiler and weaver can provide lots of information for diagnosing + problems in building AspectJ programs. For problems in the input program, + there are a number of default warning and error messages and many + configurable "lint" messages, all of which can be emitted normally, + logged using standard facilities, or intercepted programmatically. + These are discussed in . Since most errors + relate to writing pointcuts incorrectly, there is a section on + . + + + For problems with the compiler/weaver itself, there are three facilities + that enable the AspectJ developers to resolve bugs even when it is + too hard to deliver a reproducible test case: + + can be enabled to track progress up to the time of a failure; + can give a relatively complete picture of the state of + the world at the time of a failure; and + is a way to capture both + input and output classes during load-time weaving. + + + + + This guide describes how to configure messages to get the right information + and how to configure traces, dumps, and core files. Although the compiler/weaver + operates in roughly three modes (from the command-line, embedded in an IDE, + and enabled as load-time weaving), the principles are basically the same for + all modes. The differences lie in how to set up diagnostics and what + information is likely to be relevant. + + &messages; + &pointcuts; &ajcore; &trace; <wdump; diff --git a/docs/pdGuideDB/pointcuts.xml b/docs/pdGuideDB/pointcuts.xml new file mode 100644 index 000000000..ecf3cf662 --- /dev/null +++ b/docs/pdGuideDB/pointcuts.xml @@ -0,0 +1,162 @@ + + Debugging Pointcuts + + Introduction + + + This section describes how to write and debug pointcuts + using the usual approach of iteration and decomposition. + New users are often stumped when their advice does not match. + That means the pointcut doesn't match; they rewrite the + pointcut and it still doesn't match, with no new information. + This can be frustrating if each iteration involves building, + deploying, and testing a complex application. Learning to + break it down, particularly into parts that can be checked + at compile-time, can save a lot of time. + + + + + Debugging pointcuts + +Go at it top-down and then bottom-up. Top-down, draft significant +aspects by first writing the comments to specify responsibilities. +Advice responsibility usually takes the form, "When X, do Y." +Pointcut responsibility for "When X" often takes the form, +"When [join points] [in locations] [are ...]". These []'s often +translate to named pointcuts (like `libraryCalls() && within(Client) +&& args(Context)`) which form a semantic bridge to the plain-text +meaning in a comment (e.g., `// when the client passes only context into +the library`). +This gets you to a point where you can debug the parts of the +pointcut independently. + + +Bottom up (to build each part), consider each primitive pointcut +designator (PCD), then the composition, and then any implicit +constraints: + + +What kinds of join points should it match? (constructor-call? +field-get?)? This translates to using the kinded pointcuts +(`call(..)`, `get(..)`, etc.). + + +Are these restricted to being lexically within something? This +translates to using `within{code}(..)`. If this is true, it should +always be used, to speed up weaving. + + +What runtime constraints and context should be true and available at +each join point? This translates to `this()`, `target()`, `args()`, +`cflow{below}()` and `if(..)`. + + +Are there any advice or implementation limitations at issue? This +involves knowing the few constraints on AspectJ imposed by Java bytecode +as listed in the AspectJ Programming Guide section on + Implementation Notes. + + + + + It's much faster to iterate a pointcut at compile-time + using declare warning (even better, some errors are identified + at parse-time in the latest versions of AJDT). + Start with the parts of the pointcut + that are staticly-determinable (i.e., they do not involve + the runtime PCD's listed above). If compiles themselves + take too long because of all the AspectJ weaving, then + try to only include the debugging aspect with the prototype + pointcut, and limit the scope using within(..). + + + Some mistakes in primitive pointcuts: + + +`this(Foo) && execution(static * *(..))`: There is no `this` in a static +context, so `this()` or `target()` should not be used in a static +context or when targetting a static context (respectively). This +happens most often when you want to say things like "all calls to Foo from Bar" +and you only pick out calls to instance methods of Foo +or you try to pick out calls from static methods of Bar. + + +`target(Foo) && call(new(..)`: This will never match. In +constructor-call join points, there is no target because the object +has not been created yet. + + +`call(* Foo.*(..))`: `Foo` refers to the compile-time type of the +invoking reference, not the implementing class. In Java before 1.4, +the compile-time type was rendered as the defining type, not the +reference type; this was corrected in 1.4 (as shown when using ajc +with the -1.4 flag) Most people should use `target(Foo) && call(...)`. + + +`execution(* Foo.bar(..))`: An execution join point for Foo is +always within Foo, so this won't pick out any overrides of bar(..). +Use `target(Foo) && execution(* bar(..))` for instance methods. + + +`within(Foo)`: anonymous types are not known at weave-time to be +within the lexically-enclosing type (a limitation of Java bytecode). + + + + + Some mistakes in composition: + + +`call(* foo(Bar, Foo)) && args(Foo)`: This will never match. +The parameters in `args(..)` are position-dependent, so `args(Foo)` only picks + out join points where there is only one argument possible, of type Foo. +Use the indeterminate-arguments operator '..' as needed, e.g., `args(Foo, ..)`. + + +`call(* foo()) && execution(* foo())`: This will never match. Each +pointcut must be true at each join point matched. For a union of different +kinds of join points (here, call or execution), use '||'. +E.g., to match both method-call and field-get join points, use + `call(* ...) || get(...)`. + + + + + Some mistakes in implicit advice constraints: + + +`after () returning (Foo foo) : ...`: after advice can bind the +returned object or exception thrown. That effectively acts like +`target()`, `this()`, or `args()` in restricting when the advice +runs based on the runtime type of the bound object, even though it is +not explicitly part of the pointcut. + + + + + Some mistakes in implementation requirements: + + +`ajc` has to control the code for a join point in order to implement +the join point. This translates to an implicit `within({code under +the control of the compiler})` for all join points, with additional +caveat for some join points. Take exception handlers, for example: +there is no way to be sure from the bytecode where the original handler +ends, so `ajc` can't implement after advice on handler join points. +(Since these are on a per-join-point basis, they should be considered +for each corresponding primitive pointcut designator.) Unlike the +mistakes with the primitive PCDs above, the compiler will emit an +error for these caveats. + + +`call(@SuperAnnotation Subclass.meth()`: Annotations are not inherited +by default, so e.g., if the pointcut specifies an annotation, then +subclass implementations of that method will not be matched. + + + + + + + diff --git a/docs/pdGuideDB/trace.xml b/docs/pdGuideDB/trace.xml index 382d87842..21cc7d796 100644 --- a/docs/pdGuideDB/trace.xml +++ b/docs/pdGuideDB/trace.xml @@ -1,30 +1,39 @@ - + Tracing Introduction - The usual approach to opening a report on Bugzilla is to describe the symptoms of the + + The AspectJ developers have instrumented the compiler/weaver with + many "trace" messages for their own debugging use. These remain in + the production releases because tracing helps when it is hard to + isolate the problem in a test case. This sections describes how + to enable tracing so you can provide trace information on bug reports. + + + The usual approach to opening a report on Bugzilla is to describe the symptoms of the problem and attach a simple testcase. This allows the AspectJ team to try and reproduce the problem in an attempt to fix it as well as improve the test suite. Unfortunately it may not be possible to produce such a testcase either because your program is too large or is commercially sensitive. Alternatively the problem may relate to your specific environment where AspectJ is being used and will not be - reproducible by the AspectJ team. In each of these situations you may be asked to produce a + reproducible by the AspectJ team. In each of these situations you can produce a trace of the compiler when the problem occurs instead. This can then be attached to the bug report. - - Configuration + + Configuring Tracing When available (Java 5 or later) AspectJ will use the - java.util.logging - infrastructure - that is configured using a logging.properties file. By default only error - and fatal events will be logged but less severe warnings as well as fine grained + + java.util.logging infrastructure + configured using a logging.properties file. By default only error + and fatal events will be logged but less severe warnings as well as fine-grained method entry and exit events can be obtained using the appropriate configuration. All regular compiler messages can also be logged through the infrastructure by setting the org.aspectj.weaving.messages System property. - If you are using a JDK 1.4 or earlier AspectJ will use a simple built-in trace + If you are running the AspectJ compiler/weaver under JDK 1.4 or earlier, + AspectJ will use a simple built-in trace infrastructure that logs to stderr. This is enabled by setting the org.aspectj.weaving.tracing.enabled System property. You may also override the default behaviour or provide your own trace implementation using the @@ -86,7 +95,7 @@ - + Examples Using -Dorg.aspectj.tracing.factory=default -- cgit v1.2.3