diff options
Diffstat (limited to 'docs/modules/ROOT/pages')
9 files changed, 66 insertions, 66 deletions
diff --git a/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc b/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc index ca18dbede..8f3a4ac30 100644 --- a/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc +++ b/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc @@ -1,4 +1,4 @@ -== *AspectJ^TM^ Compiler and Core Tools License* += *AspectJ^TM^ Compiler and Core Tools License* This is a binary-only release. Source code is available from https://eclipse.org/aspectj @@ -19,7 +19,7 @@ the Redistributor. Unless otherwise indicated below, the terms and conditions of the EPL still apply to any source code in the Content and such source code may be obtained at link:/[https://www.eclipse.org]. -=== Third Party Content +== Third Party Content The Content includes items that have been sourced from third parties as set out below. If you did not receive this Content directly from the @@ -29,7 +29,7 @@ conditions of use. __ -==== BCEL v5.1 +=== BCEL v5.1 This product contains software developed by the Apache Software Foundation (http://www.apache.org/[http://www.apache.org]). @@ -40,7 +40,7 @@ https://commons.apache.org/bcel/. Source code for the modified version of BCEL is available at Eclipse.org in the AspectJ source tree. This code is made available under the Apache Software License v1.1 -==== ASM v2.2.1 +=== ASM v2.2.1 AspectJ includes a binary version of ASM v2.2.1 (http://asm.objectweb.org/index.html[http://asm.objectweb.org/]) The diff --git a/docs/modules/ROOT/pages/README-AspectJ.adoc b/docs/modules/ROOT/pages/README-AspectJ.adoc index c754f3a44..e8905dfcf 100644 --- a/docs/modules/ROOT/pages/README-AspectJ.adoc +++ b/docs/modules/ROOT/pages/README-AspectJ.adoc @@ -1,8 +1,8 @@ -== AspectJ^TM^ += AspectJ^TM^ _Version @build.version.long@ released on @build.date@._ -=== 1 Contents of this Package +== 1 Contents of this Package * the link:bin[`<aspectj install dir>/bin`] directory has scripts for ** `ajc`: the compiler for the AspectJ language @@ -19,7 +19,7 @@ the link:doc/index.html[index] page. ''''' -=== 2 Install Procedure +== 2 Install Procedure The AspectJ tool `ajc` is a Java program that can be run indirectly from the scripts or directly from `aspectjtools.jar`. The @@ -62,7 +62,7 @@ create short launch scripts to start ajc easily (section 3). ''''' -=== 3. Running the Tools +== 3. Running the Tools If you did not use the automatic installation process or the default launch scripts do not work on your system, you may wish to create short @@ -98,9 +98,9 @@ ____ ''''' [[configInstructions]] -=== 4. Configuration Instructions +== 4. Configuration Instructions -==== 4.1 Adding `<aspectj install dir>/lib/aspectjrt.jar` to your classpath +=== 4.1 Adding `<aspectj install dir>/lib/aspectjrt.jar` to your classpath There are several ways to add this jar file to your classpath: @@ -110,7 +110,7 @@ next section for details) * always use the "`-classpath aspectjrt.jar`" option when running programs compiled with ajc -==== 4.2 [#6.1]#Setting the Environment Variables on Windows# +=== 4.2 [#6.1]#Setting the Environment Variables on Windows# The following instructions use the PATH variable as an example, but this process is identical for the CLASSPATH variable. diff --git a/docs/modules/ROOT/pages/developer/compiler-weaver.adoc b/docs/modules/ROOT/pages/developer/compiler-weaver.adoc index f5784a983..be3eb0a94 100644 --- a/docs/modules/ROOT/pages/developer/compiler-weaver.adoc +++ b/docs/modules/ROOT/pages/developer/compiler-weaver.adoc @@ -1,4 +1,4 @@ -== Guide for Developers of the AspectJ Compiler and Weaver += Guide for Developers of the AspectJ Compiler and Weaver _Latest (non-license) content update: 2004-02-20 by jhugunin_ @@ -36,7 +36,7 @@ weaving API which can be used to implement ClassLoaders that will weave advice into classes dynamically as they are loaded by the virtual machine. -=== Compiler front-end (org.aspectj.ajdt.core) +== Compiler front-end (org.aspectj.ajdt.core) The front-end of the AspectJ compiler is implemented as an extension of the Java compiler from eclipse.org. The source-file portion of the @@ -61,7 +61,7 @@ binding and some AspectJ augmentation . For each source file do a deep parse, annotation/analysis, and then code generation -==== Top-level parse tree +=== Top-level parse tree Let's trace the following example program through the compiler. @@ -96,7 +96,7 @@ When parsed, this program will produce the following tree. image:top-tree.png[image] -==== PointcutDeclaration processing +=== PointcutDeclaration processing Let's look more closely at the pointcut declaration: @@ -112,7 +112,7 @@ declaration. The actual pointcut is parsed by the weaver module. This parsing happens as part of the shallow parse phase. This is because this information might be needed to implement a declare soft. -==== AdviceDeclaration processing +=== AdviceDeclaration processing Next we look at the processing for an advice declaration: @@ -138,13 +138,13 @@ advice is still null. This field is not filled in until the second stage of the compiler when full parsing is done on each source file as a prelude to generating the classfile. -==== Overview of the main classes in org.aspectj.ajdt.core +=== Overview of the main classes in org.aspectj.ajdt.core The main classes in this module are shown in the following diagram: image:ajdt-uml.png[image] -=== Weaving back-end (weaver) +== Weaving back-end (weaver) This provides all of the weaving functionality. It has very few dependencies to keep the code as small as possible for deployment in @@ -174,7 +174,7 @@ static shadow. If it could match, it inserts a call to the advice’s implementation method guarded by any dynamic testing needed to ensure the match. -=== Runtime support library (runtime) +== Runtime support library (runtime) This library provides classes that are used by the generated code at runtime. These are the only classes that must be redistributed with a @@ -191,7 +191,7 @@ There are also several packages all under the header org.aspectj.runtime that are considered private to the implementation and may only be used by code generated by the AspectJ compiler. -=== Mappings from AspectJ language to implementation +== Mappings from AspectJ language to implementation [cols=",,",] |=== @@ -222,7 +222,7 @@ patterns.DeclareErrorOrWarning |pcd |ast.PointcutDesignator |patterns.Pointcut hierarchy |=== -== Tutorial: implementing a throw join point += Tutorial: implementing a throw join point This tutorial will walk step-by-step through the process of adding a new join point to AspectJ for the moment when an exception is thrown. In @@ -237,14 +237,14 @@ size of your actual code changes will likely be smaller, but you are likely to need to be familiar with all of the pieces of the implementation described below. -=== Part 1: Adding the join point and corresponding pcd +== Part 1: Adding the join point and corresponding pcd The first part of this tutorial will implement the main features of the throw join point. We will create a new join point shadow corresponding to the athrow instruction and also create a new pointcut designator (pcd) for matching it. -==== Step 1. Synchronize with repository and run the existing test suite +=== Step 1. Synchronize with repository and run the existing test suite Do a Team->Synchronize With Repository and make sure that your tree is completely in sync with the existing repository. Make sure to address @@ -261,7 +261,7 @@ Run the existing test suite. I currently do this in four steps: There should be no failures when you run these tests. If there are failures, resolve them with the AspectJ developers before moving on. -==== Step 2. Write a proto test case +=== Step 2. Write a proto test case {empty}a. Create a new file in tests/design/pcds/Throw.java @@ -315,7 +315,7 @@ about to execute: call(java.lang.RuntimeException(String)) PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 2 seconds .... -==== Step 3. Implement the new join point shadow kind +=== Step 3. Implement the new join point shadow kind Modify runtime/org.aspectj.lang/JoinPoint.java to add a name for the Throw shadow kind. @@ -362,7 +362,7 @@ Shadow.Kind. case 12: return Throw; .... -==== Step 4. Create this new kind of joinpoint for the throw bytecode +=== Step 4. Create this new kind of joinpoint for the throw bytecode Modify weaver/org.aspectj.weaver.bcel/BcelClassWeaver.java to recognize this new joinpoint kind. In the method @@ -450,7 +450,7 @@ we used Member.HANDLER for the kind of the signature of this join point. That's clearly not correct. We'll fix that at the end of the lesson as part of the clean-up. For now, let's go on with the interesting parts. -==== Step 5. Extend our proto-test to use a pointcut designator for matching +=== Step 5. Extend our proto-test to use a pointcut designator for matching Add a second piece of before advice to the test aspect A: @@ -481,7 +481,7 @@ any existing programs that use throw as the name for a user-defined PCD. Fortunately because throw is a Java keyword this particular change is very safe. -==== Step 6. Extend the PCD parser to handle this new primitive PCD +=== Step 6. Extend the PCD parser to handle this new primitive PCD Modify the parseSinglePointcut method in weaver/org.aspectj.weaver.patterns/PatternParser.java to add one more @@ -526,7 +526,7 @@ Make sure that you see the 'about to throw' printed before moving on. This shows that the throw PCD is now successfully matching the throw join point shadow we added earlier. -==== Step 7. Check that we're properly providing the single thrown argument (and clean-up the test) +=== Step 7. Check that we're properly providing the single thrown argument (and clean-up the test) Now that we have a valid pcd for this advice, we can simplify our test case. Modify our test aspect A to be the following. In addition to @@ -557,7 +557,7 @@ a new join point to the AspectJ language and a corresponding PCD to match it. This is a good time to take a break before moving on to part two. -=== Part 2: Getting the signature of this new join point right +== Part 2: Getting the signature of this new join point right We know that throw(catch(Throwable)) is not the right thing to be printing for the signature at this join point. What is the correct @@ -601,7 +601,7 @@ allow dynamic matching in args to select more specific types. In general, good AspectJ code should use this dynamic matching anyway to correspond to good OO designs. -==== Step 1. Change the signature of the throw pcd +=== Step 1. Change the signature of the throw pcd Since we aren't going to recover the static type of the exception thrown, we need to fix the parser for the throw pcd to remove this @@ -683,7 +683,7 @@ passing: PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 2 seconds .... -==== Part 2. Make a real test case +=== Part 2. Make a real test case The pass result from running our test should worry you. Unlike previous runs, this test run doesn't show the output from our System.out.println @@ -734,7 +734,7 @@ we're not matching the throw join point anymore. FAIL Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 failed) 1 seconds .... -==== Step 3. Fix signature matching again +=== Step 3. Fix signature matching again In org.aspectj.weaver.patterns.SignaturePattern.matches, we need to handle throw signature matching the same way we handle advice signature @@ -777,7 +777,7 @@ Member.THROW. This problem only shows up when we try to print thisJoinPoint. It's showing that we haven't updated the reflection API to understand this new signature kind. -==== Step 4. Extend org.aspectj.lang.reflect to understand throw signatures +=== Step 4. Extend org.aspectj.lang.reflect to understand throw signatures We need to add a couple of classes to the reflection API to implement the throw signature. Because we decided at the beginning of this section @@ -906,7 +906,7 @@ about to throw: 'java.lang.RuntimeException: expected exception' at throw(throw) PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 1 seconds .... -==== Step 5. Extend the test for automated coverage of reflection +=== Step 5. Extend the test for automated coverage of reflection Modify the before advice to include at least minimal checks of the new reflective information: @@ -927,14 +927,14 @@ working version of the throw join point and there are no obvious pieces that we've skipped. Take a break before proceeding to the final phase of tests. -=== Part 3: More serious testing +== Part 3: More serious testing Now it's time to get a decent testing story. The test work that we will do here is probably too little for adding a new join point to the aspectj language; however, it should at least give you a sense of what's involved. -==== Step 1. Run the test suite again +=== Step 1. Run the test suite again Rerun the tests you ran at the beginning of part 1. Any failures that occur should be resolved at this point. At the time of writing this @@ -972,7 +972,7 @@ noted in the release notes for any AspectJ release. Since we're not writing documentation in this tutorial, we will move on an fix the test case. -==== Step 2. Fix the failing test case +=== Step 2. Fix the failing test case Now we need to fix this failing test case. The first step is to copy the test specification into our local myTests.xml file. The easiest way to @@ -1001,7 +1001,7 @@ new expected event between these two: Run the test suite again to see that this test now passes. -==== Step 3. Extend test coverage to after advice +=== Step 3. Extend test coverage to after advice There is a lot we should do now to extend test coverage for this new kind of join point. For the purpose of this tutorial, we're just going @@ -1060,7 +1060,7 @@ property of the orthogonality of the implementation of join points and advice. We never had to do any implementation work to make our new join point kind work for before and all three kinds of after advice. -==== Step 4. Look at around advice on throw join points +=== Step 4. Look at around advice on throw join points Let's create a new test case to see how this new join point interacts with around advice. @@ -1120,7 +1120,7 @@ best design. For the purpose of this tutorial we're once again going to make the language design choice that is easiest to implement and press on. -==== Step 5. Prohibit around advice on this new join point kind +=== Step 5. Prohibit around advice on this new join point kind The easiest solution to implement is to prohibit around advice on throw join points. There are already a number of these kinds of rules @@ -1169,7 +1169,7 @@ following specification: Run myTests.xml one last time to see both tests passing. -==== Step 6. Final preparations for a commit or patch +=== Step 6. Final preparations for a commit or patch You probably want to stop here for the purposes of this tutorial. We've pointed out several language design decisions that would need to be diff --git a/docs/modules/ROOT/pages/developer/language.adoc b/docs/modules/ROOT/pages/developer/language.adoc index 28a3f7548..45ee827ad 100644 --- a/docs/modules/ROOT/pages/developer/language.adoc +++ b/docs/modules/ROOT/pages/developer/language.adoc @@ -1,6 +1,6 @@ -== AspectJ Language Design += AspectJ Language Design -=== User-suggested New Language Features +== User-suggested New Language Features * `-` wildcard ** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00717.html @@ -13,9 +13,9 @@ ** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00458.html ** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00467.html + -=== Key Language Design Properties +== Key Language Design Properties -==== Orthogonal join point model +=== Orthogonal join point model The different kinds of join points, the different primitive pointcuts, and the different kinds of @@ -25,7 +25,7 @@ This was one of the hardest parts of the design to get right, because of the "constructor must call super" rule in Java. But we finally got this in 1.0. -==== Pointcuts support composition and abstraction +=== Pointcuts support composition and abstraction Abelson and Sussman say that composition and abstraction are the key elements of a real @@ -45,18 +45,18 @@ pointcut topLevelStateChange(): stateChange() && !cflowbelow(stateChange()); is what makes it possible for people to really work with crosscutting structure and make their code more clear. -==== Statically type checked +=== Statically type checked The efficiency, code quality and programmer productivity arguments for this have been made elsewhere, so I won't repeat them. -==== Efficient +=== Efficient AspectJ code is as fast as the equivalent functionality, written by hand, in a scattered and tangled way. -==== Simple kernel +=== Simple kernel I've heard some people say that AspectJ is too big and too complex. In the most important sense of simple AspectJ is @@ -69,7 +69,7 @@ the right idea for a standard AOP API is this kernel, packaged in a way that allows building more sophisticated tools on top of it. -==== Supports multiple weave times +=== Supports multiple weave times AspectJ is neutral on whether weaving happens at pre-process, compile, post-process, load, JIT or runtime. diff --git a/docs/modules/ROOT/pages/developer/modules.adoc b/docs/modules/ROOT/pages/developer/modules.adoc index 74292212b..2cb60910f 100644 --- a/docs/modules/ROOT/pages/developer/modules.adoc +++ b/docs/modules/ROOT/pages/developer/modules.adoc @@ -1,10 +1,10 @@ -== AspectJ Modules += AspectJ Modules There are a number of different structures [Parnas]: "the module structure, the uses structure, the runtime structure, ..." This document overviews module structure and summarizes what is hidden by each. For detailed documentation refer to the individual module sources and docs available via CVS. -=== Core Modules +== Core Modules *CVS Location:* dev.eclipse.org:/cvsroot/technology/org.aspectj/modules @@ -50,7 +50,7 @@ bytecode toolkit. All advice planning and weaving is done here. Takes an aspect classfiles as input. |=== -=== Supporting Modules +== Supporting Modules *CVS Location:* dev.eclipse.org:/cvsroot/technology/org.aspectj/modules @@ -66,7 +66,7 @@ classfiles as input. | tests | AspectJ test suite, including all language tests, regression tests, and test system sources |=== -=== Eclipse AspectJ Development Tools (AJDT) +== Eclipse AspectJ Development Tools (AJDT) *CVS Location:* dev.eclipse.org:/cvsroot/technology/org.eclipse.ajdt/plugins/org.eclipse.ajdt diff --git a/docs/modules/ROOT/pages/examples/spacewar/README.adoc b/docs/modules/ROOT/pages/examples/spacewar/README.adoc index 9991867a3..d39b9b5fc 100644 --- a/docs/modules/ROOT/pages/examples/spacewar/README.adoc +++ b/docs/modules/ROOT/pages/examples/spacewar/README.adoc @@ -1,5 +1,5 @@ [[_5]] -== Exploring the Spacewar Example += Exploring the Spacewar Example _© Copyright 1997-2001 Xerox Corporation. All rights reserved._ @@ -19,13 +19,13 @@ the helloworld example first by following the instructions in xref:../doc/primer/default.html[Primer] section Getting Started. [[_5_1]] -=== Compiling Spacewar +== Compiling Spacewar * Change to the `examples` directory. * Type `ajc -argfile spacewar/demo.lst` to compile the system. [[_5_2]] -=== Running Spacewar +== Running Spacewar * In the examples directory, type `java spacewar.Game` @@ -42,7 +42,7 @@ focus so that your keystrokes are recognized. You can quit the game with ctl-Q. [[_5_3]] -=== Exploring the Code +== Exploring the Code There is one other built-in configurations for the Spacewar game. Try it by typing `ajc @spacewar\debug.lst`. This compiles in an elaborate diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 4daa8ee0a..32a8d2001 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,5 +1,5 @@ [[top]] -== AspectJ Documentation and Resources += AspectJ Documentation and Resources AspectJ^TM^ is a seamless aspect-oriented extension to Java^TM^. The compiler and development tools are available under an open-source license, require Java 8 to run, and produce code that runs in JDK 1.3 and later VM's. For the latest @@ -27,7 +27,7 @@ mailto:aspectj-users@eclipse.org[users] and mailto:aspectj-dev@eclipse.org[devel |=== [[documentation]] -=== AspectJ documentation +== AspectJ documentation [width="100%",cols="50%,50%",options="header",] |=== @@ -144,7 +144,7 @@ a|AspectJ Design Overview [[distributions]] -=== AspectJ distributions +== AspectJ distributions [cols=",",options="header",] |=== @@ -167,7 +167,7 @@ eclipse.org project site https://eclipse.org/ajdt [[resources]] -=== Other AspectJ resources +== Other AspectJ resources [cols=",",options="header",] |=== @@ -193,7 +193,7 @@ See the xref:faq/faq.adoc#ajcbugs[FAQ entry] for instructions on submitting comp |=== [[paths]] -=== Suggested learning paths for those new to AspectJ +== Suggested learning paths for those new to AspectJ To learn the AspectJ language, read the xref:progguide/index.adoc[Programming Guide], keeping the xref:progguide/semantics.adoc[Semantics appendix] nearby as the best reference for AspectJ usage. Focus initially on the diff --git a/docs/modules/ROOT/pages/sandbox/ubc-design-patterns/patterns-readme.adoc b/docs/modules/ROOT/pages/sandbox/ubc-design-patterns/patterns-readme.adoc index ade559c2d..7820d8b01 100644 --- a/docs/modules/ROOT/pages/sandbox/ubc-design-patterns/patterns-readme.adoc +++ b/docs/modules/ROOT/pages/sandbox/ubc-design-patterns/patterns-readme.adoc @@ -1,4 +1,4 @@ -== AspectJ Patterns += AspectJ Patterns _Last updated: 2004-03-31 by wisberg_ diff --git a/docs/modules/ROOT/pages/teaching/exercises/plugins/index.adoc b/docs/modules/ROOT/pages/teaching/exercises/plugins/index.adoc index 1cdf0fbc1..9a70bf6a9 100644 --- a/docs/modules/ROOT/pages/teaching/exercises/plugins/index.adoc +++ b/docs/modules/ROOT/pages/teaching/exercises/plugins/index.adoc @@ -1,4 +1,4 @@ -== Exercises plugin for the tutorial += Exercises plugin for the tutorial Download the appropriate version and unzip it in your eclipse\plugins directory: |