From a6a1dbea46fd4829189b23fb900da6a586a8151a Mon Sep 17 00:00:00 2001 From: Alexander Kriegisch Date: Fri, 16 Jul 2021 10:48:06 +0700 Subject: Fix more AsciiDoc links and code blocks (WIP) - Add Java syntax highlighting to AspectJ and Java files - Add XML syntax highlighting to XML files (Ant, LTW etc.) - Dedent and remove empty lines, where necessary - Enclose in-line line numbers for Java code in /*23*/ comments in order to enable Java formatting Signed-off-by: Alexander Kriegisch --- docs/faq/faq.adoc | 84 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 47 insertions(+), 37 deletions(-) (limited to 'docs/faq') diff --git a/docs/faq/faq.adoc b/docs/faq/faq.adoc index 903406d48..0c6333668 100644 --- a/docs/faq/faq.adoc +++ b/docs/faq/faq.adoc @@ -140,9 +140,9 @@ must be able to reach classes in the small (< 100K) runtime library *A:* From AspectJ's http://eclipse.org/aspectj[web page] , download the AspectJ distribution. The `jar` file is installed by executing +[source, text] .... java -jar jar file name - .... Do *not* try to extract the `jar` file contents and then attempt to @@ -503,6 +503,7 @@ AKA agile methods)? *A:* From a question on the user list: +[source, text] .... > Anyone know the connections between AOP and Extreme Programming? > I am really confused. It seems AOP is a programming paradigm, which @@ -510,7 +511,6 @@ AKA agile methods)? > this is a lightweight software development process. One of the common > motivations of AOP and XP is designed to adopt to the requirement > changes, so that it can save the cost of software development. - .... This is Raymond Lee's answer: @@ -649,6 +649,7 @@ in a modular way, something that would otherwise be spread throughout the code. Consider the following code, adapted from the AspectJ tutorial: +[source, java] .... aspect PublicErrorLogging { Log log = new Log(); @@ -660,7 +661,6 @@ aspect PublicErrorLogging { log.write(o, e); } } - .... The effect of this code is to ensure that whenever any public method of @@ -838,6 +838,7 @@ below shows how the different profiles build on top of the two configurations CDC (Connected Device Configuration) and CLDC (Connected Limited Device Configuration): +[source, text] .... -------------- | Personal | @@ -848,7 +849,6 @@ Limited Device Configuration): ------------------------------------------ | Java | ------------------------------------------ - .... Which configuration you have dictates the restrictions when running @@ -1007,18 +1007,18 @@ Environment Guide] link:devguide/ajc-ref.html[Reference for ajc]. line-delimited text file and direct ajc to that file using `-argfile` or `@`: +[source, text] .... ajc @sources.lst ajc -argfile sources.lst - .... Another way in AspectJ 1.1 is to use the `-sourceroots` options, which reads all source files in a given set of directories: +[source, text] .... ajc -sourceroots "src;testsrc" - .... For more information, see the link:devguide/index.html[Development @@ -1063,23 +1063,23 @@ Here's an example of using `ajc` in this sort of cross-compilation mode (assuming a Windows platform with all the default installation directories): +[source, text] .... ajc -target 1.1 -bootclasspath c:\jdk1.1.7\lib\classes.zip \ -classpath c:\aspectj1.0\lib\aspectjrt.jar -extdirs "" \ -argfile jdk11system.lst - .... This same technique can be used if you want to run `ajc` on a JDK 1.3 JVM (highly recommended) but need to generate code for JDK 1.2. That would look something like: +[source, text] .... ajc -bootclasspath c:\jdk1.2\jre\lib\rt.jar \ -classpath c:\aspectj1.0\lib\aspectjrt.jar \ -extdirs c:\jdk1.2\jre\lib\ext -argfile jdk12system.lst - .... *Q:* Does the `ajc` compiler support the `assert` keyword in Java 1.4? @@ -1226,10 +1226,10 @@ which will be affected by any advice specifying the same pointcut. For example, the following will print a warning whereever some code in class Bar gets a field value from Foo: +[source, java] .... declare warning: get(* Foo.*) && within(Bar) : "reading Foo state from Bar"; - .... When you are running your program, you can trace advice as it executes. @@ -1282,6 +1282,7 @@ use implement a hybrid build process by listing the production source files into a javac-compliant argfile, and the development source files in another ajc argfiles: +[source, text] .... -- file "production.lst": One.java @@ -1295,21 +1296,20 @@ Trace.java -- file "development.lst": @production.lst @tracing.lst - .... Then your development build can use `ajc`: +[source, text] .... ajc @development.lst - .... And your development build can use `ajc` or `javac` or `jikes`: +[source, text] .... jikes @production.lst - .... *Q:* We compile module jars and then assemble them. Can we continue this @@ -1331,6 +1331,7 @@ are visible to other clients, which themselves are otherwise unaffected by the aspects. In this case, the common library can be built using ajc, and used on the classpath for the module builds: +[source, text] .... ajc -outjar common.jar -sourceroots "aspectj-src:src" ... cd ../otherProject @@ -1342,6 +1343,7 @@ should affect two or more modules that are in a dependency relationship to one another. It should work to reuse the aspects in binary form for each compile, in dependency order: +[source, text] .... ajc -outjar common-aspects.jar -sourceroots "aspectj-src" ... @@ -1380,6 +1382,7 @@ libraries). In Eclipse's AJDT, you can create a top-level project with symbolic links out to the sources: +[source, text] .... app-assembly/ {link common/aspects} @@ -1425,6 +1428,7 @@ Here's some code Jim Hugunin wrote to trace join points and posted to the users list. To reuse the aspect, define a subaspect and implement the pointcuts, for example: +[source, java] .... aspect JoinPointSampleAspect extends aj.TraceJoinPoints { protected pointcut entry() : @@ -1442,11 +1446,11 @@ aspect JoinPointSampleAspect extends aj.TraceJoinPoints { class JoinPointSample { public static void main(String[] args) {} } - .... Here's the aspect: +[source, java] .... /* TraceJoinPoints.java */ @@ -1639,6 +1643,7 @@ call? How about the most-recent prior entrypoint? most-recent recursive call or (b) the current and original recursive call: +[source, java] .... aspect LogFactorial { pointcut f(int i) : call(int factorial(int)) && args(i); @@ -1654,7 +1659,6 @@ aspect LogFactorial { System.err.println(i + "@" + j); } } - .... *Q:* What is the difference between constructor call, constructor @@ -1672,6 +1676,7 @@ constructor call obtained using `TraceJointPoints.java` from #q:seeingjoinpoints[Q:I don't understand what join points exist. How can I see them?]. +[source, java] .... public class Init { public static void main (String[] args) { @@ -1689,6 +1694,7 @@ class Test extends Super implements I { For a program compiled with AspectJ 1.0, the result is this: +[source, xml] .... @@ -1723,9 +1729,9 @@ of thumb: * If you want the join point on the "outside" of object creation, use after returning from call to the constructor: + +[source, java] .... after() returning (Foo newlyCreatedObject): call(Foo.new(..)) { ... } - .... + You might be tempted to use "this" or "target" to expose the new object, @@ -1734,9 +1740,9 @@ object itself might not be created yet... it only exists "on the way out", when you return the object. * If you want the join point inside a particular constructor, use: + +[source, java] .... after(Foo newlyCreatedObject) returning: this(newlyCreatedObject) && execution(Foo.new(..)) { ... } - .... + Remember, though, that if you use "before" advice here, the body of the @@ -1747,9 +1753,9 @@ object that call each other with `this(...)` and you want exactly one join point for each initialization of `Foo`, regardless of the path of constructors it takes, then use: + +[source, java] .... after(Foo f) returning: this(f) && initialization(Foo.new(..)) { ... } - .... *Q:* I want advice to run at two join points, but it doesn't run at all. @@ -1759,9 +1765,9 @@ What gives? mistake. Most likely you want to do something like "run the advice for all public and private calls," and the code looks something like this: +[source, java] .... within(com.xerox.printing..*) && call(public * *(..)) && call(private * *(..)) - .... But a pointcut is evaluated at *each* join point. The expression above @@ -1770,9 +1776,9 @@ has both public and private access. In a pointcut, `pc1() && pc2()` means both must be true at a given join point for advice to run at that join point. The correct pointcut would use `||` as follows: +[source, java] .... within(com.xerox.printing..*) && (call(public * *(..)) || call(private * *(..))) - .... Then the advice will run at the join point. @@ -1796,6 +1802,7 @@ limited to a certain set of classes. Do I have to retype it each time? *A:* No. You can declare that all the types implement an interface you define, and then use the interface type in your program. For example: +[source, java] .... /** * Example of using an interface to represent a type pattern. @@ -1821,7 +1828,6 @@ abstract aspect MarkerExample { aspect MyMarker extends MarkerExample { declare parents: com.mycompany.whatever..* implements Marked; } - .... *Q:* Where do I find example programs and how-to's? @@ -1886,6 +1892,7 @@ Specification] . here is the HTML code for an HTML editor applet that contains some debugging aspects: +[source, xml] .... - .... [[aj11]] @@ -2653,6 +2661,7 @@ only XML. This means aspect developers can write abstract aspects, and deployers need only configure `aop.xml` and run using the AspectJ weaver in Java 5. For example, to run Java 5 VM with load-time weaving, +[source, text] .... java -javaagent:aspectjweaver.jar -classpath "aspects.jar:${CLASSPATH}" .. .... @@ -2661,6 +2670,7 @@ To declare a concrete aspect, add a a concrete-aspect XML entity to `META-INF/aop.xml`. This example extends a tracing aspect to apply to every type in the application: +[source, xml] .... @@ -3137,10 +3148,10 @@ tree as described in #q:buildingsource[Q:How do I get and compile the source code for AspectJ?] and then build the `build-testing-drivers` target: +[source, text] .... cd build ../lib/ant/bin/ant -f build.xml build-testing-drivers - .... This produces `../aj-build/jars/testing-drivers-all.jar` which you can @@ -3237,8 +3248,7 @@ http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AJDT ). Bug reports on ajbrowser should have version information for both Java and AspectJ, and (most importantly) clear steps for reproducing the bug. You may submit ajbrowser bugs against the IDE component of AspectJ via -the web form http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ -. +the web form http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ. One of the benefits of open-source is that you can find and fix the bug for yourself; when you submit the fix back to us, we can validate the @@ -3422,7 +3432,7 @@ More details for 1.0 and earlier releases are available in changes.html. *Q:* What is the AspectJ development schedule? *A:* Below is a table describing the goals for the major releases. For -information about specific features, search the bug database for `RFE`'s +information about specific features, search the bug database for ``RFE``'s ("requests for enhancement") by http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&bug_severity=enhancement[selecting severity of "enhancement"]. Like many open-source projects, we don't -- cgit v1.2.3