[jboss-cvs] JBossAS SVN: r76432 - projects/aop/trunk/aop/docs/examples/metadata.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Jul 29 15:00:12 EDT 2008
Author: flavia.rainone at jboss.com
Date: 2008-07-29 15:00:12 -0400 (Tue, 29 Jul 2008)
New Revision: 76432
Added:
projects/aop/trunk/aop/docs/examples/metadata/metadata-aop.xml
Modified:
projects/aop/trunk/aop/docs/examples/metadata/POJO.java
projects/aop/trunk/aop/docs/examples/metadata/metadata.html
Log:
[JBAOP-591] A metadata-aop.xml file has been added to contain the metadata tags. The metadata.html has been updated,
now it exaplains the structure of metadata tags and doesn't mention annotationc. All doclets have been
removed from POJO.
Modified: projects/aop/trunk/aop/docs/examples/metadata/POJO.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/metadata/POJO.java 2008-07-29 18:46:20 UTC (rev 76431)
+++ projects/aop/trunk/aop/docs/examples/metadata/POJO.java 2008-07-29 19:00:12 UTC (rev 76432)
@@ -21,38 +21,20 @@
*/
public class POJO
{
- /**
- * @@trace
- * @@billable (amount=0.01)
- */
public POJO()
{
System.out.println("empty constructor");
}
- /**
- * @@trace
- * @@billable (amount=0.01)
- */
public POJO(int i)
{
System.out.println("int constructor");
}
- /**
- * @@billable (amount=0.05)
- * @@trace
- */
public void someMethod()
{
System.out.println("someMethod");
}
- /**
- * @@trace
- */
public int field;
-}
-
-
-
+}
\ No newline at end of file
Added: projects/aop/trunk/aop/docs/examples/metadata/metadata-aop.xml
===================================================================
--- projects/aop/trunk/aop/docs/examples/metadata/metadata-aop.xml (rev 0)
+++ projects/aop/trunk/aop/docs/examples/metadata/metadata-aop.xml 2008-07-29 19:00:12 UTC (rev 76432)
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<aop>
+ <metadata tag="trace" class="POJO">
+ <constructor expr="POJO()"/>
+ </metadata>
+ <metadata tag="billable" class="POJO">
+ <constructor expr="POJO()">
+ <amount>0.01</amount>
+ </constructor>
+ </metadata>
+ <metadata tag="trace" class="POJO">
+ <field name="field"/>
+ <constructor expr="POJO(int)"/>
+ <method expr="void someMethod()"/>
+ </metadata>
+ <metadata tag="billable" class="POJO">
+ <constructor expr="POJO(int)">
+ <amount>0.01</amount>
+ </constructor>
+ <method expr="void someMethod()">
+ <amount>0.05</amount>
+ </method>
+ </metadata>
+</aop>
\ No newline at end of file
Modified: projects/aop/trunk/aop/docs/examples/metadata/metadata.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/metadata/metadata.html 2008-07-29 18:46:20 UTC (rev 76431)
+++ projects/aop/trunk/aop/docs/examples/metadata/metadata.html 2008-07-29 19:00:12 UTC (rev 76432)
@@ -6,40 +6,75 @@
</p><p>
<h4>Overview</h4>
-JBoss Metadata is alot like JDK 5's annotations(<a href="http://www.jcp.org/en/jsr/detail?id=175">JSR-175</a>) except it is
-driven and applied through XML. JBossAOP has the ability to define metadata in XML or as Doclet tags that are then parsed to
-generate XML when you are not using JDK 5 or higher. You can use the same pointcut annotation expressions to reference JBossAOP
-XML metadata expressions. This metadata is different than regular JDK annotations in that they are untyped. If you've read
-the <a href="../annotation14/annotation.html">Annotations with JDK 1.4</a>. You can handcode this XML or have the Annotation
-compiler generate them from doclet tags using the -xml option. Having run this example, you can find the metadata in
-<i>metadata-aop.xml</i>.
+JBoss Metadata is alot like annotations except it is driven and applied through XML.
+JBossAOP has the ability to define metadata in XML. You can use the same pointcut annotation expressions to reference JBossAOP
+XML metadata expressions. This metadata is different than regular JDK annotations in that they are untyped.
</p><p>
<h4>Example code</h4>
The example code applies 2 separate interceptors via tags supplied in a Java source file. One of the interceptors is a tracing interceptor that is trigger by a @trace annotation, the other is B2B functionality that will bill/charge a user for each access of the api. This is also triggered by an annotation.
</p><p>
-<h4>Declaring annotations</h4>
+<h4>Declaring Metadata</h4>
-Open up POJO.java. This is the source file for where our annotations will be declared.
-<b>IMPORTANT NOTE!</b> You MUST have a space after the annotation tag name otherwise you will get a compiler error.
+Open up <code>metadata-aop.xml</code>. This is the source file for where our annotations will be declared.
+This file is composed of a list of <code>metadata</code> tags. Each such tag must have two attributes:
+<code>tag</code> and <code>class</code>. The <code>tag</code> attribute is the name of the metadata, equivalent to the name of an annotation. The
+<code>class</code> attribute must contain a class expression. Every class matching that expression will be bound to the metadata.
+Take a look at the two first tags of <code>metadata-aop.xml</code>:
<pre>
- /**
- * @@billable (amount=0.05)
- * @@trace
- */
- public void someMethod()
- {
- System.out.println("someMethod");
- }
+ <metadata tag="trace" class="POJO">
+ <constructor expr="POJO()"/>
+ </metadata>
+ <metadata tag="billable" class="POJO">
+ <constructor expr="POJO()">
+ <amount>0.01</amount>
+ </constructor>
+ </metadata>
</pre>
</p><p>
-JBossAOP tags are defined by a double at symbol '@@' and zero or more name/value pairs. In the above example, we are declaring someMethod() to be traced and billable to an ammount of $0.05 every time it is accessed. This Java source file is run through JBossAOP's annotation compiler to generate XML. You can run this annotation compiler as an ANT taskdef or standalone. Look at build.xml to see how the taskdef is set up for <tt>annotationc</tt>.
+The first one represents a metadata <code>@trace</code> and the second
+one represents the metadata <code>@billable</code>. Both metadata will be applied to class <code>POJO</code>,
+as specified in the <code>class</code> attribute.
+The contents of a <code>metadata</code> tag indicate to which elements of
+<code>POJO</code> class this metadata should be applied. In the example, the metadata <code>@trace</code> will be applied to the
+default constructor of POJO(). The metada <code>@billable</code> will be also applied to the same constructor, and has an attribute,
+<code>amount</code>, whose value is <code>0.01</code>. Following this same format you can define as many attributes and values you
+need.
+In similar ways, a metadata can be applied to the fields, methods and to the class itself, just like Java annotations. The next
+<code>metadata</code> tags apply metadata to constructors, methods and fields:
+<pre>
+ <metadata tag="trace" class="POJO">
+ <field name="field"/>
+ <constructor expr="POJO(int)"/>
+ <method expr="void someMethod()"/>
+ </metadata>
+ <metadata tag="billable" class="POJO">
+ <constructor expr="POJO(int)">
+ <amount>0.01</amount>
+ </constructor>
+ <method expr="void someMethod()">
+ <amount>0.05</amountgt;
+ </method>
+ </metadata>
+</pre>
+
+If we wanted to apply <code>@trace</code> to <code>POJO</code> class, we could have added an empty <code>class</code>
+XML tag to a <code>metadata</code> element:
+<pre>
+ <metadata tag="trace" class="POJO">
+ <class/>
+ </metadata>
+</pre>
+The example bellow states that every constructor, field, and method of <code>POJO</code> class will be bound to the
+<code>@trace</code> metadata:
+<pre>
+ <metadata tag="trace" class="POJO">
+ <default/>
+ </metadata>
+</pre>
+
</p><p>
-The <tt>annotationc</tt> task is very similar to the <tt>javac</tt> taskdef. You declare <tt><src></tt> tags just as you would with <tt>javac</tt>. Any .java files in your sourcepath will be compiled and an XML file will be generated.
-</p><p>
-When you run the build, metadata-aop.xml is generated. Take a look at that to see how the doclet tags are mapped to XML. It is pretty straightforward.
-</p><p>
<h4>Annotations in pointcut expressions</h4>
Annotations can be referenced by an '@' sign in pointcut expressions. They can only be used in the class expressions for a method, field, or constructor for execution and caller pointcuts. They can also be used in substitute for 'new' in constructor land, and for a method or field name. Take a look at jboss-aop.xml
@@ -55,7 +90,7 @@
</pre>
</p><p>
-The first binding above says that for every constructor tagged as @billable apply the BillingInterceptor. The second binding states that for any method tagged as @billable apply the BillingInterceptor. Let's now take a look at applying the tracing advice.
+The first binding above says that for every constructor tagged as <code>@billable</code> apply the <code>BillingInterceptor</code>. The second binding states that for any method tagged as <code>@billable</code> apply the <code>BillingInterceptor</code>. Let's now take a look at applying the tracing advice.
</p><p>
<pre>
<bind pointcut="all(@trace)">
@@ -63,11 +98,11 @@
</bind>
</pre>
</p><p>
-The above states that for any field, constructor, or method tagged as @trace, apply the TraceInterceptor.
+The above states that for any field, constructor, or method tagged as <code>@trace</code>, apply the <code>TraceInterceptor</code>.
</p><p>
<h4>Accessing metadata at runtime</h4>
-You can access metadata through the <tt>org.jboss.aop.Advised</tt> interface through the _getAdvisor() or _getInstanceAdvisor() methods, or you can use the indirection that the Invocation object provides you. You can use the Invocation object to resolve metadata based on the context of the execution. <tt>BillingInterceptor.java</tt> gives an example of this. This interceptor intercepts different kinds of things (methods and constructors), but it doesn't care about the thing it is intercepting, only the metadata.
+You can access metadata through the <tt>org.jboss.aop.Advised</tt> interface through the <code>_getAdvisor()</code> or <code>_getInstanceAdvisor()</code> methods, or you can use the indirection that the <code>Invocation</code> object provides you. You can use the <code>Invocation</code> object to resolve metadata based on the context of the execution. <tt>BillingInterceptor.java</tt> gives an example of this. This interceptor intercepts different kinds of things (methods and constructors), but it doesn't care about the thing it is intercepting, only the metadata.
</p><p>
<pre>
public Object invoke(Invocation invocation) throws Throwable
More information about the jboss-cvs-commits
mailing list