[jboss-cvs] JBossAS SVN: r93054 - 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
Mon Aug 31 22:23:42 EDT 2009
Author: irooskov at redhat.com
Date: 2009-08-31 22:23:41 -0400 (Mon, 31 Aug 2009)
New Revision: 93054
Modified:
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
Log:
added info to Chapter 7 - AOP from tech review
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-09-01 00:49:38 UTC (rev 93053)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2009-09-01 02:23:41 UTC (rev 93054)
@@ -172,4 +172,237 @@
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.
</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:
+<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>
+<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>
+</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-5.x.x.GA/server/xxx/conf/aop.xml</literal>. The AspectManager 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>
+]]></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>
+<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>
+<programlisting>
+# Setup JBoss sepecific properties
+
+JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME \
+
+-Xmanagement:class=org.jboss.aop.hook.JRockitPluggableClassPreProcessor"
+
+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-aop.deployer/META-INF/jboss-service.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>
+<programlisting>
+<boss-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>
+<programlisting>
+<?xml version="1.0" encoding="UTF-8"?>
+<aop>
+ <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>
More information about the jboss-cvs-commits
mailing list