[jboss-cvs] JBossAS SVN: r63207 - in projects/aop/trunk/aop/docs/reference/reference/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri May 25 00:50:36 EDT 2007
Author: flavia.rainone at jboss.com
Date: 2007-05-25 00:50:36 -0400 (Fri, 25 May 2007)
New Revision: 63207
Added:
projects/aop/trunk/aop/docs/reference/reference/en/modules/jdk14compatibility.xml
Removed:
projects/aop/trunk/aop/docs/reference/reference/en/modules/annotationcompiler.xml
Modified:
projects/aop/trunk/aop/docs/reference/reference/en/master.xml
projects/aop/trunk/aop/docs/reference/reference/en/modules/annotated.xml
Log:
[JBAOP-400] The references to jdk1.4 have been commented, and the text, adapted.
Modified: projects/aop/trunk/aop/docs/reference/reference/en/master.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/reference/en/master.xml 2007-05-24 22:24:03 UTC (rev 63206)
+++ projects/aop/trunk/aop/docs/reference/reference/en/master.xml 2007-05-25 04:50:36 UTC (rev 63207)
@@ -9,7 +9,7 @@
<!ENTITY xml SYSTEM "modules/xml.xml">
<!ENTITY annotated SYSTEM "modules/annotated.xml">
<!ENTITY dynamic SYSTEM "modules/dynamic.xml">
-<!ENTITY annotationcompiler SYSTEM "modules/annotationcompiler.xml">
+<!ENTITY jdk14compatibility SYSTEM "modules/jdk14compatibility.xml">
<!ENTITY installing SYSTEM "modules/installing.xml">
<!ENTITY compiling SYSTEM "modules/compiling.xml">
<!ENTITY running SYSTEM "modules/running.xml">
@@ -98,7 +98,7 @@
&dynamic;
- &annotationcompiler;
+ &jdk14compatibility;
&installing;
Modified: projects/aop/trunk/aop/docs/reference/reference/en/modules/annotated.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/reference/en/modules/annotated.xml 2007-05-24 22:24:03 UTC (rev 63206)
+++ projects/aop/trunk/aop/docs/reference/reference/en/modules/annotated.xml 2007-05-25 04:50:36 UTC (rev 63207)
@@ -7,17 +7,17 @@
<para>
JDK 5.0 has introduced a new concept called annotations. Annotations can be
used as an alternative to XML for configuring classes for AOP. For backward compatibility
- with JDK 1.4.2 JBoss AOP uses an annotation compiler allowing you to create the same annotations
- in javadoc style comments.
+ with JDK 1.4.2 <!-- JBoss AOP uses an annotation compiler allowing you to create the same annotations
+ in javadoc style comments. -->, refer to XXX.
</para>
- <para>
+<!-- <para>
The JDK 5 form has been used for the declarations of each annotation type shown below. For
clarity both types of annotations are shown in the usage examples contained in this chapter.
A point worth mentioning is that in JDK 5 annotations are part of language and can thus
be imported, so that just the classname can be used. In JDK 1.4.2 the annotations are not
part of "Java" so fully qualified classnames are needed. To keep things short and sweet
the listings only import classes that are new for each listing.
- </para>
+ </para> -->
<!-- *********************************** Aspect ******************************** -->
@@ -59,10 +59,10 @@
PER_VM, PER_CLASS, PER_INSTANCE, PER_JOINPOINT
}
</programlisting>
- See the "XML Bindings" chapter for a description of the various scopes.
+ See <xref linkend="xml-aspect2"/> for a description of the various scopes.
</para>
<para>
- In JDK 5 we use the @Aspect annotation as follows:
+ We use the @Aspect annotation as follows:
<programlisting>
package com.mypackage;
@@ -77,24 +77,9 @@
}
</programlisting>
- And in JDK 1.4.2:
- <programlisting>
- package com.mypackage;
-
- /**
- * @@Aspect (scope = Scope.PER_VM)
- */
- public class MyAspect
- {
- public Object myAdvice(Invocation invocation)
- {
- return invocation.invokeNext();
- }
- }
- </programlisting>
</para>
<para>
- The name of the class (in this case com.mypackage.MyAspect) gets used as the
+ The name of the class (in this case <literal>com.mypackage.MyAspect</literal>) gets used as the
internal name of the aspect. The equivalent using XML configuration would be:
<programlisting>
<aop>
@@ -137,7 +122,7 @@
<sect2 id="annotated-interceptor-interceptor" revision="1">
<title>Interceptor Example</title>
<para>
- In JDK 5 we use the
+ We use the
<literal>@InterceptorDef</literal> annotation to mark
an Interceptor as follows:
<programlisting>
@@ -158,7 +143,7 @@
}
</programlisting>
- And in JDK 1.4.2:
+<!-- And in JDK 1.4.2:
<programlisting>
package com.mypackage;
@@ -173,10 +158,10 @@
return invocation.invokeNext();
}
}
- </programlisting>
+ </programlisting> -->
</para>
<para>
- The name of the class (in this case com.mypackage.MyInterceptor) gets used as the
+ The name of the class (in this case <literal>com.mypackage.MyInterceptor</literal>) gets used as the
class name of the interceptor. The equivalent using XML configuration would be:
<programlisting>
<aop>
@@ -205,7 +190,7 @@
}
</programlisting>
</para>
- <para>
+<!-- <para>
And in JDK 1.4.2:
<programlisting>
package com.mypackage;
@@ -229,7 +214,7 @@
<interceptor factory="com.mypackage.MyInterceptorFactory" scope="PER_VM"/>
</aop>
</programlisting>
- </para>
+ </para> -->
</sect2>
</sect1>
@@ -263,7 +248,7 @@
</para>
<para>
An example of an aspect class containing a named pointcut which it references from
- a bindng's pointcut expression in JDK 5:
+ a bindng's pointcut expression:
<programlisting>
package com.mypackage;
@@ -287,7 +272,7 @@
outside the class they are declared in (if the annotated fields are declared
public of course!).
</para>
- <para>
+<!-- <para>
The same example in JDK 1.4.2:
<programlisting>
package com.mypackage;
@@ -311,7 +296,7 @@
}
}
</programlisting>
- </para>
+ </para> -->
<para>
Using XML configuration this would be:
<programlisting>
@@ -380,7 +365,7 @@
<programlisting><name of the Interceptor/AspectFactory implementation class></programlisting>
</para>
<para>
- An example of a binding using an advice method in an aspect class in JDK 5:
+ An example of a binding using an advice method in an aspect class:
<programlisting>
package com.mypackage;
@@ -407,9 +392,10 @@
}
</programlisting>
+ </para>
<para>
</para>
- And in JDK 1.4.2:
+<!-- And in JDK 1.4.2:
<programlisting>
package com.mypackage;
@@ -441,7 +427,7 @@
}
}
</programlisting>
- </para>
+ </para> -->
The equivalent using XML configuration would be:
<programlisting>
<aop>
@@ -524,8 +510,7 @@
but not both.
</para>
<para>
- This is how to use
- <literal>@Introduction</literal> in JDK 5:
+ This is how to use this annotation:
<programlisting>
package com.mypackage;
@@ -539,7 +524,7 @@
public static Object pojoNoInterfacesIntro;
}
</programlisting>
- And in JDK 1.4.2:
+<!-- And in JDK 1.4.2:
<programlisting>
package com.mypackage;
@@ -557,7 +542,7 @@
</programlisting>
Notice the slight difference in the JDK 1.4.2 annotation, the class values don't have
- the ".class" suffix.
+ the ".class" suffix. -->
</para>
<para>
This means make
@@ -641,7 +626,7 @@
</para>
<para>
An example aspect using
- <literal>@Mixin</literal> in JDK 5:
+ <literal>@Mixin</literal> follows:
<programlisting>
package com.mypackage;
@@ -657,7 +642,7 @@
}
}
</programlisting>
- Here's the JDK 1.4.2 version:
+<!-- Here's the JDK 1.4.2 version:
<programlisting>
package com.mypackage;
@@ -677,7 +662,7 @@
return new ExternalizableMixin(pojo);
}
}
- </programlisting>
+ </programlisting>-->
</para>
<para>
Since this is slightly more complex than the previous examples we have seen, the
@@ -721,7 +706,6 @@
}
}
</programlisting>
-
<para>
This has the same effect as the following XML configuration:
<programlisting>
@@ -767,7 +751,7 @@
</para>
<para>
To use
- <literal>@Prepare</literal> in JDK 5:
+ <literal>@Prepare</literal> follow this example:
<programlisting>
package com.mypackage;
@@ -787,7 +771,7 @@
}
</programlisting>
- And in JDK 1.4.2:
+ <!-- And in JDK 1.4.2:
<programlisting>
package com.mypackage;
@@ -808,7 +792,7 @@
}
}
</programlisting>
-
+-->
</para>
<para>
Using XML configuration instead we would write:
@@ -840,7 +824,7 @@
You can also annotate a POJO with @Prepare directly in cases where
you are using Dynamic AOP, and the exact bindings are not known at
instrumentation time. In this case you annotate the class itself.
- Here's how it is done in JDK 5:
+ Here's how it is done:
<programlisting>
package com.mypackage;
@@ -856,7 +840,7 @@
<literal>all(com.blah.MyDynamicPOJO)</literal>, but the use of
<literal>all(this)</literal> is recommended.
</para>
- <para>
+<!-- <para>
JDK 1.4:
<programlisting>
package com.mypackage;
@@ -871,7 +855,7 @@
...
}
</programlisting>
- </para>
+ </para> -->
<para>
The examples just given equate to this XML
<programlisting>
@@ -915,7 +899,7 @@
<programlisting><name of @Aspect/@InterceptorDef annotated class>.<name of @TypeDef annotated field></programlisting>
</para>
<para>
- Here's how to use it with JDK 5:
+ Here's how to use it:
<programlisting>
package com.mypackage;
@@ -936,7 +920,7 @@
}
</programlisting>
</para>
- <para>
+<!-- <para>
And with JDK 1.4.2:
<programlisting>
package com.mypackage;
@@ -964,7 +948,7 @@
}
}
</programlisting>
- </para>
+ </para> -->
<para>
The equivalent using XML configuration would be:
<programlisting>
@@ -1028,7 +1012,7 @@
<programlisting><name of @Aspect/@InterceptorDef annotated class>.<name of @CFlowStackDef annotated field></programlisting>
</para>
<para>
- CFlowStackDef is used like this in JDK 5:
+ CFlowStackDef is used like the following example:
<programlisting>
package com.mypackage;
@@ -1053,7 +1037,7 @@
}
</programlisting>
</para>
- <para>
+<!-- <para>
And in 1.4.2:
<programlisting>
@@ -1084,7 +1068,7 @@
}
}
</programlisting>
- </para>
+ </para> -->
<para>
The above means the same as this XML:
<programlisting>
@@ -1117,7 +1101,7 @@
</programlisting>
</para>
<para>
- Here is a @DynamicCFlow annotated class in JDK 5:
+ Here is a @DynamicCFlow annotated class:
<programlisting>
package com.mypackage;
@@ -1136,7 +1120,7 @@
}
</programlisting>
</para>
- <para>
+<!-- <para>
And the same in JDK 1.4.2:
<programlisting>
package com.mypackage;
@@ -1155,13 +1139,14 @@
return execute;
}
}
- </programlisting>
+ </programlisting> -->
+ <para>
The name of the
<literal>@DynamicCFlowDef</literal> annotated class gets used as
the name of the cflow for references.
</para>
<para>
- To use the dynamic cflow we just defined in JDK 5:
+ To use the dynamic cflow we just defined:
<programlisting>
package com.mypackage;
@@ -1177,7 +1162,7 @@
}
</programlisting>
</para>
- <para>
+<!-- <para>
To use the dynamic cflow we just defined in JDK 5:
<programlisting>
package com.mypackage;
@@ -1197,7 +1182,7 @@
}
}
</programlisting>
- </para>
+ </para>-->
</sect1>
<!-- *********************************** Annotation Intro ******************************** -->
@@ -1254,7 +1239,7 @@
</para>
<para>
The use of
- <literal>@AnnotationIntroductionDef</literal> in JDK 5:
+ <literal>@AnnotationIntroductionDef</literal>:
<programlisting>
package com.mypackage;
@@ -1287,7 +1272,7 @@
<literal>@com.mypackage.MyAnnotation</literal> must use the
fully qualified class name, and that the value for its string parameter uses single quotes.
</para>
- <para>
+<!-- <para>
The use of
<literal>@AnnotationIntroductionDef</literal> in JDK 1.4.2:
<programlisting>
@@ -1322,7 +1307,7 @@
}
</programlisting>
Note that the reference to only uses one '@', and that the value for its string parameter uses single quotes.
- </para>
+ </para> -->
<para>
The previous listings are the same as this XML configuration:
<programlisting>
@@ -1377,7 +1362,7 @@
<para>
The example shown below declares a relative sort order where <literal>org.acme.Interceptor</literal>
must always be invoked before <literal>org.acme.Aspect.advice1()</literal> which must be invoked before
- <literal>org.acme.Aspect.advice2()</literal>. Here is the JDK 5 version:
+ <literal>org.acme.Aspect.advice2()</literal>:
</para>
<programlisting>
import org.jboss.aop.Precedence;
@@ -1396,7 +1381,7 @@
org.acme.Aspect precAdvice2;
}
</programlisting>
- <para>
+<!-- <para>
And the JDK 1.4 version:
</para>
<programlisting>
@@ -1420,7 +1405,7 @@
*/
org.acme.Aspect precAdvice2;
}
- </programlisting>
+ </programlisting> -->
<para>
The ordering of interceptors/advices defined via annotations that have no precedence defined, is arbitrary.
</para>
@@ -1461,7 +1446,7 @@
the message to print out if a match is found for the pointcut. If you use
<literal>DeclareWarning</literal> instrumentation/your application will simply continue having printed the
message you supplied. In the case of <literal>DeclareError</literal>, the message is logged and an error is
- thrown, causing instrumentation/your application to stop. Here is an example in JDK 5
+ thrown, causing instrumentation/your application to stop. Here is an example:
</para>
<programlisting>
import org.jboss.aop.Aspect;
@@ -1483,7 +1468,7 @@
Pointcut error;
}
</programlisting>
- <para>
+<!-- <para>
And in JDK 1.4:
</para>
<programlisting>
@@ -1508,7 +1493,7 @@
*/
Pointcut error;
}
- </programlisting>
+ </programlisting> -->
</sect1>
Deleted: projects/aop/trunk/aop/docs/reference/reference/en/modules/annotationcompiler.xml
===================================================================
--- projects/aop/trunk/aop/docs/reference/reference/en/modules/annotationcompiler.xml 2007-05-24 22:24:03 UTC (rev 63206)
+++ projects/aop/trunk/aop/docs/reference/reference/en/modules/annotationcompiler.xml 2007-05-25 04:50:36 UTC (rev 63207)
@@ -1,373 +0,0 @@
-<chapter id="annotationcompiler">
- <title>Annotation Compiler for JDK 1.4</title>
- <sect1 id="annotationcompiler-annotations" revision="1">
- <title>Annotations with JDK 1.4.2</title>
-
- <para>
- Annotations are only available in JDK 5, but using our annotation compiler
- you can acheive similar functionality with JDK 1.4.2.
- </para>
-
- <para>
- Annotations must map to an annotation type, in JDK 5 they are defined as:
-
- <programlisting>
- package com.mypackage;
-
- public @interface MyAnnotation
- {
- String myString();
- int myInteger();
- }
- </programlisting>
-
- Annotation types for use with the annotation compiler are defined in exactly
- the same way for JDK 1.4.2, with the important difference that '@interface'
- is replaced by 'interface'. i.e. the simulater annotation type is a normal
- Java interface:
- <programlisting>
- package com.mypackage;
-
- public interface MyAnnotation
- {
- String myString();
- int myInteger();
- }
- </programlisting>
- </para>
-
- <para>
- The syntax for using annotations in JDK 1.4.2 is almost exactly the same as
- JDK 5 annotations except for these subtle differences:
- <itemizedlist>
- <listitem>they are embedded as doclet tags</listitem>
- <listitem>You use a double at sign, i.e. '@@'</listitem>
- <listitem>
- You MUST have a space after the tag name otherwise you will get
- a compilation error. (This is the quirkiness of the QDox doclet compiler
- used to compile the annotations.')
- </listitem>
- <listitem>
- You cannot import the annotation type, you must use the fully
- qualified name of the interface.
- </listitem>
- <listitem>
- You can only annotate top-level and inner classes, and their constructors, methods and fields.
- Annotating anonyomus classes, local classes, and parameters for constructors or methods is not supported.
- </listitem>
- <listitem>You cannot specify default values for an annotation's value</listitem>
- </itemizedlist>
- </para>
-
- <para>
- This example shows an annotated class in JDK 1.4.2:
- <programlisting>
- package com.mypackage;
-
- /**
- * @@com.mypackage.MyAnnotation (myString="class", myInteger=5)
- */
- public class MyClass
- {
- /**
- * @@com.mypackage.MyAnnotation (myString="field", myInteger=4)
- */
- private String myField;
-
- /**
- * @@com.mypackage.MyAnnotation (myString="constructor", myInteger=3)
- */
- public MyClass()
- {
- }
-
- /**
- * @@com.mypackage.MyAnnotation (myString="method", myInteger=3)
- */
- public int myMethod()
- {
- }
- }
- </programlisting>
- </para>
-
- </sect1>
- <sect1 id="annotationcompiler-enums" revision="1">
- <title>Enums in JDK 1.4.2</title>
- <para>
- Another JDK 5 feature that JBoss AOP helps introduce to JBoss 1.4.2 are Enums.
- As an example we can look at the
- <literal>org.jboss.aop.advice.Scope</literal>
- enum that is used for the
- <literal>@Aspect</literal> annotation. Here is the
- JDK 5 version.
- <programlisting>
- package org.jboss.aop.advice;
-
- public enum Scope
- {
- PER_VM, PER_CLASS, PER_INSTANCE, PER_JOINPOINT
- }
- </programlisting>
-
- And it's usage in JDK 5
- <programlisting>
- package com.mypackage;
-
- @Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
- public class SomeAspect
- {
- }
- </programlisting>
- The usage in JDK 1.4.2 is similar:
- <programlisting>
- package com.mypackage;
-
- /**
- * @@org.jboss.aop.Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
- */
- public class SomeAspect
- {
- //...
- }
- </programlisting>
- However the declaration of the enumeration is different in 1.4.2:
- <programlisting>
- package org.jboss.aop.advice;
-
- import java.io.ObjectStreamException;
-
- public class Scope extends org.jboss.lang.Enum
- {
- private Scope(String name, int v)
- {
- super(name, v);
- }
-
- public static final Scope PER_VM = new Scope("PER_VM", 0);
- public static final Scope PER_CLASS = new Scope("PER_CLASS", 1);
- public static final Scope PER_INSTANCE = new Scope("PER_INSTANCE", 2);
- public static final Scope PER_JOINPOINT = new Scope("PER_JOINPOINT", 3);
-
- private static final Scope[] values = {PER_VM, PER_CLASS, PER_INSTANCE, PER_JOINPOINT};
-
- Object readResolve() throws ObjectStreamException
- {
- return values[ordinal];
- }
-
- }
- </programlisting>
- </para>
- <para>
- To create your own enum class for use within annotations, you need to inherit
- from
- <literal>org.jboss.lang.Enum</literal>. Each enum has two values, a
- String name, and an integer ordinal. The value used for the ordinal must
- be the same as it's index in the static array.
- </para>
- </sect1>
-
- <sect1 id="annotationcompiler-nestedannotations" revision="1">
- <title>Using Annotations within Annotations</title>
- <para>
- The annotation compiler allows you to use annotations within annotations. This
- is best illustrated with an example. The definitions of the annotation
- interfaces in JDK 1.4.2:
-
- <programlisting>
- com.mypackage;
-
- public interface Outer
- {
- Inner[] values();
- }
- </programlisting>
-
- <programlisting>
- com.mypackage;
-
- public interface Inner
- {
- String str();
- int integer();
- }
- </programlisting>
- </para>
- <para>
- The annotations can be applied as follows
- <programlisting>
- com.mypackage;
-
- /**
- * @@com.mypackage.Outer ({@@com.mypackage.Inner (str="x", integer=1), \
- @@com.mypackage.Inner (str="y", integer=2)})
- */
- public class Test
- {
- Inner[] values();
- }
- </programlisting>
-
- </para>
- </sect1>
-
-
- <sect1 id="annotationcompiler-compiler" revision="1">
- <title>Using the Annotation Compiler</title>
- <para>
- In order to use the JDK 1.4.2 annotations you have to precompile your
- files with an annotation compiler.
- </para>
-
- <para>
- To use the annotation compiler you can create a simple ant build.xml file
-
- <programlisting><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-
-<project default="run" name="JBoss/AOP">
- <target name="prepare">]]></programlisting>
- Include the jars AOP depends on
- <programlisting><![CDATA[
- <path id="javassist.classpath">
- <pathelement path="../../../javassist.jar"/>
- </path>
- <path id="trove.classpath">
- <pathelement path="../../../trove.jar"/>
- </path>
- <path id="concurrent.classpath">
- <pathelement path="../../../concurrent.jar"/>
- </path>
- <path refid="jboss.common.core.classpath"/>
- <path refid="jboss.common.logging.spi.classpath"/>
- <path refid="jboss.common.logging.log4j.classpath"/>
- <path refid="jboss.common.logging.jdk.classpath"/>
- <pathelement path="../../../jboss-common.jar"/>
- </path>
- <path id="jboss.aop.classpath">
- <pathelement path="../../../jboss-aop.jar"/>
- </path>
- <path id="qdox.classpath">
- <pathelement path="../../../qdox.jar"/>
- </path>
- <path id="classpath">
- <path refid="javassist.classpath"/>
- <path refid="trove.classpath"/>
- <path refid="jboss.aop.classpath"/>
- <path refid="jboss.common.core.classpath"/>
- <path refid="jboss.common.logging.spi.classpath"/>
- <path refid="jboss.common.logging.log4j.classpath"/>
- <path refid="jboss.common.logging.jdk.classpath"/>
- <path refid="concurrent.classpath"/>
- <path refid="qdox.classpath"/>
- </path>]]></programlisting>
- Define the ant task that does the annnotation compilation
- <programlisting><![CDATA[
- <taskdef
- name="annotationc"
- classname="org.jboss.aop.ant.AnnotationC"
- classpathref="jboss.aop.classpath"/>
- </target>
-
- <target name="compile" depends="prepare">]></programlisting>
- Compile the source files
- <programlisting><!CDATA[
- <javac srcdir="."
- destdir="."
- debug="on"
- deprecation="on"
- optimize="off"
- includes="**">
- <classpath refid="classpath"/>
- </javac>]]></programlisting>
- Run the annotation compiler
- <programlisting><![CDATA[
- <annotationc compilerclasspathref="classpath" classpath="." bytecode="true">
- <src path="."/>
- </annotationc>
- </target>
-</project>]]></programlisting>
- </para>
-
- <para>
- The
- <literal>org.jboss.aop.ant.AnnotationC</literal> ant task takes several parameters.
-
- <itemizedlist>
- <listitem>
- <literal>compilerclasspath</literal> or
- <literal>compilerclasspathref</literal> -
- These are interchangable, and represent the jars needed for the annotation compiler
- to work. The
- <literal>compilerclasspath</literal> version takes the paths of the
- jar files, and the
- <literal>compilerclasspathref</literal> version takes the
- name of a predefined ant path.
- </listitem>
- <listitem>
- <literal>bytecode</literal> - The default is false. If true the annotation compiler
- instruments (i.e. modifies) the class files with the annotations. In this case,
- the classes must be precompiled with javac and
- <literal>classpath</literal> or
- <literal>classpathref</literal> must be specified.
- </listitem>
- <listitem>
- <literal>classpath</literal> or
- <literal>classpathref</literal> - Path to the
- compiled classes to be instrumented with annotations, if
- <literal>bytecode</literal>="true". The
- <literal>classpath</literal>
- version takes the path of the directory, and the
- <literal>classpathref</literal>
- version takes the name of a predefined ant path.
- </listitem>
- <listitem>
- <literal>xml</literal> - Default is false. If true an xml file is generated
- containing information of how to attach the annotations at a later stage in
- the aop process.
- </listitem>
- <listitem>
- <literal>output</literal> - If
- <literal>xml</literal>="true", this lets
- you specify the name you would like for the generated xml file. The default
- name is
- <literal>metadata-aop.xml</literal>
- </listitem>
- <listitem>
- <literal>verbose</literal> - Default is false. If true, verbose output
- is generated, which comes in handy for diagnosing unexpected results.
- </listitem>
- </itemizedlist>
- You cannot currently specify both
- <literal>bytecode</literal> and
- <literal>xml</literal>.
- </para>
- <para>
- You can also run
- <literal>org.jboss.aop.ant.AnnotationC</literal> from the command line, you need
- <programlisting>
- $ java -cp <all the JBoss AOP jars and the directory containing files we want to AOP> \
- org.jboss.aop.annotation.compiler.AnnotationCompiler \
- [-xml [-o outputfile ]] [-bytecode]<files>+
- </programlisting>
- </para>
- <para>
- In the /bin folder of the distribution we have provided batch/script files to make
- this easier. It includes all the aop libs for you, so you just have to worry
- about your files. The usage is:
- <programlisting>
- $ annotationc <classpath> [-verbose] [-xml [-o outputfile]] [-bytecode] <dir_or_file>+
- </programlisting>
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <literal>classpath</literal> - path to your classes and any jars your code depends on
- </listitem>
- </itemizedlist>
- The other parameters are the same as above.
- </para>
- </sect1>
-</chapter>
-
Copied: projects/aop/trunk/aop/docs/reference/reference/en/modules/jdk14compatibility.xml (from rev 63059, projects/aop/trunk/aop/docs/reference/reference/en/modules/annotationcompiler.xml)
===================================================================
--- projects/aop/trunk/aop/docs/reference/reference/en/modules/jdk14compatibility.xml (rev 0)
+++ projects/aop/trunk/aop/docs/reference/reference/en/modules/jdk14compatibility.xml 2007-05-25 04:50:36 UTC (rev 63207)
@@ -0,0 +1,480 @@
+<chapter id="jdk14compatibility">
+ <title>JDK 1.4 Backwards Compatibility</title>
+ <para>
+ Despite the fact that it has been a while since the release of JDK1.5, there are projects
+ that still require backwards compatibility with JDK1.4. This is relatively common, and
+ the reasons for it are diverse.
+ To deal with this type of requirement, JBoss AOP provides two different solutions. By using
+ one of them, you can use all features JBoss AOP provides, including annotation-related
+ features, and still keep your code backwards compatible with JDK1.4.
+ </para>
+ <sect1 id="jdk14-jbossretro" revision="1">
+ <title>JBoss Retro</title>
+ <para>
+ The first solution to achieve JDK1.4 backwards compatibility is to use the JBoss Retro
+ tool. JBoss Retro converts JDK1.5 compiled bytecodes into bytecodes that can be
+ run using a JDK1.4 virtual machine.
+ </para>
+ <para>
+ This tool acts as a bytecode processor, and using it is very simple. You just need to
+ write your code using JDK1.5 constructs and features, and then compile it,
+ using a JDK1.5 virtual machine. Next, process the generated bytecodes using
+ JBoss Retro tool (just like you do when you use aopc compiler), and now your
+ bytecodes are ready to run using a JDK1.4 virtual machine. Notice this solution
+ allows not only the use of JBoss AOP annotations, but of all JDK1.5 features and
+ new API operations.
+ </para>
+ <para>
+ The simplest way to run JBoss Retro is using the ant task. You just need to declare it:
+ </para>
+ <programlisting><![CDATA[<taskdef name="retro" classname="org.jboss.ant.tasks.retro.Retro" classpathref="jboss.retro.classpath"/>
+ ]]></programlisting>
+ <para>
+ And use it as in the following example:
+ </para>
+ <programlisting><![CDATA[<retro compilerclasspathref="jboss.retro.classpath" destdir=".">
+ <classpath refid="jboss.retro.classpath"/>
+ <classpath path="."/>
+ <src path="."/>
+</retro>]]></programlisting>
+ <para>
+ <anchor id="jbossretroparam"/>
+ This task takes the following parameters:
+ <itemizedlist>
+ <listitem>
+ <literal>compilerclasspathref</literal> -
+ This represent the jars needed for the JBoss Retro processor to work. The
+ <literal>compilerclasspath</literal> version takes the paths of the
+ jar files, and the
+ <literal>compilerclasspathref</literal> version takes the
+ name of a predefined ant path.
+ </listitem>
+ <listitem>
+ <literal>classpath</literal> or
+ <literal>classpathref</literal> - Path to the
+ compiled classes to be processed by JBoss Retro. The
+ <literal>classpath</literal>
+ version takes the path of the directory, and the
+ <literal>classpathref</literal>
+ version takes the name of a predefined ant path.
+ </listitem>
+ <listitem>
+ <literal>verbose</literal> - Default is false. If true, verbose output
+ is generated, which comes in handy for diagnosing unexpected results.
+ </listitem>
+ <listitem>
+ <literal>suppress</literal> - Default is true. If false, error messages
+ will not be suppressed.
+ </listitem>
+ <listitem>
+ <literal>maxmemory</literal> - Sets the maximum memory of the java task that will
+ be forked.
+ </listitem>
+ <listitem>
+ <literal>destdir</literal> - the dir where JBoss Retro will write the
+ resulting bytecodes.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>It is also possible to run JBoss Retro with the following command line:</para>
+ <programlisting>
+ $ java -cp <all the JBoss AOP jars and the directory containing files we want to AOP> \
+ -verbose <true/false> -suppress <true/false> -destdir <
+ org.jboss.ant.tasks.retro.Weaver \
+ [-bytecode]<files>+
+ </programlisting>
+ <para>
+ JBoss Retro is the de facto standard solution JBoss Group provides to achieve JDK1.4 backward compatibility.
+ However, if you are impossibilitated of compiling your code using a JDK1.5 virtual machine, you should go with the next solution,
+ the annotation compiler.
+ </para>
+ </sect1>
+ <sect1 id="jdk14-anncompiler" revision="1">
+ <title>JDK1.4 Annotation Compiler</title>
+ <para>
+ Differently from JBoss Retro, the annotation compiler does not support all JDK1.5 constructs and new APIs.
+ Its functionality consists in supporting only annotations, that must be written in the form of doclets.
+ Nevertheless, this is enough to allow the use of all JBoss AOP features, and doesn't require a JDK1.5
+ compiler.
+ </para>
+ <para>
+ This way, if you can't use a JDK1.5 compiler to compile your code, you should stick with the annotation
+ compiler. It will process your application's bytecodes, transforming doclets into annotations.
+ The result of this transformation is that your doclets will become viewable by JBoss AOP as
+ if they were regular JDK1.5 annotations.
+ </para>
+ <para>
+ In the next sections, we will see what is the format your doclets need to follow in order to be
+ transformed into annotations, and how to use the annotation compiler.
+ </para>
+ </sect1>
+ <sect2 id="annotationcompiler-annotations" revision="1">
+ <title>Annotations with JDK 1.4.2</title>
+
+ <para>
+ In JDK 1.5, annotations must map to an annotation type, which is defined using the following sintax:
+
+ <programlisting>
+ package com.mypackage;
+
+ public @interface MyAnnotation
+ {
+ String myString();
+ int myInteger();
+ }
+ </programlisting>
+
+ Similarly, annotations for use with the annotation compiler also need to map to
+ a type. And this one is defined in exactly the same way as above, with the
+ important difference that '@interface' is replaced by 'interface'. i.e.
+ the simulated annotation type is a normal Java interface:
+ <programlisting>
+ package com.mypackage;
+
+ public interface MyAnnotation
+ {
+ String myString();
+ int myInteger();
+ }
+ </programlisting>
+ </para>
+
+ <para>
+ The syntax for using annotations in JDK 1.4.2 is almost exactly the same as
+ JDK 5 annotations except for these subtle differences:
+ <itemizedlist>
+ <listitem>they are embedded as doclet tags</listitem>
+ <listitem>You use a double at sign, i.e. '@@'</listitem>
+ <listitem>
+ You MUST have a space after the tag name otherwise you will get
+ a compilation error. (This is the quirkiness of the QDox doclet compiler
+ used to compile the annotations.')
+ </listitem>
+ <listitem>
+ You cannot import the annotation type, you must use the fully
+ qualified name of the interface.
+ </listitem>
+ <listitem>
+ You can only annotate top-level and inner classes, and their constructors, methods and fields.
+ Annotating anonyomus classes, local classes, and parameters for constructors or methods is not supported.
+ </listitem>
+ <listitem>You cannot specify default values for an annotation's value</listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ This example shows an annotated class in JDK 1.4.2:
+ <programlisting>
+ package com.mypackage;
+
+ /**
+ * @@com.mypackage.MyAnnotation (myString="class", myInteger=5)
+ */
+ public class MyClass
+ {
+ /**
+ * @@com.mypackage.MyAnnotation (myString="field", myInteger=4)
+ */
+ private String myField;
+
+ /**
+ * @@com.mypackage.MyAnnotation (myString="constructor", myInteger=3)
+ */
+ public MyClass()
+ {
+ }
+
+ /**
+ * @@com.mypackage.MyAnnotation (myString="method", myInteger=3)
+ */
+ public int myMethod()
+ {
+ }
+ }
+ </programlisting>
+ </para>
+
+ </sect2>
+ <sect2 id="annotationcompiler-enums" revision="1">
+ <title>Enums in JDK 1.4.2</title>
+ <para>
+ Another JDK 5 feature that JBoss AOP helps introduce to JBoss 1.4.2 are Enums.
+ As an example we can look at the
+ <literal>org.jboss.aop.advice.Scope</literal>
+ enum that is used for the
+ <literal>@Aspect</literal> annotation. Here is the
+ JDK 5 version.
+ <programlisting>
+ package org.jboss.aop.advice;
+
+ public enum Scope
+ {
+ PER_VM, PER_CLASS, PER_INSTANCE, PER_JOINPOINT
+ }
+ </programlisting>
+
+ And it's usage in JDK 5
+ <programlisting>
+ package com.mypackage;
+
+ @Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
+ public class SomeAspect
+ {
+ }
+ </programlisting>
+ The usage in JDK 1.4.2 is similar:
+ <programlisting>
+ package com.mypackage;
+
+ /**
+ * @@org.jboss.aop.Aspect (scope=org.jboss.aop.advice.Scope.PER_VM)
+ */
+ public class SomeAspect
+ {
+ //...
+ }
+ </programlisting>
+ However the declaration of the enumeration is different in 1.4.2:
+ <programlisting>
+ package org.jboss.aop.advice;
+
+ import java.io.ObjectStreamException;
+
+ public class Scope extends org.jboss.lang.Enum
+ {
+ private Scope(String name, int v)
+ {
+ super(name, v);
+ }
+
+ public static final Scope PER_VM = new Scope("PER_VM", 0);
+ public static final Scope PER_CLASS = new Scope("PER_CLASS", 1);
+ public static final Scope PER_INSTANCE = new Scope("PER_INSTANCE", 2);
+ public static final Scope PER_JOINPOINT = new Scope("PER_JOINPOINT", 3);
+
+ private static final Scope[] values = {PER_VM, PER_CLASS, PER_INSTANCE, PER_JOINPOINT};
+
+ Object readResolve() throws ObjectStreamException
+ {
+ return values[ordinal];
+ }
+
+ }
+ </programlisting>
+ </para>
+ <para>
+ To create your own enum class for use within annotations, you need to inherit
+ from
+ <literal>org.jboss.lang.Enum</literal>. Each enum has two values, a
+ String name, and an integer ordinal. The value used for the ordinal must
+ be the same as it's index in the static array.
+ </para>
+ </sect2>
+
+ <sect2 id="annotationcompiler-nestedannotations" revision="1">
+ <title>Using Annotations within Annotations</title>
+ <para>
+ The annotation compiler allows you to use annotations within annotations. This
+ is best illustrated with an example. The definitions of the annotation
+ interfaces in JDK 1.4.2:
+
+ <programlisting>
+ com.mypackage;
+
+ public interface Outer
+ {
+ Inner[] values();
+ }
+ </programlisting>
+
+ <programlisting>
+ com.mypackage;
+
+ public interface Inner
+ {
+ String str();
+ int integer();
+ }
+ </programlisting>
+ </para>
+ <para>
+ The annotations can be applied as follows
+ <programlisting>
+ com.mypackage;
+
+ /**
+ * @@com.mypackage.Outer ({@@com.mypackage.Inner (str="x", integer=1), \
+ @@com.mypackage.Inner (str="y", integer=2)})
+ */
+ public class Test
+ {
+ Inner[] values();
+ }
+ </programlisting>
+
+ </para>
+ </sect2>
+
+
+ <sect2 id="annotationcompiler-compiler" revision="1">
+ <title>Using the Annotation Compiler</title>
+ <para>
+ In order to use the JDK 1.4.2 annotations you have to precompile your
+ files with an annotation compiler.
+ </para>
+
+ <para>
+ To use the annotation compiler you can create a simple ant build.xml file
+
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project default="run" name="JBoss/AOP">
+ <target name="prepare">]]></programlisting>
+ Include the jars AOP depends on
+ <programlisting><![CDATA[
+ <path id="javassist.classpath">
+ <pathelement path="../../../javassist.jar"/>
+ </path>
+ <path id="trove.classpath">
+ <pathelement path="../../../trove.jar"/>
+ </path>
+ <path id="concurrent.classpath">
+ <pathelement path="../../../concurrent.jar"/>
+ </path>
+ <path refid="jboss.common.core.classpath"/>
+ <path refid="jboss.common.logging.spi.classpath"/>
+ <path refid="jboss.common.logging.log4j.classpath"/>
+ <path refid="jboss.common.logging.jdk.classpath"/>
+ <pathelement path="../../../jboss-common.jar"/>
+ </path>
+ <path id="jboss.aop.classpath">
+ <pathelement path="../../../jboss-aop.jar"/>
+ </path>
+ <path id="qdox.classpath">
+ <pathelement path="../../../qdox.jar"/>
+ </path>
+ <path id="classpath">
+ <path refid="javassist.classpath"/>
+ <path refid="trove.classpath"/>
+ <path refid="jboss.aop.classpath"/>
+ <path refid="jboss.common.core.classpath"/>
+ <path refid="jboss.common.logging.spi.classpath"/>
+ <path refid="jboss.common.logging.log4j.classpath"/>
+ <path refid="jboss.common.logging.jdk.classpath"/>
+ <path refid="concurrent.classpath"/>
+ <path refid="qdox.classpath"/>
+ </path>]]></programlisting>
+ Define the ant task that does the annnotation compilation
+ <programlisting><![CDATA[
+ <taskdef
+ name="annotationc"
+ classname="org.jboss.aop.ant.AnnotationC"
+ classpathref="jboss.aop.classpath"/>
+ </target>
+
+ <target name="compile" depends="prepare">]></programlisting>
+ Compile the source files
+ <programlisting><!CDATA[
+ <javac srcdir="."
+ destdir="."
+ debug="on"
+ deprecation="on"
+ optimize="off"
+ includes="**">
+ <classpath refid="classpath"/>
+ </javac>]]></programlisting>
+ Run the annotation compiler
+ <programlisting><![CDATA[
+ <annotationc compilerclasspathref="classpath" classpath="." bytecode="true">
+ <src path="."/>
+ </annotationc>
+ </target>
+</project>]]></programlisting>
+ </para>
+
+ <para>
+ The
+ <literal>org.jboss.aop.ant.AnnotationC</literal> ant task takes several parameters.
+
+ <itemizedlist>
+ <listitem>
+ <literal>compilerclasspath</literal>,
+ <literal>compilerclasspathref</literal>,
+ <literal>classpath</literal>,
+ <literal>classpathref</literal> and
+ <literal>verbose</literal> -
+ These have the same meaning as in the JBoss Retro <link linkend="jbossretroparam">task</link>.
+ <!--These are interchangable, and represent the jars needed for the annotation compiler
+ to work. The
+ <literal>compilerclasspath</literal> version takes the paths of the
+ jar files, and the
+ <literal>compilerclasspathref</literal> version takes the
+ name of a predefined ant path.-->
+ </listitem>
+ <listitem>
+ <literal>bytecode</literal> - The default is false. If true the annotation compiler
+ instruments (i.e. modifies) the class files with the annotations. In this case,
+ the classes must be precompiled with javac and
+ <literal>classpath</literal> or
+ <literal>classpathref</literal> must be specified.
+ </listitem>
+ <!--<listitem>
+ <literal>classpath</literal> or
+ <literal>classpathref</literal> - Path to the
+ compiled classes to be instrumented with annotations, if
+ <literal>bytecode</literal>="true". The
+ <literal>classpath</literal>
+ version takes the path of the directory, and the
+ <literal>classpathref</literal>
+ version takes the name of a predefined ant path.
+ </listitem> -->
+ <listitem>
+ <literal>xml</literal> - Default is false. If true an xml file is generated
+ containing information of how to attach the annotations at a later stage in
+ the aop process.
+ </listitem>
+ <listitem>
+ <literal>output</literal> - If
+ <literal>xml</literal>="true", this lets
+ you specify the name you would like for the generated xml file. The default
+ name is
+ <literal>metadata-aop.xml</literal>
+ </listitem>
+<!-- <listitem>
+ <literal>verbose</literal> - Default is false. If true, verbose output
+ is generated, which comes in handy for diagnosing unexpected results.
+ </listitem>-->
+ </itemizedlist>
+ You cannot currently specify both
+ <literal>bytecode</literal> and
+ <literal>xml</literal>.
+ </para>
+ <para>
+ You can also run
+ <literal>org.jboss.aop.ant.AnnotationC</literal> from the command line, you need
+ <programlisting>
+ $ java -cp <all the JBoss AOP jars and the directory containing files we want to AOP> \
+ org.jboss.aop.annotation.compiler.AnnotationCompiler \
+ [-xml [-o outputfile ]] [-bytecode]<files>+
+ </programlisting>
+ </para>
+ <para>
+ In the /bin folder of the distribution we have provided batch/script files to make
+ this easier. It includes all the aop libs for you, so you just have to worry
+ about your files. The usage is:
+ <programlisting>
+ $ annotationc <classpath> [-verbose] [-xml [-o outputfile]] [-bytecode] <dir_or_file>+
+ </programlisting>
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <literal>classpath</literal> - path to your classes and any jars your code depends on
+ </listitem>
+ </itemizedlist>
+ The other parameters are the same as above.
+ </para>
+ </sect2>
+</chapter>
+
More information about the jboss-cvs-commits
mailing list