[jboss-cvs] JBossAS SVN: r97920 - projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Dec 16 20:13:49 EST 2009
Author: laubai
Date: 2009-12-16 20:13:49 -0500 (Wed, 16 Dec 2009)
New Revision: 97920
Modified:
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
Log:
Corrected tags in AOP.xml for EAP5.
Modified: projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
===================================================================
--- projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2009-12-17 01:13:21 UTC (rev 97919)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2009-12-17 01:13:49 UTC (rev 97920)
@@ -7,47 +7,47 @@
<para>
<indexterm><primary>JBoss AOP</primary><secondary>aspect oriented framework</secondary></indexterm>
<indexterm><primary>AOP</primary><see>JBoss AOP</see></indexterm>
- JBoss AOP is a 100% Pure Java Aspected Oriented Framework usable in any programming environment or tightly integrated with our application server. Aspects allow you to more easily modularize your code base when regular object oriented programming just doesn't fit the bill. It can provide a cleaner separation from application logic and system code. It provides a great way to expose integration points into your software. Combined with JDK 1.5 Annotations, it also is a great way to expand the Java language in a clean pluggable way rather than using annotations solely for code generation. </para>
+ JBoss AOP is a 100% Pure Java Aspected Oriented Framework usable in any programming environment or tightly integrated with our application server. Aspects allow you to more easily modularize your code base when regular object oriented programming just doesn't fit the bill. It can provide a cleaner separation from application logic and system code. It provides a great way to expose integration points into your software. Combined with JDK 1.5 Annotations, it also is a great way to expand the Java language in a clean pluggable way rather than using annotations solely for code generation. </para>
<para>JBoss AOP is not only a framework, but also a prepackaged set of aspects that are applied via annotations, pointcut expressions, or dynamically at runtime. Some of these include caching, asynchronous communication, transactions, security, remoting, and many many more. </para>
-<para>An aspect is a common feature that's typically scattered across methods, classes, object hierarchies, or even entire object models. It is behavior that looks and smells like it should have structure, but you can't find a way to express this structure in code with traditional object-oriented techniques. </para>
+<para>An aspect is a common feature that is typically scattered across methods, classes, object hierarchies, or even entire object models. It is behavior that looks and smells like it should have structure, but you can't find a way to express this structure in code with traditional object-oriented techniques. </para>
<para>For example, metrics is one common aspect. To generate useful logs from your application, you have to (often liberally) sprinkle informative messages throughout your code. However, metrics is something that your class or object model really shouldn't be concerned about. After all, metrics is irrelevant to your actual application: it doesn't represent a customer or an account, and it doesn't realize a business rule. It's simply orthogonal. </para>
<section>
<title>Some key terms</title>
<formalpara><title>Joinpoint</title>
-<para>A joinpoint is any point in your java program. The call of a method. The execution of a constructor the access of a field. All these are joinpoints. You could also think of a joinpoint as a particular Java event. Where an event is a method call, constructor call, field access etc... </para>
+<para>A <emphasis>joinpoint</emphasis> is any point in your Java program. The call of a method, the execution of a constructor, the access of a field; all these are joinpoints. You could also think of a joinpoint as a particular Java event, where an event is a method call, constructor call, field access, etc.</para>
</formalpara>
<formalpara><title>Invocation</title>
-<para>An Invocation is a JBoss AOP class that encapsulates what a joinpiont is at runtime. It could contain information like which method is being called, the arguments of the method, etc... </para>
+<para>An <emphasis>invocation</emphasis> is a JBoss AOP class that encapsulates what a joinpiont is at runtime. It could contain information like which method is being called, the arguments of the method, etc. </para>
</formalpara>
<formalpara><title>Advice</title>
-<para>An advice is a method that is called when a particular joinpoint is executed, i.e., the behavior that is triggered when a method is called. It could also be thought of as the code that does the interception. Another analogy is that an advice is an "event handler". </para>
+<para>An <emphasis>advice</emphasis> is a method that is called when a particular joinpoint is executed, such as the behavior that is triggered when a method is called. It could also be thought of as the code that performs the interception. Another analogy is that an advice is an "event handler". </para>
</formalpara>
<formalpara><title>Pointcut</title>
-<para>Pointcuts are AOP's expression language. Just as a regular expression matches strings, a pointcut expression matches a particular joinpoint. </para>
+<para><emphasis>Pointcuts</emphasis> are AOP's expression language. Just as a regular expression matches strings, a pointcut expression matches a particular joinpoint. </para>
</formalpara>
-<formalpara><title>Introductions</title>
-<para>An introduction modifies the type and structure of a Java class. It can be used to force an existing class to implement an interface or to add an annotation to anything. </para>
+<formalpara><title>Introduction</title>
+<para>An <emphasis>introduction</emphasis> modifies the type and structure of a Java class. It can be used to force an existing class to implement an interface or to add an annotation to anything. </para>
</formalpara>
<formalpara><title>Aspect</title>
-<para>An Aspect is a plain Java class that encapsulates any number of advices, pointcut definitions, mixins, or any other JBoss AOP construct. </para>
+<para>An <emphasis>aspect</emphasis> is a plain Java class that encapsulates any number of advices, pointcut definitions, mixins, or any other JBoss AOP construct. </para>
</formalpara>
<formalpara><title>Interceptor</title>
-<para>An interceptor is an Aspect with only one advice named "invoke". It is a specific interface that you can implement if you want your code to be checked by forcing your class to implement an interface. It also will be portable and can be reused in other JBoss environments like EJBs and JMX MBeans. </para>
+<para>An <emphasis>interceptor</emphasis> is an aspect with only one advice, named <literal>invoke</literal>. It is a specific interface that you can implement if you want your code to be checked by forcing your class to implement an interface. It also will be portable and can be reused in other JBoss environments like EJBs and JMX MBeans. </para>
</formalpara>
<!--merged sections</section>-->
-<para>In AOP, a feature like metrics is called a <emphasis>crosscutting concern</emphasis>, as it's a behavior that "cuts" across multiple points in your object models, yet is distinctly different. As a development methodology, AOP recommends that you abstract and encapsulate crosscutting concerns.</para>
+<para>In AOP, a feature like metrics is called a <emphasis>crosscutting concern</emphasis>, as it is a behavior that "cuts" across multiple points in your object models, yet is distinctly different. As a development methodology, AOP recommends that you abstract and encapsulate crosscutting concerns.</para>
<para>For example, let's say you wanted to add code to an application to measure the amount of time it would take to invoke a particular method. In plain Java, the code would look something like the following. </para>
<programlisting role="JAVA">public class BankAccountDAO
@@ -71,10 +71,10 @@
<orderedlist>
<listitem>
-<para>It's extremely difficult to turn metrics on and off, as you have to manually add the code in the <emphasis>try>/finally</emphasis> block to each and every method or constructor you want to benchmark. </para>
+<para>It's extremely difficult to turn metrics on and off, as you have to manually add the code in the <code>try</code> and <code>finally</code> blocks to each and every method or constructor you want to benchmark. </para>
</listitem>
<listitem>
-<para>The profiling code really doesn't belong sprinkled throughout your application code. It makes your code bloated and harder to read, as you have to enclose the timings within a try/finally block. </para>
+<para>Profiling code should not be combined with your application code. It makes your code more verbose and difficult to read, since the timings must be enclosed within the <code>try</code> and <code>finally</code> blocks. </para>
</listitem>
<listitem>
<para>If you wanted to expand this functionality to include a method or failure count, or even to register these statistics to a more sophisticated reporting mechanism, you'd have to modify a lot of different files (again).</para>
@@ -83,27 +83,27 @@
</para>
<para>
- This approach to metrics is very difficult to maintain, expand, and extend, because it's dispersed throughout your entire code base. And this is just a tiny example! In many cases, OOP may not always be the best way to add metrics to a class.
+ This approach to metrics is very difficult to maintain, expand, and extend, because it's dispersed throughout your entire code base. In many cases, OOP may not always be the best way to add metrics to a class.
</para>
<para>
- Aspect-oriented programming gives you a way to encapsulate this type of behavior functionality. It allows you to add behavior such as metrics "around" your code. For example, AOP provides you with programmatic control to specify that you want calls to BankAccountDAO to go through a metrics aspect before executing the actual body of that code.
+ Aspect-oriented programming gives you a way to encapsulate this type of behavior functionality. It allows you to add behavior such as metrics "around" your code. For example, AOP provides you with programmatic control to specify that you want calls to <classname>BankAccountDAO</classname> to go through a metrics aspect before executing the actual body of that code.
</para>
</section>
<section>
- <title>Creating Aspects in JBoss AOP</title>
- <para>
+ <title>Creating Aspects in JBoss AOP</title>
+ <para>
<indexterm><primary>JBoss AOP</primary><secondary>creating aspects</secondary></indexterm>
- In short, all AOP frameworks define two things: a way to implement crosscutting concerns, and a programmatic construct -- a programming language or a set of tags -- to specify how you want to apply those snippets of code.
- Let's take a look at how JBoss AOP, its cross-cutting concerns, and how you can implement a metrics aspect in JBoss.
- </para>
- <para>
- The first step in creating a metrics aspect in JBoss AOP is to encapsulate the metrics feature in its own Java class. Listing Two extracts the try/finally block in Listing One's BankAccountDAO.withdraw() method into Metrics, an implementation of a JBoss AOP Interceptor class.
- </para>
- <para>
- The following listing demonstrates Implementing metrics in a JBoss AOP Interceptor
- </para>
+ In short, all AOP frameworks define two things: a way to implement crosscutting concerns, and a programmatic construct — a programming language or a set of tags — to specify how you want to apply those snippets of code.
+ Let's take a look at how JBoss AOP, its cross-cutting concerns, and how you can implement a metrics aspect in JBoss Enterprise Web Platform.
+ </para>
+ <para>
+ The first step in creating a metrics aspect in JBoss AOP is to encapsulate the metrics feature in its own Java class. Listing <literal>Two</literal> extracts the <code>try</code>/<code>finally</code> block in <classname>Listing</classname> <literal>One</literal>'s <methodname>BankAccountDAO.withdraw()</methodname> method into Metrics, an implementation of a JBoss AOP Interceptor class.
+ </para>
+ <para>
+ The following listing demonstrates Implementing metrics in a JBoss AOP Interceptor
+ </para>
<programlisting role="JAVA">01. public class Metrics implements org.jboss.aop.advice.Interceptor
02. {
03. public Object invoke(Invocation invocation) throws Throwable
@@ -120,231 +120,207 @@
14. System.out.println("method " + m.toString() + " time: " + endTime + "ms");
15. }
16. }
-17. }</programlisting>
+17. }</programlisting>
- <para>
- Under JBoss AOP, the Metrics class wraps withdraw(): when calling code invokes withdraw(), the AOP framework breaks the method call into its parts and encapsulates those parts into an Invocation object. The framework then calls any aspects that sit between the calling code and the actual method body.
- </para>
- <para>
- When the AOP framework is done dissecting the method call, it calls Metric's invoke method at line 3. Line 8 wraps and delegates to the actual method and uses an enclosing try/finally block to perform the timings. Line 13 obtains contextual information about the method call from the Invocation object, while line 14 displays the method name and the calculated metrics.
- </para>
- <para>
- Having the metrics code within its own object allows us to easily expand and capture additional measurements later on. Now that metrics are encapsulated into an aspect, let's see how to apply it.
- </para>
-
+ <para>
+ Under JBoss AOP, the Metrics class wraps <methodname>withdraw()</methodname>: when calling code invokes <methodname>withdraw()</methodname>, the AOP framework breaks the method call into its parts and encapsulates those parts into an Invocation object. The framework then calls any aspects that sit between the calling code and the actual method body.
+ </para>
+ <para>
+ When the AOP framework is done dissecting the method call, it calls <classname>Metrics</classname>'s invoke method at line 3. Line 8 wraps and delegates to the actual method and uses an enclosing try/finally block to perform the timings. Line 13 obtains contextual information about the method call from the Invocation object, while line 14 displays the method name and the calculated metrics.
+ </para>
+ <para>
+ Having the <classname>Metrics</classname> code within its own object allows us to easily expand and capture additional measurements later on. Now that metrics are encapsulated into an aspect, let's see how to apply it.
+ </para>
+
</section>
-
+
<section>
- <title>Applying Aspects in JBoss AOP</title>
- <para>
+ <title>Applying Aspects in JBoss AOP</title>
+ <para>
<indexterm><primary>JBoss AOP</primary><secondary>applying aspects</secondary></indexterm>
- To apply an aspect, you define when to execute the aspect code. Those points in execution are called pointcuts. An analogy to a pointcut is a regular expression. Where a regular expression matches strings, a pointcut expression matches events/points within your application. For example, a valid pointcut definition would be "for all calls to the JDBC method executeQuery(), call the aspect that verifies SQL syntax."
- </para>
- <para>
- An entry point could be a field access, or a method or constructor call. An event could be an exception being thrown. Some AOP implementations use languages akin to queries to specify pointcuts. Others use tags. JBoss AOP uses both. Listing Three shows how to define a pointcut for the metrics example.
- </para>
- <para>
- The following listing demonstrates defining a pointcut in JBoss AOP
- </para>
+ To apply an aspect, you define when to execute the aspect code. Those points in execution are called pointcuts. An analogy to a pointcut is a regular expression. Where a regular expression matches strings, a pointcut expression matches events/points within your application. For example, a valid pointcut definition would be "for all calls to the JDBC method executeQuery(), call the aspect that verifies SQL syntax."
+ </para>
+ <para>
+ An entry point could be a field access, or a method or constructor call. An event could be an exception being thrown. Some AOP implementations use languages akin to queries to specify pointcuts. Others use tags. JBoss AOP uses both. Listing <literal>Three</literal> shows how to define a pointcut for the metrics example.
+ </para>
+ <para>
+ The following listing demonstrates defining a pointcut in JBoss AOP
+ </para>
<programlisting role="XML">1. <bind pointcut="public void com.mc.BankAccountDAO->withdraw(double amount)">
2. <interceptor class="com.mc.Metrics"/>
3. </bind >
-
+
4. <bind pointcut="* com.mc.billing.*->*(..)">
5. <interceptor class="com.mc.Metrics"/>
6. </bind >
</programlisting>
<para>
- Lines 1-3 define a pointcut that applies the metrics aspect to the specific method BankAccountDAO.withdraw(). Lines 4-6 define a general pointcut that applies the metrics aspect to all methods in all classes in the com.mc.billing package.
- There is also an optional annotation mapping if you do not like XML. See our Reference Guide for more information.
+ Lines 1-3 define a pointcut that applies the metrics aspect to the specific method <methodname>BankAccountDAO.withdraw()</methodname>. Lines 4-6 define a general pointcut that applies the metrics aspect to all methods in all classes in the com.mc.billing package.
+ There is also an optional annotation mapping if you do not like XML. See our Reference Guide for more information.
</para>
<para>
- JBoss AOP has a rich set of pointcut expressions that you can use to define various points/events in your Java application so that you can apply your aspects. You can attach your aspects to a specific Java class in your application or you can use more complex compositional pointcuts to specify a wide range of classes within one expression.
+ JBoss AOP has a rich set of pointcut expressions that you can use to define various points/events in your Java application so that you can apply your aspects. You can attach your aspects to a specific Java class in your application or you can use more complex compositional pointcuts to specify a wide range of classes within one expression.
</para>
<para>
- With AOP, as this example shows, you're able to pull together crosscutting behavior into one object and apply it easily and simply, without polluting and bloating your code with features that ultimately don't belong mingled with business logic. Instead, common crosscutting concerns can be maintained and extended in one place.
+ With AOP, as this example shows, you're able to pull together crosscutting behavior into one object and apply it easily and simply, without polluting and bloating your code with features that ultimately don't belong mingled with business logic. Instead, common crosscutting concerns can be maintained and extended in one place.
</para>
<para>
- Notice too that the code within the BankAccountDAO class has no idea that it's being profiled. This is what aspect-oriented programmers deem orthogonal concerns. Profiling is an orthogonal concern. In the OOP code snippet in Listing One, profiling was part of the application code. With AOP, you can remove that code. A modern promise of middleware is transparency, and AOP (pardon the pun) clearly delivers.
+ Notice too that the code within the <classname>BankAccountDAO</classname> class has no idea that it's being profiled. This is what aspect-oriented programmers deem orthogonal concerns. Profiling is an orthogonal concern. In the OOP code snippet in Listing One, profiling was part of the application code. With AOP, you can remove that code. A modern promise of middleware is transparency, and AOP clearly delivers.
</para>
<para>
- Just as important, orthogonal behavior could be bolted on after development. In Listing One, monitoring and profiling must be added at development time. With AOP, a developer or an administrator can (easily) add monitoring and metrics as needed without touching the code. This is a very subtle but significant part of AOP, as this separation (obliviousness, some may say) allows aspects to be layered on top of or below the code that they cut across. A layered design allows features to be added or removed at will. For instance, perhaps you snap on metrics only when you're doing some benchmarks, but remove it for production. With AOP, this can be done without editing, recompiling, or repackaging the code.
+ Just as important, orthogonal behavior could be bolted on after development. In Listing One, monitoring and profiling must be added at development time. With AOP, a developer or an administrator can (easily) add monitoring and metrics as needed without touching the code. This is a very subtle but significant part of AOP, as this separation allows aspects to be layered on top of or below the code that they cut across. A layered design allows features to be added or removed at will. For instance, perhaps you snap on metrics only when you're doing some benchmarks, but remove it for production. With AOP, this can be done without editing, recompiling, or repackaging the code.
</para>
</section>
<section>
- <title>Packaging AOP Applications</title>
- <para>
- To deploy an AOP application in JBoss you need to package it. AOP is packaged similarly
- to SARs(MBeans). You can either deploy an XML file directly in the deploy/ directory
- with the signature <filename>*-aop.xml</filename> along with your package (this is how the base-aop.xml,
- included in the
- <literal>jboss-aop.deployer</literal> file works) or you can include it in
- the jar file containing your classes. If you include your xml file in your jar,
- it must have the file extension .aop and a jboss-aop.xml file must be contained
- in a META-INF directory, for instanace:
- <literal>META-INF/jboss-aop.xml</literal>.
- </para>
- <para>
- In the JBoss Enterprise Application Platform 5, you <emphasis>must</emphasis> specify the schema used, otherwise your information will not be
- parsed correctly. You do this by adding the <literal>xmlns="urn:jboss:aop-beans:1:0</literal>
- attribute to the root <literal>aop</literal> element, as shown here:
+ <title>Packaging AOP Applications</title>
+ <para>
+ To deploy an AOP application in JBoss you need to package it. AOP is packaged similarly to SARs (MBeans). You can either deploy an XML file directly in the <filename>deploy/</filename> directory with the signature <filename>*-aop.xml</filename> along with your package (this is how the <filename>base-aop.xml</filename>, included in the <filename>jboss-aop.deployer</filename> file works) or you can include it in the jar file containing your classes. If you include your XML file in your JAR, it must have the file extension <filename>.aop</filename> and a <filename>jboss-aop.xml</filename> file must be contained in a <filename>META-INF</filename> directory, for instance: <filename>META-INF/jboss-aop.xml</filename>.
+ </para>
+ <para>
+ In the JBoss Enterprise Application Platform 5, you <emphasis>must</emphasis> specify the schema used, otherwise your information will not be parsed correctly. You do this by adding the <varname>xmlns="urn:jboss:aop-beans:1:0</varname> attribute to the root <literal>aop</literal> element, as shown here:
+ </para>
<programlisting>
<aop xmlns="urn:jboss:aop-beans:1.0">
-
</aop>
</programlisting>
- </para>
- <para>
- If you want to create anything more than a non-trivial example, using the .aop jar
- files, you can make any top-level deployment contain a .aop file containing the xml
- binding configuration. For instance you can have a .aop file in an .ear file, or a .aop
- file in a war file. The bindings specified in the
- <literal>META-INF/jboss-aop.xml</literal>
- file contained in the .aop file will affect all the classes in the whole war file
- </para>
- <para>
- To pick up a .aop file in an .ear file, it must be listed in the
- <literal>.ear/META-INF/application.xml</literal> as a java module; for example:
- </para>
+ <para>
+ If you want to create anything more than a non-trivial example, using the <filename>.aop</filename> JAR files, you can make any top-level deployment contain an AOP file containing the XML binding configuration. For instance you can have an AOP file in an EAR file, or an AOP file in a WAR file. The bindings specified in the <filename>META-INF/jboss-aop.xml</filename> file contained in the AOP file will affect all the classes in the whole WAR file.
+ </para>
+ <para>
+ To pick up an AOP file in an EAR file, it must be listed in the <filename>.ear/META-INF/application.xml</filename> as a Java module, as follows:
+ </para>
<programlisting><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN''http://java.sun.com/j2ee/dtds/application_1_2.dtd'>
<application>
- <display-name>AOP in JBoss example</display-name>
- <module>
- <java>example.aop</java>
- </module>
- <module>
- <ejb>aopexampleejb.jar</ejb>
- </module>
- <module>
- <web>
- <web-uri>aopexample.war</web-uri>
- <context-root>/aopexample</context-root>
- </web>
- </module>
+ <display-name>AOP in JBoss example</display-name>
+ <module>
+ <java>example.aop</java>
+ </module>
+ <module>
+ <ejb>aopexampleejb.jar</ejb>
+ </module>
+ <module>
+ <web>
+ <web-uri>aopexample.war</web-uri>
+ <context-root>/aopexample</context-root>
+ </web>
+ </module>
</application>
]]></programlisting>
- <important>
- <para>
- In the JBoss Enterprise Application Platform 5, the contents of the <filename>.ear</filename> file are deployed in the order they
- are listed in the <filename>application.xml</filename>. When using loadtime weaving the bindings listed in the <filename>example.aop</filename> file must be
- deployed before the classes being advised are deployed, so that the bindings exist in the system before (for example) the
- ejb and servlet classes are loaded. This is acheived by listing the <filename>.aop</filename> file at the start of the <filename>application.xml</filename>.
- Other types of archives are deployed before anything else and so do not require special consideration, such as <filename>.sar</filename> and <filename>.war</filename> files.
- </para>
- </important>
- </section>
- <section>
- <title>The JBoss AspectManager Service</title>
- <para>
- The AspectManager Service can be managed at runtime
- using the JMX console which is found at <literal>http://localhost:8080/jmx-console</literal>. It is
- registered under the ObjectName <literal>jboss.aop:service=AspectManager</literal>. If you want to configure
- it on startup you need to edit some configuration files.
- </para>
- <para>
- In JBoss Enterprise Application Platform 5 the AspectManager Service is configured using a JBoss Microcontainer bean. The configuration file is <literal>jboss-as/server/xxx/conf/bootstrap/aop.xml</literal>. The AspectManager Service is deployed with the following xml:
- </para>
+ <important>
+ <para>
+ In the JBoss Enterprise Application Platform 5, the contents of the <filename>.ear</filename> file are deployed in the order they are listed in the <filename>application.xml</filename>. When using loadtime weaving the bindings listed in the <filename>example.aop</filename> file must be deployed before the classes being advised are deployed, so that the bindings exist in the system before (for example) the <classname>ejb</classname> and <classname>servlet</classname> classes are loaded. This is acheived by listing the AOP file at the start of the <filename>application.xml</filename>. Other types of archives are deployed before anything else and so do not require special consideration, such as <filename>.sar</filename> and <filename>.war</filename> files.
+ </para>
+ </important>
+ </section>
+ <section>
+ <title>The JBoss AspectManager Service</title>
+ <para>
+ The <classname>AspectManager</classname> Service can be managed at runtime using the JMX console, which is found at <filename>http://localhost:8080/jmx-console</filename>. It is registered under the ObjectName <literal>jboss.aop:service=AspectManager</literal>. If you want to configure it on startup you need to edit some configuration files.
+ </para>
+ <para>
+ In JBoss Enterprise Application Platform 5 the <classname>AspectManager</classname> Service is configured using a JBoss Microcontainer bean. The configuration file is <filename>jboss-as/server/xxx/conf/bootstrap/aop.xml</filename>. The <classname>AspectManager</classname> Service is deployed with the following XML:
+ </para>
<programlisting><![CDATA[
- <bean name="AspectManager" class="org.jboss.aop.deployers.AspectManagerJDK5">
-
- <property name="jbossIntegration"><inject bean="AOPJBossIntegration"/></property>
-
- <property name="enableLoadtimeWeaving">false</property>
- <!-- only relevant when EnableLoadtimeWeaving is true.
- When transformer is on, every loaded class gets transformed.
- If AOP can't find the class, then it throws an exception.
- Sometimes, classes may not have all the classes they reference.
- So, the Suppressing is needed. (For instance, JBoss cache in the default configuration) -->
-
- <property name="suppressTransformationErrors">true</property>
-
- <property name="prune">true</property>
-
- <property name="include">org.jboss.test., org.jboss.injbossaop.</property>
-
- <property name="exclude">org.jboss.</property>
- <!-- This avoids instrumentation of hibernate cglib enhanced proxies
-
- <property name="ignore">*$$EnhancerByCGLIB$$*</property> -->
-
- <property name="optimized">true</property>
-
- <property name="verbose">false</property>
- <!-- Available choices for this attribute are: org.jboss.aop.instrument.ClassicInstrumentor (default)
- org.jboss.aop.instrument.GeneratedAdvisorInstrumentor -->
-
- <!-- <property name="instrumentor">org.jboss.aop.instrument.ClassicInstrumentor</property>-->
-
- <!-- By default the deployment of the aspects contained in
- ../deployers/jboss-aop-jboss5.deployer/base-aspects.xml
- are not deployed. To turn on deployment uncomment this property
- <property name="useBaseXml">true</property>-->
+ <bean name="AspectManager" class="org.jboss.aop.deployers.AspectManagerJDK5">
+
+ <property name="jbossIntegration"><inject bean="AOPJBossIntegration"/></property>
+
+ <property name="enableLoadtimeWeaving">false</property>
+ <!-- only relevant when EnableLoadtimeWeaving is true.
+ When transformer is on, every loaded class gets transformed.
+ If AOP can't find the class, then it throws an exception.
+ Sometimes, classes may not have all the classes they reference.
+ So, the Suppressing is needed. (For instance, JBoss cache in the default configuration) -->
+
+ <property name="suppressTransformationErrors">true</property>
+
+ <property name="prune">true</property>
+
+ <property name="include">org.jboss.test., org.jboss.injbossaop.</property>
+
+ <property name="exclude">org.jboss.</property>
+ <!-- This avoids instrumentation of hibernate cglib enhanced proxies
+
+ <property name="ignore">*$$EnhancerByCGLIB$$*</property> -->
+
+ <property name="optimized">true</property>
+
+ <property name="verbose">false</property>
+ <!-- Available choices for this attribute are: org.jboss.aop.instrument.ClassicInstrumentor (default)
+ org.jboss.aop.instrument.GeneratedAdvisorInstrumentor -->
+
+ <!-- <property name="instrumentor">org.jboss.aop.instrument.ClassicInstrumentor</property>-->
+
+ <!-- By default the deployment of the aspects contained in
+ ../deployers/jboss-aop-jboss5.deployer/base-aspects.xml
+ are not deployed. To turn on deployment uncomment this property
+ <property name="useBaseXml">true</property>-->
</bean>
]]></programlisting>
- <para>
- Later we will talk about changing the class of the AspectManager Service. T,o do this replace the contents of the <literal>class</literal> attribute of the <literal>bean</literal> element.
- </para>
- </section>
- <section id="running-as-sun-jdk">
- <title>Loadtime transformation in the JBoss Enterprise Application Platform Using Sun JDK</title>
- <para>
- The JBoss Enterprise Application Platform has special integration with JDK to do loadtime transformations. This section explains how to use it.
- </para>
- <para>
- If you want to do load-time transformations with JBoss Enterprise Application Platform 5 and Sun JDK, these are the steps you must take.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Set the <literal>enableLoadtimeWeaving</literal> attribute/property to true. By default, JBoss application server will not do load-time bytecode manipulation of AOP files unless this is set. If <literal>suppressTransformationErrors</literal> is <literal>true</literal> failed bytecode transformation will only give an error warning. This flag is needed because sometimes a JBoss deployment will not have all the classes a class references.
- </para>
- </listitem>
- <listitem>
- <para>
- Copy the <literal>pluggable-instrumentor.jar</literal> from the <literal>lib/</literal> directory of your JBoss AOP distribution to the <literal>bin/</literal> directory of your JBoss Enterprise Application Platform.
- </para>
- </listitem>
- <listitem>
- <para>
- Next edit <literal>run.sh</literal> or <literal>run.bat</literal> (depending on what OS you're on) and add the following to the JAVA_OPTS environment variable:
- </para>
+ <para>
+ Later we will talk about changing the class of the <classname>AspectManager</classname> Service. To do this replace the contents of the <varname>class</varname> attribute of the <classname>bean</classname> element.
+ </para>
+ </section>
+ <section id="running-as-sun-jdk">
+ <title>Loadtime transformation in the JBoss Enterprise Application Platform Using Sun JDK</title>
+ <para>
+ The JBoss Enterprise Application Platform has special integration with JDK to do loadtime transformations. This section explains how to use it.
+ </para>
+ <para>
+ If you want to do load-time transformations with JBoss Enterprise Application Platform 5 and Sun JDK, these are the steps you must take.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Set the <varname>enableLoadtimeWeaving</varname> attribute/property to <literal>true</literal>. By default, JBoss Application Server will not do load-time bytecode manipulation of AOP files unless this is set. If <varname>suppressTransformationErrors</varname> is <literal>true</literal>, failed bytecode transformation will only give an error warning. This flag is needed because sometimes a JBoss deployment will not have all of the classes a class references.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Copy the <filename>pluggable-instrumentor.jar</filename> from the <filename>lib/</filename> directory of your JBoss AOP distribution to the <filename>bin/</filename> directory of your JBoss Enterprise Application Platform.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Next edit <filename>run.sh</filename> or <literal>run.bat</literal> (depending on what OS you're on) and add the following to the JAVA_OPTS environment variable:
+ </para>
<programlisting>
set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME% -javaagent:pluggable-instrumentor.jar
</programlisting>
- </listitem>
- </itemizedlist>
- <important>
- <para>
- The class of the AspectManager Service must be <literal>org.jboss.aop.deployers.AspectManagerJDK5</literal> or <literal>org.jboss.aop.deployment.AspectManagerServiceJDK5</literal> as these are what work with the <code>-javaagent</code> option.
- </para>
- </important>
- </section>
- <section>
- <title>JRockit</title>
- <para>
- JRockit also supports the <code>-javaagent</code> switch mentioned in <xref linkend="running-as-sun-jdk"/>. If you wish to use that, then the steps in <xref linkend="running-as-sun-jdk"/> are sufficient. However, JRockit also comes with its own framework for intercepting when classes are loaded, which might be faster than the <code>-javaagent</code> switch. If you want to do load-time transformations using the special JRockit hooks, these are the steps you must take.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Set the <literal>enableLoadtimeWeaving</literal> attribute/property to true. By default, JBoss application server will not do load-time bytecode manipulation of AOP files unless this is set. If <literal>suppressTransformationErrors</literal> is <literal>true</literal> failed bytecode transformation will only give an error warning. This flag is needed because sometimes a JBoss deployment will not have all the classes a class references.
- </para>
- </listitem>
- <listitem>
- <para>
- Copy the <literal>jrockit-pluggable-instrumentor.jar</literal> from the <literal>lib/</literal> directory of your JBoss AOP distribution to the <literal>bin/</literal> directory of your the JBoss Enterprise Application Platform installation.
- </para>
- </listitem>
- <listitem>
- <para>
- Next edit <literal>run.sh</literal> or <literal>run.bat</literal> (depending on what OS you're on) and add the following to the JAVA_OPTS and JBOSS_CLASSPATH environment variables:
- </para>
+ </listitem>
+ </itemizedlist>
+ <important>
+ <para>
+ The class of the AspectManager Service must be <literal>org.jboss.aop.deployers.AspectManagerJDK5</literal> or <literal>org.jboss.aop.deployment.AspectManagerServiceJDK5</literal> as these are what work with the <code>-javaagent</code> option.
+ </para>
+ </important>
+ </section>
+ <section>
+ <title>JRockit</title>
+ <para>
+ JRockit also supports the <code>-javaagent</code> switch mentioned in <xref linkend="running-as-sun-jdk"/>. If you wish to use that, then the steps in <xref linkend="running-as-sun-jdk"/> are sufficient. However, JRockit also comes with its own framework for intercepting when classes are loaded, which might be faster than the <code>-javaagent</code> switch. If you want to do load-time transformations using the special JRockit hooks, these are the steps you must take.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Set the <literal>enableLoadtimeWeaving</literal> attribute/property to true. By default, JBoss application server will not do load-time bytecode manipulation of AOP files unless this is set. If <varname>suppressTransformationErrors</varname> is <literal>true</literal> failed bytecode transformation will only give an error warning. This flag is needed because sometimes a JBoss deployment will not have all the classes a class references.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Copy the <filename>jrockit-pluggable-instrumentor.jar</filename> from the <filename>lib/</filename> directory of your JBoss AOP distribution to the <filename>bin/</filename> directory of your the JBoss Enterprise Application Platform installation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Next edit <filename>run.sh</filename> or <filename>run.bat</filename> (depending on what OS you're on) and add the following to the JAVA_OPTS and JBOSS_CLASSPATH environment variables:
+ </para>
<programlisting>
-# Setup JBoss sepecific properties
+# Setup JBoss specific properties
JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME \
@@ -352,57 +328,57 @@
JBOSS_CLASSPATH="$JBOSS_CLASSPATH:jrockit-pluggable-instrumentor.jar"
</programlisting>
- </listitem>
- <listitem>
- <para>
- Set the class of the AspectManager Service to be <literal>org.jboss.aop.deployers.AspectManagerJRockit</literal> on JBoss Enterprise Application Platform 5, or <literal>org.jboss.aop.deployment.AspectManagerService</literal> as these are what work with special hooks in JRockit.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Improving Loadtime Performance in tje JBoss Enterprise Application Platform Environment</title>
- <para>
- The same rules apply to the JBoss Enterprise Application Platform for tuning loadtime weaving performance as standalone Java. Switches such as pruning, optimized, include and exclude are configured through the <filename>jboss-5.x.x.GA/server/xxx/conf/aop.xml</filename> file talked about earlier in this chapter.
- </para>
- </section>
- <section>
- <title>Scoping the AOP to the classloader</title>
- <para>
- By default all deployments in JBoss are global to the whole application server. That means that any EAR, SAR, JAR (for example), that is put in the deploy directory can see the classes from any other deployed archive. Similarly, aop bindings are global to the whole virtual machine. This <emphasis>global</emphasis> visibility can be turned off per top-level deployment.
- </para>
- <section>
- <title>Deploying as part of a scoped classloader</title>
- <para>
- How the following works may be changed in future versions of <filename>jboss-aop</filename>. If you deploy a AOP file as part of a scoped archive or the bindings (for instance), applied within the <filename>.aop/META-INF/jboss-aop.xml</filename> file will only apply to the classes within the scoped archive and not to anything else in the application server. Another alternative is to deploy <filename>-aop.xml</filename> files as part of a service archive (SAR). Again if the SAR is scoped, the bindings contained in the <filename>-aop.xml</filename> files will only apply to the contents of the SAR file. It is not currently possible to deploy a standalone <filename>-aop.xml</filename> file and have that attach to a scoped deployment. Standalone <filename>-aop.xml</filename> files will apply to classes in the whole application server.
- </para>
- </section>
- <section>
- <title>Attaching to a scoped deployment</title>
- <para>
- If you have an application using classloader isolation, as long as you have prepared your classes you can later attach a AOP file to that deployment. If we have an EAR file scoped using a <filename>jboss-app.xml</filename> file, with the scoped loader repository <literal>jboss.test:service=scoped</literal>:
- </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set the class of the <classname>AspectManager</classname> Service to be <literal>org.jboss.aop.deployers.AspectManagerJRockit</literal> on JBoss Enterprise Application Platform 5, or <literal>org.jboss.aop.deployment.AspectManagerService</literal> as these are what work with special hooks in JRockit.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Improving Loadtime Performance in the JBoss Enterprise Application Platform Environment</title>
+ <para>
+ The same rules apply to the JBoss Enterprise Application Platform for tuning loadtime weaving performance as standalone Java. Switches such as pruning, optimized, include and exclude are configured through the <filename>jboss-5.x.x.GA/server/xxx/conf/aop.xml</filename> file talked about earlier in this chapter.
+ </para>
+ </section>
+ <section>
+ <title>Scoping the AOP to the classloader</title>
+ <para>
+ By default all deployments in JBoss are global to the whole application server. That means that any EAR, SAR, or JAR (for example), that is put in the deploy directory can see the classes from any other deployed archive. Similarly, AOP bindings are global to the whole virtual machine. This <emphasis>global</emphasis> visibility can be turned off per top-level deployment.
+ </para>
+ <section>
+ <title>Deploying as part of a scoped classloader</title>
+ <para>
+ How the following works may be changed in future versions of JBoss AOP. If you deploy a AOP file as part of a scoped archive or the bindings (for instance), applied within the <filename>.aop/META-INF/jboss-aop.xml</filename> file will only apply to the classes within the scoped archive and not to anything else in the application server. Another alternative is to deploy <filename>-aop.xml</filename> files as part of a service archive (SAR). Again if the SAR is scoped, the bindings contained in the <filename>-aop.xml</filename> files will only apply to the contents of the SAR file. It is not currently possible to deploy a standalone <filename>-aop.xml</filename> file and have that attach to a scoped deployment. Standalone <filename>-aop.xml</filename> files will apply to classes in the whole application server.
+ </para>
+ </section>
+ <section>
+ <title>Attaching to a scoped deployment</title>
+ <para>
+ If you have an application using classloader isolation, as long as you have prepared your classes you can later attach an AOP file to that deployment. If we have an EAR file scoped using a <filename>jboss-app.xml</filename> file, with the scoped loader repository <literal>jboss.test:service=scoped</literal>:
+ </para>
<programlisting>
-<boss-app>
- <loader-repository>
- jboss.test:service=scoped
- </loader-repository>
+<jboss-app>
+ <loader-repository>
+ jboss.test:service=scoped
+ </loader-repository>
</jboss-app>
</programlisting>
- <para>
- We can later deploy a AOP file containing aspects and configuration to attach that deployment to the scoped EAR. This is done using the <literal>loader-repository</literal> tag in the AOP files <literal>META-INF/jboss-aop.xml</literal> file.
- </para>
+ <para>
+ We can later deploy an AOP file containing aspects and configuration to attach that deployment to the scoped EAR. This is done using the <literal>loader-repository</literal> tag in the AOP file's <filename>META-INF/jboss-aop.xml</filename> file.
+ </para>
<programlisting>
<?xml version="1.0" encoding="UTF-8"?>
<aop>
- <loader-repository>jboss.test:service=scoped</loader-repository>
-
- <!-- Aspects and bindings -->
+ <loader-repository>jboss.test:service=scoped</loader-repository>
+
+ <!-- Aspects and bindings -->
</aop>
</programlisting>
- <para>
- This has the same effect as deploying the AOP file as part of the EAR as we saw previously, but allows you to hot deploy aspects into your scoped application.
- </para>
- </section>
- </section>
-</chapter>
+ <para>
+ This has the same effect as deploying the AOP file as part of the EAR as we saw previously, but allows you to hot deploy aspects into your scoped application.
+ </para>
+ </section>
+ </section>
+</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list