[jboss-cvs] JBossAS SVN: r98068 - projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Dec 21 01:07:08 EST 2009
Author: laubai
Date: 2009-12-21 01:07:08 -0500 (Mon, 21 Dec 2009)
New Revision: 98068
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
Log:
Edited AOP chapter of Admin and Config Guide.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2009-12-21 06:06:33 UTC (rev 98067)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2009-12-21 06:07:08 UTC (rev 98068)
@@ -48,9 +48,10 @@
<!--merged sections</section>-->
<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
+<programlisting id="aop.code1" role="JAVA">public class BankAccountDAO
{
public void withdraw(double amount)
{
@@ -71,10 +72,10 @@
<orderedlist>
<listitem>
-<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>
+<para>It's extremely difficult to turn metrics on and off, as you have to manually add the code in the <code>try</code>/<code>finally</code> blocks to each and every method or constructor you want to benchmark. </para>
</listitem>
<listitem>
-<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>
+<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>/<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,7 +84,7 @@
</para>
<para>
- 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.
+ This approach to metrics is very difficult to maintain, expand, and extend, because it is 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>
@@ -95,15 +96,16 @@
<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.
+ 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.
+ The first step in creating a metrics aspect in JBoss AOP is to encapsulate the metrics feature in its own Java class. The following code extracts the <code>try</code>/<code>finally</code> block in our first code example's <methodname>BankAccountDAO.withdraw()</methodname> method into <literal>Metrics</literal>, an implementation of a JBoss AOP Interceptor class.
</para>
<para>
- The following listing demonstrates Implementing metrics in a JBoss AOP Interceptor
+ The following example code 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,13 +122,13 @@
14. System.out.println("method " + m.toString() + " time: " + endTime + "ms");
15. }
16. }
-17. }</programlisting>
+17. }</programlisting>
<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.
+ 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 <code>try</code>/<code>finally</code> block to perform the timings. Line 13 obtains contextual information about the method call from the <classname>Invocation</classname> 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.
@@ -138,44 +140,43 @@
<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."
+ To apply an aspect, you define when to execute the aspect code. Those points in execution are called <emphasis>pointcuts</emphasis>. An analogy to a pointcut is a regular expression. Where a regular expression matches strings, a pointcut expression matches events or <emphasis>points</emphasis> within your application. For example, a valid pointcut definition would be, "for all calls to the JDBC method <methodname>executeQuery()</methodname>, 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.
+ 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.
</para>
<para>
- The following listing demonstrates defining a pointcut in JBoss AOP
+ The following listing demonstrates defining a pointcut for the Metrics example 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 role="XML"><![CDATA[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 <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.
+ Lines 1-3 define a pointcut that applies the <literal>metrics</literal> aspect to the specific method <methodname>BankAccountDAO.withdraw()</methodname>. Lines 4-6 define a general pointcut that applies the <literal>metrics</literal> aspect to all methods in all classes in the <filename>com.mc.billing</filename> package. There is also an optional annotation mapping if you prefer to avoid XML. For more information, see the JBoss AOP reference documentation.
</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 or events in your Java application. Once your points are defined, you can apply aspects to them. 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 can combine all crosscutting behavior into one object and apply it easily and simply, without complicating your code with features unrelated to business logic. Instead, common crosscutting concerns can be maintained and extended in one place.
</para>
<para>
- 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.
+ Note that code within the <classname>BankAccountDAO</classname> class does not detect that it is being profiled. Profiling is part of what aspect-oriented programmers deem orthogonal concerns. In the object-oriented programming code snippet at the beginning of this chapter, profiling was part of the application code. AOP allows you to 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 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.
+ Orthogonal behavior can also be included after development. In object-oriented code, 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 <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>.
+ To deploy an AOP application in JBoss Enterprise Web Platform 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 Web 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:
@@ -262,7 +263,7 @@
</bean>
]]></programlisting>
<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.
+ 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">
@@ -276,7 +277,7 @@
<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.
+ 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 include all of the classes referenced.
</para>
</listitem>
<listitem>
@@ -286,7 +287,7 @@
</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:
+ Next edit <filename>run.sh</filename> or <literal>run.bat</literal> (depending on what OS you're on) and add the following to the <varname>JAVA_OPTS</varname> environment variable:
</para>
<programlisting>
set JAVA_OPTS=%JAVA_OPTS% -Dprogram.name=%PROGNAME% -javaagent:pluggable-instrumentor.jar
@@ -307,7 +308,7 @@
<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.
+ Set the <literal>enableLoadtimeWeaving</literal> attribute/property to true. By default, JBoss Enterprise Web Platform 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 include all the classes referenced.
</para>
</listitem>
<listitem>
@@ -317,7 +318,7 @@
</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:
+ Next edit <filename>run.sh</filename> or <filename>run.bat</filename> (depending on what OS you're on) and add the following to the <varname>JAVA_OPTS</varname> and <varname>JBOSS_CLASSPATH</varname> environment variables:
</para>
<programlisting>
# Setup JBoss specific properties
@@ -331,7 +332,7 @@
</listitem>
<listitem>
<para>
- Set the class of the <classname>AspectManager</classname> Service to be <literal>org.jboss.aop.deployers.AspectManagerJRockit</literal> on JBoss Enterprise Web Platform 5, or <literal>org.jboss.aop.deployment.AspectManagerService</literal> as these are what work with special hooks in JRockit.
+ Set the class of the <classname>AspectManager</classname> Service to <literal>org.jboss.aop.deployers.AspectManagerJRockit</literal> on JBoss Enterprise Web Platform 5, or <literal>org.jboss.aop.deployment.AspectManagerService</literal> as these are what work with special hooks in JRockit.
</para>
</listitem>
</itemizedlist>
@@ -350,13 +351,13 @@
<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.
+ The following process may change in future versions of JBoss AOP. If you deploy an AOP file as part of a scoped archive, 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>:
+ If you have an application that uses 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>
<jboss-app>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2009-12-21 06:06:33 UTC (rev 98067)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2009-12-21 06:07:08 UTC (rev 98068)
@@ -727,7 +727,7 @@
<section>
<title>Support Foreign Keys in CMP Services</title>
- <para>Next, we need to go change the <filename>$JBOSS_HOME/server/$PROFILE/conf/standardjbosscmp-jdbc.xml</filename> file so that the <varname>fk-constraint</varname> property is <literal>true</literal>. That is needed for all external databases we support on the JBoss Enterprise Web Platform. This file configures the database connection settings for the EJB2 CMP beans deployed in the JBoss Enterprise Web Platform.</para>
+ <para>Next, we need to go change the <filename>$JBOSS_HOME/server/$PROFILE/conf/standardjbosscmp-jdbc.xml</filename> file so that the <varname>fk-constraint</varname> property is <literal>true</literal>. This is required for all external databases supported on the JBoss Enterprise Web Platform. This file configures the database connection settings for the EJB2 CMP beans deployed in the JBoss Enterprise Web Platform.</para>
<programlisting role="XML"><![CDATA[<fk-constraint>true</fk-constraint>]]></programlisting>
More information about the jboss-cvs-commits
mailing list