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/messages.xml | 299 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 232 insertions(+), 67 deletions(-) (limited to 'docs/pdGuideDB/messages.xml') 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. + + + + + + + -- cgit v1.2.3