diff options
Diffstat (limited to 'docs/dist/doc/README-11.adoc')
| -rw-r--r-- | docs/dist/doc/README-11.adoc | 142 |
1 files changed, 94 insertions, 48 deletions
diff --git a/docs/dist/doc/README-11.adoc b/docs/dist/doc/README-11.adoc index 0464ba88b..377d18588 100644 --- a/docs/dist/doc/README-11.adoc +++ b/docs/dist/doc/README-11.adoc @@ -1,8 +1,9 @@ +[[readme-1_1]] +== AspectJ 1.1 Readme + [.small]#© Copyright 2002 Palo Alto Research Center, Incorporated, 2003 Contributors. All rights reserved.# -== AspectJ 1.1 Readme - This is the initial release of AspectJ 1.1. It includes a small number of new language features as well as major improvements to the functionality of the tools. @@ -30,7 +31,8 @@ xref:#knownLimitations[known limitations]. ''''' -=== [#language]#The Language# +[[language]] +=== The Language AspectJ 1.1 is a slightly different language than AspectJ 1.0. In all but a few cases, programs written in AspectJ 1.0 should compile @@ -116,7 +118,8 @@ specifier] in this release, but it may well be in a future release. ''''' -=== [#compiler]#The Compiler# +[[compiler]] +=== The Compiler The compiler for AspectJ 1.1 is different than the compiler for AspectJ 1.0. While this document describes the differences in the compiler, it's @@ -169,7 +172,7 @@ compiler: -nocomment and -workingdir * xref:#NO_STRICT_LENIENT[The -strict and -lenient options] * xref:#NO_PORTING[The -porting option] -* xref:#13_REQUIRED[J2SE 1.2 is not supported; J2SE 1.3 or later is +* xref:#_13_REQUIRED[J2SE 1.2 is not supported; J2SE 1.3 or later is required.] A short description of the options ajc accepts is available with @@ -190,7 +193,8 @@ xref:#ONE_FOUR_METHOD_SIGNATURES[the -1.4 flag]. ''''' -=== [#tools]#Support Tools# +[[tools]] +=== Support Tools This release includes an Ant task for old-style 1.0 build scripts, a new task for all the new compiler options, and a CompilerAdapter to support @@ -219,7 +223,8 @@ support is available. ''''' -=== [#runtime]#The Runtime Library# +[[runtime]] +=== The Runtime Library This release has minor additions to the runtime library classes. As with any release, you should compile and run with the runtime library that @@ -234,7 +239,8 @@ and will always return 0. ''''' -=== [#devenv]#The AJDE Tools# +[[devenv]] +=== The AJDE Tools The AspectJ Browser supports incremental compilation and running programs. AJDE for JBuilder, AJDE for NetBeans, and AJDE for Emacs are @@ -243,7 +249,8 @@ the batch-build mode of the new compiler. ''''' -=== [#sources]#The Sources and the Licenses# +[[sources]] +=== The Sources and the Licenses The AspectJ tools sources are available under the https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt[Eclipse Public @@ -253,7 +260,8 @@ faq.html#q:buildingsource[building sources]. ''''' -=== [#distribution]#The AspectJ distribution# +[[distribution]] +=== The AspectJ distribution AspectJ 1.0 had many distributions - for the tools, the documentation, each IDE support package, their respective sources, and the Ant tasks - @@ -270,9 +278,11 @@ SourceForge projects. ''''' -=== [#details]#Details# of some language and compiler changes +[[details]] +=== Details of some language and compiler changes -==== [#ASPECT_INSTANTIATION_AND_ADVICE]#Aspect Instantiation and Advice# +[[ASPECT_INSTANTIATION_AND_ADVICE]] +==== Aspect Instantiation and Advice In AspectJ 1.0.6, we made an effort to hide some complications with Aspect instantiation from the user. In particular, the following code @@ -339,7 +349,8 @@ exception than a NullPointerException for this case. In AspectJ 1.1, both of the above programs will throw org.aspectj.lang.NoAspectBoundException. -==== [#THROWS_PATTERN]#Matching based on throws# +[[THROWS_PATTERN]] +==== Matching based on throws Type patterns may now be used to pick out methods and constructors based on their throws clauses. This allows the following two kinds of @@ -400,7 +411,8 @@ declares that it throws IOException. [2] WILL match the method m(), because method m's throws clause declares the it throws some exception which does not match IOException, i.e. RuntimeException. -==== [#NEW_PCDS]#New kinded pointcut designators# +[[NEW_PCDS]] +==== New kinded pointcut designators AspectJ 1.0 does not provide kinded pointcut designators for two (rarely used) join points: preinitialization (the code that runs before a super @@ -417,7 +429,8 @@ aspect. + join points where the initialization process is entered through `ConstructorPattern`. -==== [#PER_TYPE]#New pertype aspect specifier# (not in 1.1) +[[PER_TYPE]] +==== New pertype aspect specifier (not in 1.1) We strongly considered adding a pertype aspect kind to 1.1. This is somewhat motivated by the new @@ -460,7 +473,8 @@ the most common uses of this idiom. In any case, this feature will not be in AspectJ 1.1. -==== [#SINGLE_INTERCLASS_TARGET]#One target for intertype declarations# +[[SINGLE_INTERCLASS_TARGET]] +==== One target for intertype declarations Intertype declarations (once called "introductions") in AspectJ 1.1 can only have one target type. So the following code intended to declare @@ -494,7 +508,8 @@ ability to add static fields to many classes. We believe that the xref:#PER_TYPE[pertype proposal] provides this functionality in a much more usable form. -==== [#UNAVAILABLE_JOIN_POINTS]#No initializer execution join points# +[[UNAVAILABLE_JOIN_POINTS]] +==== No initializer execution join points AspectJ 1.1 does not consider initializer execution a principled join point. The collection of initializer code (the code that sets fields @@ -502,13 +517,15 @@ with initializers and the code in non-static initializer blocks) is something that makes sense only in Java source code, not in Java bytecode. -==== [#AFTER_HANDLER]####No after or around advice on handler join points +[[AFTER_HANDLER]] +==== No after or around advice on handler join points The end of an exception handler is underdetermined in bytecode, so ajc will not implement after or around advice on handler join points, instead signaling a compile-time error. -==== [#CONSTRUCTOR_EXECUTION_IS_BIGGER]#Initializers run inside constructor execution join points# +[[CONSTRUCTOR_EXECUTION_IS_BIGGER]] +==== Initializers run inside constructor execution join points The code generated by the initializers in Java source code now runs inside of constructor execution join points. This changes how before @@ -544,7 +561,8 @@ programmers using before advice on constructor execution must always assume incomplete object initialization, since the constructor has not yet run. -==== [#INTER_TYPE_FIELD_INITIALIZERS]#Inter-type field initializers# +[[INTER_TYPE_FIELD_INITIALIZERS]] +==== Inter-type field initializers The initializer, if any, of an inter-type field definition runs before the class-local initializers of its target class. @@ -571,7 +589,8 @@ We felt there would be too much surprise if a constructor called a method (thus incrementing the method count) and then the field was reset to zero after the constructor was done. -==== [#WITHIN_MEMBER_TYPES]#Small limitations of the within pointcut# +[[WITHIN_MEMBER_TYPES]] +==== Small limitations of the within pointcut Because of the guarantees made (and not made) by the Java classfile format, there are cases where AspectJ 1.1 cannot guarantee that the @@ -609,12 +628,14 @@ example: We believe the non-guarantee is small, and we haven't verified that it is a problem in practice. -==== [#WITHIN_CODE]#Small limitations of the withincode pointcut# +[[WITHIN_CODE]] +==== Small limitations of the withincode pointcut The withincode pointcut has similar issues to those described above for within. -==== [#INSTANCEOF_ON_WILD]#Can't do instanceof matching on type patterns with wildcard# +[[INSTANCEOF_ON_WILD]] +==== Can't do instanceof matching on type patterns with wildcard The pointcut designators this, target and args specify a dynamic test on their argument. These tests can not be performed on type patterns with @@ -660,7 +681,8 @@ based on static types. So, you can use 'within(com.bigboxco..*+)' to match any code lexically within one of your classes or a subtype thereof. This is often a good choice. -==== [#NO_SOURCE_COLUMN]#SourceLocation.getColumn()# +[[NO_SOURCE_COLUMN]] +==== SourceLocation.getColumn() The Java .class file format contains information about the source file and line numbers of its contents; however, it has no information about @@ -669,7 +691,8 @@ of column information in the reflection API. So, any calls to thisJoinPoint.getSourceLocation().getColumn() will be marked as deprecated by the compiler, and will always return 0. -==== [#ASPECT_PRECEDENCE]#Aspect precedence# +[[ASPECT_PRECEDENCE]] +==== Aspect precedence AspectJ 1.1 has a new declare form: @@ -791,7 +814,8 @@ This no longer works in AspectJ 1.1, since declare precedence only matters for concrete aspects. Thus, if you want to regain this kind of precedence change, you will need to refactor your aspects. -==== [#SOURCEROOT]#The -sourceroots option# +[[SOURCEROOT]] +==== The -sourceroots option The AspectJ 1.1 compiler now accepts a -sourceroots option used to pass all .java files in particular directories to the compiler. It takes @@ -812,7 +836,8 @@ of This option may be used in conjunction with lst files, listing .java files on the command line, and the -injars option. -==== [#BYTECODE_WEAVING]#The -injars option# +[[BYTECODE_WEAVING]] +==== The -injars option The AspectJ 1.1 compiler now accepts an -injars option used to pass all .class files in a particular jar file to the compiler. It takes either a @@ -838,7 +863,8 @@ compiler), they should not be compiled with any non-abstract aspects. This option may be used in conjunction with lst files, listing .java files on the command line, and the -sourceroots option. -==== [#OUTJAR]#The -outjar option# +[[OUTJAR]] +==== The -outjar option The -outjar option takes the name of a jar file into which the results of the compilation should be put. For example: @@ -850,7 +876,8 @@ of the compilation should be put. For example: No meta information is placed in the output jar file. -==== [#INCREMENTAL]#Incremental compilation# +[[INCREMENTAL]] +==== Incremental compilation The AspectJ 1.1 compiler now supports incremental compilation. When ajc is called with the -incremental option, it must also be passed a @@ -863,7 +890,8 @@ recompiles those input files that need recompiling. This new functionality is still only lightly tested. -==== [#XNOWEAVE]#-XnoWeave, a compiler option to suppress weaving# +[[XNOWEAVE]] +==== -XnoWeave, a compiler option to suppress weaving The -XnoWeave option suppresses weaving, and generates classfiles and that can be passed to ajc again (through the -injars option) to generate @@ -876,7 +904,8 @@ the `-aspectpath` option is a much better option. There may still be use cases for unwoven classfiles, but we've moved the flag to experimental status. -==== [#BINARY_ASPECTS]#-aspectpath, working with aspects in .class/.jar form# +[[BINARY_ASPECTS]] +==== -aspectpath, working with aspects in .class/.jar form When aspects are compiled into classfiles, they include all information necessary for the ajc compiler to weave their advice and deal with their @@ -886,7 +915,8 @@ a compilation process, they must be passed to the compiler on the and any aspects that are found will be enabled during the compilation. The binary forms of this aspects will be untouched. -==== [#NO_CALLEE_SIDE_CALL]#Callee-side call join points# +[[NO_CALLEE_SIDE_CALL]] +==== Callee-side call join points The 1.0 implementation of AspectJ, when given: @@ -994,7 +1024,8 @@ How will this affect developers? * When using the call PCD but only supplying the callee code, supply the calling code or use the execution PCD instead. -==== [#OTHER_X_OPTIONS]#Various -X options# +[[OTHER_X_OPTIONS]] +==== Various -X options The AspectJ 1.0 compiler supported a number of options that started with X, for "experimental". Some of them will not be supported in 1.1, either @@ -1012,7 +1043,8 @@ xref:#XNOINLINE[`-XnoInline`]. because we're now always using (what we believe to be) safe prefixes. * -Xlint: Still supported, with xref:#XLINT[various options]. -==== [#ERROR_MESSAGES]#Some confusing error messages# +[[ERROR_MESSAGES]] +==== Some confusing error messages Building on the eclipse compiler has given us access to a very sophisticated problem reporting system as well as highly optimized error @@ -1022,7 +1054,8 @@ correctly this can sometimes lead to cascading error messages where a single small syntax error will produce dozens of other messages. Please report any very confusing error messages as bugs. -==== [#MESSAGE_CONTEXT]#Source code context is not shown for errors and warnings detected during bytecode weaving# +[[MESSAGE_CONTEXT]] +==== Source code context is not shown for errors and warnings detected during bytecode weaving For compiler errors and warnings detected during bytecode weaving, source code context will not be displayed. In particular, for declare @@ -1032,7 +1065,8 @@ the source code is available; in cases where source code is not available, we might specify the signature of the offending code. For more information, see bug 31724. -==== [#XLINT]#The -Xlint option# +[[XLINT]] +==== The -Xlint option `-Xlint:ignore,error,warning` will set the level for all Xlint warnings. `-Xlint`, alone, is an abbreviation for `-Xlint:warning`. @@ -1048,23 +1082,27 @@ warn about more potentially dangerous situations, such as the potentially unsafe casts used by very polymorphic uses of proceed in around advice. -==== [#NO_SOURCE]#Source-specific options# +[[NO_SOURCE]] +==== Source-specific options Because AspectJ 1.1 does not generate source code after weaving, the source-code-specific options -preprocess, -usejavac, -nocomment and -workingdir options are meaningless and so not supported. -==== [#NO_STRICT_LENIENT]#The -strict and -lenient options# +[[NO_STRICT_LENIENT]] +==== The -strict and -lenient options Because AspectJ 1.1 uses the Eclipse compiler, which has its own mechanism for changing strictness, we no longer support the -strict and -lenient options. -==== [#NO_PORTING]#The -porting option# +[[NO_PORTING]] +==== The -porting option AspectJ 1.1 does not have a -porting option. -==== [#13_REQUIRED]#J2SE 1.3 required# +[[_13_REQUIRED]] +==== J2SE 1.3 required Because we build on Eclipse, the compiler will no longer run under J2SE 1.2. You must run the compiler (and all tools based on the compiler) @@ -1072,7 +1110,8 @@ using J2SE 1.3 or later. The code generated by the compiler can still run on Java 1.1 or later VM's if compiled against the correct runtime libraries. -==== [#DEFAULT_CONSTRUCTOR_CONFLICT]#Default constructors# +[[DEFAULT_CONSTRUCTOR_CONFLICT]] +==== Default constructors AspectJ 1.1 does not allow the inter-type definition of a zero-argument constructor on a class with a visible default constructor. So this is no @@ -1097,7 +1136,8 @@ and can be referenced by other classes, and has code generated for it in classfiles. Therefore, it was an oversight that AspectJ 1.0.6 allowed such an "overriding" inter-type constructor definition. -==== [#SUPER_IFACE_INITS]#Initialization join points for super-interfaces# +[[SUPER_IFACE_INITS]] +==== Initialization join points for super-interfaces In AspectJ, interfaces may have non-static members due to inter-type declarations. Because of this, the semantics of AspectJ defines the @@ -1143,7 +1183,8 @@ the initializers for a type's superclass are run before the initializers for its superinterfaces. ____ -==== [#VOID_FIELD_SET]#Field Set Join Points# +[[VOID_FIELD_SET]] +==== Field Set Join Points In AspectJ 1.0.6, the join point for setting a field F had, as a return type, F's type. This was "java compatible" because field assignment in @@ -1193,14 +1234,16 @@ So, because it's easier to implement, and because we believe that this is the last possibility to make the semantics more useful, we have made set join points have a void return type in 1.1. -==== [#XNOINLINE]#The -XnoInline Option# +[[XNOINLINE]] +==== The -XnoInline Option The `-XnoInline` option to indicate that no inlining of any kind should be done. This is purely a compiler pragma: No program semantics (apart from stack traces) will be changed by the presence or absence of this option. -==== [#TARGET_TYPES_MADE_PUBLIC]#Target types made public# +[[TARGET_TYPES_MADE_PUBLIC]] +==== Target types made public Even in 1.0.6, the AspectJ compiler has occasionally needed to convert the visibility of a package-level class to a public one. This was @@ -1218,7 +1261,8 @@ various implementation tricks if they become a serious concern, but did not encounter them as such a concern when they were done in the 1.0.6 implementation. -==== [#STRINGBUFFER]#String + now advised# +[[STRINGBUFFER]] +==== String + now advised In Java, the + operator sometimes results in StringBuffer objects being created, appended to, and used to generate a new String. Thus, @@ -1271,7 +1315,8 @@ call(* *(int)) && args(i) && !within(A) call(* *(int)) && args(i) && !target(StringBuffer) .... -==== [#ONE_FOUR_METHOD_SIGNATURES]#The -1.4 flag and method signatures# +[[ONE_FOUR_METHOD_SIGNATURES]] +==== The -1.4 flag and method signatures Consider the following aspect @@ -1307,7 +1352,8 @@ OO programmers don't want to care about the static type of an object at a call site, but only want to know the dynamic instanceof behavior which is what the target matching will handle. -=== [#knownLimitations]#Known limitations# +[[knownLimitations]] +=== Known limitations The AspectJ 1.1.0 release contains a small number of known limitations relative to the AspectJ 1.1 language. For the most up-to-date |