[prev in list] [next in list] [prev in thread] [next in thread]
List: jboss-cvs-commits
Subject: [jboss-cvs] jboss-docs/adminguide/docbook/en/modules appendix-c.xml chap10.xml chap11.xml chap5.xml
From: Norman Richards <orb () users ! sourceforge ! net>
Date: 2004-12-31 23:43:37
Message-ID: E1CkWQj-0005ob-5u () sc8-pr-cvs1 ! sourceforge ! net
[Download RAW message or body]
User: orb
Date: 04/12/31 15:43:37
Modified: adminguide/docbook/en/modules appendix-c.xml chap10.xml
chap11.xml chap5.xml chap6.xml chap7.xml chap8.xml
chap9.xml jbossaop.xml
Log:
a few more typos, fix validation errors
Revision Changes Path
1.2 +23 -27 jboss-docs/adminguide/docbook/en/modules/appendix-c.xml
Index: appendix-c.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/appendix-c.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- appendix-c.xml 29 Nov 2004 15:58:10 -0000 1.1
+++ appendix-c.xml 31 Dec 2004 23:43:34 -0000 1.2
@@ -2,41 +2,37 @@
<appendix id="appendix-install">
<title>Book Example Installation</title>
<para>The book comes with the source code for the examples discussed in the
- book. The examples are included with the book archive. When you unzip
- the <literal>JBossBook_326.zip</literal> archive this creates an
- <literal>AdminDevel</literal> directory that
- contains an examples subdirectory. This is the examples directory
- referred to by the book.</para>
+ book. The examples are included with the book archive. Unzipping
+ the example code archive creates a JBoss
+ <literal>jboss4guide</literal> directory that contains an
+ <literal>examples</literal> subdirectory. This is the
+ <literal>examples</literal> directory referred to by the book.</para>
<para>The only customization needed before the examples may be used it to
set the location of the JBoss server distribution. This may be done by
- editing the <literal>examples/build.xml</literal> file and changing the
- <literal>jboss.dist</literal> property
- value. This is shown in bold below:</para>
-
- <programlisting><project name="JBossBook 3.2.x examples"
- default="build-all" basedir=".">
-
+ editing the <literal>examples/build.xml</literal> file and changing the
+ <literal>jboss.dist</literal> property value. This is shown in bold \
below:</para> + <programlisting><project name="JBoss book examples" \
default="build-all" basedir="."> <!-- Allow override from \
local properties file -->
- <property file=".ant.properties" />
- <!-- Override with your JBoss/Web server bundle dist location \
--><emphasis role="bold">
- <property name="jboss.dist" value="/tmp/jboss-3.2.6"/></emphasis>
- <property name="jboss.deploy.dir" \
value="${jboss.dist}/server/default/deploy"/>
-</programlisting>
-
- <para>or by creating an <literal>.ant.properties</literal> file in the \
examples
- directory that contains a definition for the <literal>jboss.dist</literal>
- property. For example:</para>
- <programlisting>jboss.dist=/usr/JBoss3.2/jboss-3.2/build/output/jboss-3.2.6</programlisting>
+ <property file="ant.properties"/>
+
+ <!-- Override with your JBoss server bundle dist location -->
+ <property name="jboss.dist" value="<emphasis \
role="bold">/tmp/jboss-4.0.1</emphasis>"/> + <property \
name="jboss.deploy.conf" value="default"/> + \
...</programlisting> + <para>or by creating an <literal>.ant.properties</literal> \
file in the + examples directory that contains a definition for the
+ <literal>jboss.dist</literal> property. For example:</para>
+ <programlisting>jboss.dist=/usr/local/jboss/jboss-4.0.1</programlisting>
<para>Part of the verification process validates that the version you are
running the examples against matches what the book examples were tested
against. If you have a problem running the examples first look for the
output of the validate target such as the following:</para>
<programlisting>validate:
- [java] ImplementationTitle: JBoss [WonderLand]
- [java] ImplementationVendor: JBoss.org
- [java] ImplementationVersion: 3.2.6RC2 (build: CVSTag=Branch_3_2 \
date=200409270100) + [java] ImplementationTitle: JBoss [Zion]
+ [java] ImplementationVendor: JBoss Inc.
+ [java] ImplementationVersion: 4.0.1 (build: CVSTag=JBoss_4_0_1 \
date=200412230944) [java] SpecificationTitle: JBoss
[java] SpecificationVendor: JBoss (http://www.jboss.org/)
- [java] SpecificationVersion: 3.2.6
- [java] JBoss version is: 3.2.6</programlisting>
+ [java] SpecificationVersion: 4.0.1
+ [java] JBoss version is: 4.0.1</programlisting>
</appendix>
1.5 +16 -16 jboss-docs/adminguide/docbook/en/modules/chap10.xml
Index: chap10.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/chap10.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- chap10.xml 28 Dec 2004 03:35:32 -0000 1.4
+++ chap10.xml 31 Dec 2004 23:43:34 -0000 1.5
@@ -22,7 +22,7 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">URLList</emphasis>: a comma seperated \
list of URL strings + <emphasis role="bold">URLList</emphasis>: a \
comma separated list of URL strings
from which to load properties file formatted content. If a \
component in the list
is a relative path rather than a URL it will be treated as a \
file path relative to the
@@ -38,7 +38,7 @@
<programlisting><mbean \
code="org.jboss.varia.property.SystemPropertiesService" \
name="jboss.util:type=Service,name=SystemProperties">
- <!-- Load properties from each of the given comma seperated URLs -->
+ <!-- Load properties from each of the given comma separated URLs -->
<attribute name="URLList">
http://somehost/some-location.properties,
./conf/somelocal.properties
@@ -63,7 +63,7 @@
to for editing values in the JMX console. The
<literal>java.bean.PropertyEditorManager</literal> class controls the
<literal>java.bean.PropertyEditor</literal> instances in the system. \
The property editor
- manager can be managed in JBoss using the the
+ manager can be managed in JBoss using the
<literal>org.jboss.varia.property.PropertyEditorManagerService</literal> \
MBean. The property editor manager service is configured in
<literal>deploy/properties-service.xml</literal> and supports the \
following attributes: </para> @@ -112,7 +112,7 @@
<para>
<emphasis role="bold">ServerName</emphasis>: This is the name \
of the server
configuration this JBoss instance is associated with. The \
binding manager will
- aply the overrides defined for the named configuration. \
</para> + apply the overrides defined for the named \
configuration. </para> </listitem>
<listitem>
<para>
@@ -120,19 +120,19 @@
class that implements the \
<literal>ServicesStoreFactory</literal> interface. You
may provide your own implementation, or use the default XML \
based store
\
<literal>org.jboss.services.binding.XMLServicesStoreFactory</literal>. \
The
- factory provides a <literal>ServicesStore</literal> instance \
repsonsible for + factory provides a \
<literal>ServicesStore</literal> instance responsible for providing the names \
configuration sets.</para> </listitem>
<listitem>
<para>
<emphasis role="bold">StoreURL</emphasis>: This is the URL of \
the configuration
store contents, which is passed to the \
<literal>ServicesStore</literal> instance
- to load the server configuration sets from.For the XML store, \
this is a + to load the server configuration sets from. For the \
XML store, this is a simple service binding file. </para> </listitem>
</itemizedlist>
<para> The following is a sample service binding manager configuration \
that uses the <literal>ports-01</literal> configuration from the
- <literal>sample-bindings.xml</literal> file provided in in the JBoss \
examples directory. </para> + <literal>sample-bindings.xml</literal> file \
provided in the JBoss examples directory. </para>
<programlisting><mbean \
code="org.jboss.services.binding.ServiceBindingManager" \
name="jboss.system:service=ServiceBindingManager">
<attribute name="ServerName">ports-01</attribute>
@@ -347,7 +347,7 @@
previously. You can observe that the port numbers in the console log \
are different for
the <literal>jboss1</literal> server. To test out that both instances \
work correctly,
try accessing the web server of the first JBoss on port 8080 and then \
try the second
- JBoss instance on port port 8180. </para>
+ JBoss instance on port 8180. </para>
</section>
<section id="ch10.sched.sect">
<title>Scheduling Tasks</title>
@@ -382,7 +382,7 @@
<listitem>
<para>Date as String able to be parsed by
<literal>SimpleDateFormat</literal> with default \
format pattern
- "<literal>M/d/yy h:mm a</literal>".If the date \
is in the past + "<literal>M/d/yy h:mm \
a</literal>". If the date is in the past
the <literal>Scheduler</literal> will search a \
start date in the
future with respect to the initial repetitions and \
the period
between calls. This means that when you restart \
the MBean @@ -426,20 +426,20 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">SchedulableArguments</emphasis>: A \
comma seperated + <emphasis \
role="bold">SchedulableArguments</emphasis>: A comma separated
list of arguments for the <literal>Schedulable</literal> \
implementation
class constructor. Only primitive data types, \
<literal>String</literal> and
classes with a constructor that accepts a \
<literal>String</literal> as its
- sole aregument are supported.</para>
+ sole argument are supported.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">SchedulableArgumentTypes</emphasis>: \
A comma seperated + <emphasis \
role="bold">SchedulableArgumentTypes</emphasis>: A comma separated
list of argument types for the \
<literal>Schedulable</literal> implementation
class constructor. This will be used to find the correct \
constructor via
reflection. Only primitive data types, \
<literal>String</literal> and classes
with a constructor that accepts a \
<literal>String</literal> as its sole
- aregument are supported.</para>
+ argument are supported.</para>
</listitem>
<listitem>
<para>
@@ -454,7 +454,7 @@
<para>
<emphasis role="bold">SchedulableMBeanMethod</emphasis>: \
Specifies the
operation name to be called on the schedulable MBean. It \
can optionally be
- followed by an opening bracket, a comma seperated list of \
parameter + followed by an opening bracket, a comma separated \
list of parameter
keywords, and a closing bracket. The supported parameter \
keywords include:</para> <itemizedlist>
<listitem>
@@ -518,7 +518,7 @@
/**
* A simple Schedulable example.
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.4 $
+ * @version $Revision: 1.5 $
*/
public class ExSchedulable implements Schedulable
{
@@ -544,7 +544,7 @@
<para>Deploy the timer SAR by running:</para>
<programlisting>[examples]$ ant -Dchap=chap10 -Dex=2 \
run-example</programlisting>
<para>The server console shows the following which includes the first \
two timer
- invocations, seperated by 60 seconds:</para>
+ invocations, separated by 60 seconds:</para>
<programlisting>21:09:27,716 INFO [ExSchedulable] ctor, name: \
TheName, value: 123456789 21:09:28,925 INFO [ExSchedulable] perform, now: Mon Dec \
20 21:09:28 CST 2004, remainingRepetitions: -1, name: TheName, value: 123456789 \
21:10:28,899 INFO [ExSchedulable] perform, now: Mon Dec 20 21:10:28 CST 2004, \
remainingRepetitions: -1, name: TheName, value: 123456789
1.4 +44 -44 jboss-docs/adminguide/docbook/en/modules/chap11.xml
Index: chap11.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/chap11.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- chap11.xml 28 Dec 2004 03:35:32 -0000 1.3
+++ chap11.xml 31 Dec 2004 23:43:34 -0000 1.4
@@ -2,10 +2,10 @@
<chapter id="ch11.chapter">
<title>The CMP Engine</title>
<para>This chapter will explore the use of container managed persistence
- (CMP) in JBoss. We will assume a basic familiarity the the EJB CMP model
- and focus on the operation of the JBoss CMP engine. Specifically, we
- will look at how to configure and optimize CMP applications on JBoss.
- For more introductory coverage of basic CMP concepts, we recomment
+ (CMP) in JBoss. We will assume a basic familiarity the EJB CMP model and
+ focus on the operation of the JBoss CMP engine. Specifically, we will
+ look at how to configure and optimize CMP applications on JBoss. For
+ more introductory coverage of basic CMP concepts, we recommend
<emphasis>Enterprise Java Beans, Fourth Edition</emphasis> (O'Reilly \
2004).</para> <section>
<title>Example Code</title>
@@ -45,12 +45,12 @@
<para>Since the beans in the examples are configured to have their
tables removed on undeployment, anytime you restart the JBoss server
you need to rerun the config target to reload the example data and
- re-deploy the the application.</para>
+ re-deploy the application.</para>
<section>
<title>Enabling CMP Debug Logging</title>
<para>In order to get meaningful feedback from the chapter tests,
you will want to increase the log level of the CMP subsystem
- beforring running the test. To enable debug logging add the
+ before running running the test. To enable debug logging add the
following category to your <literal>log4j.xml</literal> \
file:</para>
<programlisting><category name="org.jboss.ejb.plugins.cmp">
<priority value="DEBUG"/>
@@ -818,7 +818,7 @@
<listitem>
<para>
<emphasis role="bold">state-factory</emphasis>: This
- specfies class name of a state factory object which can
+ specifies class name of a state factory object which can
perform dirty checking for this field. State factory
classes must implement the
<literal>CMPFieldStateFactory</literal> interface. </para>
@@ -855,11 +855,11 @@
</section>
<section id="ch11.audit.sect">
<title>Auditing Entity Access</title>
- <para>The auadit element of the entity section allows one to specify
- how access to and entity bean is audited. This is only allowed
- when an entity bean is accessed under a security domain so that
- this is a caller identity established. The content model of the
- audit element is given <xref linkend="ch11.audit.fig"/>.</para>
+ <para>The <literal>audit</literal> element of the entity section
+ allows one to specify how access to and entity bean is audited.
+ This is only allowed when an entity bean is accessed under a
+ security domain so that this is a caller identity established.
+ The content model of the audit element is given <xref \
linkend="ch11.audit.fig"/>.</para> <figure id="ch11.audit.fig">
<title>The jbosscmp-jdbc.xml audit element content model </title>
<mediaobject>
@@ -941,7 +941,7 @@
</section>
<section id="ch11.dvc.sect">
<title>Dependent Value Classes (DVCs)</title>
- <para>A dependent balue class (DVC) is a fancy term used to identity
+ <para>A dependent value class (DVC) is a fancy term used to identity
any Java class that is the type of a
<literal>cmp-field</literal> other than the automatically
recognized types core types such as strings and number values.
@@ -1107,7 +1107,7 @@
<literal>cmp-field</literal> followed by an underscore and then
the column name of the property. If the property is a DVC, the
process is repeated. For example, a <literal>cmp-field</literal>
- named <literal>info</literal> that uses the the
+ named <literal>info</literal> that uses the
<literal>ContactInfo</literal> DVC would have the following \
columns:</para> <programlisting>info_cell_area_code
info_cell_exchange
@@ -1194,7 +1194,7 @@
entity, and multi-valued relationships can only return a
<literal>java.util.Collection</literal> (or
<literal>java.util.Set</literal>) object. For example, to
- declare a one-to-many relationship between organzation and
+ declare a one-to-many relationship between organization and
gangster, we declare the relationship from organization to
gangster in the <literal>OrganizationBean</literal> class:</para>
<programlisting>public abstract class OrganizationBean
@@ -1388,7 +1388,7 @@
either a <literal>foreign-key-mapping</literal> element or a
<literal>relation-table-mapping</literal> element, which are
described in <xref linkend="ch11.fkmap.sect"/> and <xref
- linkend="chg11.rtmap.sect"/>.<literal/> This element may also
+ linkend="ch11.rtmap.sect"/>.<literal/> This element may also
contain a pair of <literal>ejb-relationship-role</literal>
elements as described in the following section.</para>
<section>
@@ -1421,7 +1421,7 @@
<listitem>
<para>
<emphasis role="bold">fk-constraint</emphasis>: This
- optional element is is a true/false value that
+ optional element is a true/false value that
indicates whether JBoss should add a foreign key
constraint to the tables for this side of the
relationship. JBoss will only add generate the
@@ -1750,7 +1750,7 @@
an entity implementation. Unlike finders, which are restricted to
only return entities of the same type as the home interface on which
they are defined, select methods can return any entity type or just
- one field of the entity. EJB-QL is the query language used used to
+ one field of the entity. EJB-QL is the query language used to
specify finders and select methods in a platform independent way. \
</para> <section>
<title>Finder and select Declaration</title>
@@ -1761,7 +1761,7 @@
<literal>findBadDudes_ejbql</literal> finder on the
<literal>GangsterHome</literal> interface. The
<literal>ejbql</literal> suffix here is not required. It is
- simply a naming convention used here to differentiate the the
+ simply a naming convention used here to differentiate the
different types of query specifications we will be looking at. \
</para> <programlisting>public interface GangsterHome
extends EJBLocalHome
@@ -1770,7 +1770,7 @@
}</programlisting>
<para>Select methods are declared in the entity implementation
class, and must be public and abstract just like CMP and CMR
- field abstract accessorsand must throw a
+ field abstract accessors and must throw a
<literal>FinderException</literal>. The following code declares
an select method:</para>
<programlisting>public abstract class GangsterBean
@@ -2059,7 +2059,7 @@
<para>DeclaredSQL is based on the legacy JAWS CMP 1.1 engine finder
declaration, but has been updated for CMP 2.0. Commonly this
declaration is used to limit a query with a
- <literal>WHERE</literal> clause that cannot be represented in
+ <literal>WHERE</literal> clause that cannot be represented in q
EJB-QL or JBossQL. The content model for the declared-sql
element is given in <xref linkend="ch11.declsql.fig"/>.</para>
<figure id="ch11.declsql.fig">
@@ -2225,8 +2225,8 @@
<literal>SELECT</literal> clause to use the <literal>SELECT
DISTINCT</literal> declaration. The DeclaredSQL declaration can
also be used in select methods to select a CMP field. </para>
- <para> Now we well see an example which overrides a selectto select
- all of the zip codes in which an <literal>Organization</literal> \
operates.</para> + <para> Now we well see an example which overrides a \
select to return + all of the zip codes an \
<literal>Organization</literal> operates in.</para> \
<programlisting><jbosscmp-jdbc> <enterprise-beans>
<entity>
@@ -2319,7 +2319,7 @@
entity can be dereferenced (this restriction may be
removed in later versions). The JDBC type used to
set the parameter is the JDBC type that is declared
- for that field in the entitydeclaration.</para>
+ for that field in the entity declaration.</para>
</listitem>
</itemizedlist>
</section>
@@ -2335,7 +2335,7 @@
<ql-compiler>org.jboss.ejb.plugins.cmp.jdbc.JDBCEJBQLCompiler</ql-compiler>
...
</defaults></programlisting>
- <para>To use the SQL92 compiler, simply specifyt the SQL92 compiler
+ <para>To use the SQL92 compiler, simply specify the SQL92 compiler
in <literal>ql-compiler</literal> element. </para>
<programlisting><defaults>
...
@@ -2473,7 +2473,7 @@
until a method is invoked on it. This is known as the
<emphasis>n+1</emphasis> problem and is addressed with the
read-ahead strategies described in the following sections. </para>
- <para> Second, the values of unused fields are loaded neeedlessly.
+ <para> Second, the values of unused fields are loaded needlessly.
JBoss loads the <literal>hangout</literal> and
<literal>organization</literal> fields, which are never
accessed. (we have disabled the complex
@@ -2617,8 +2617,7 @@
<section>
<title>on-find</title>
<para>The <literal>on-find</literal> strategy reads additional
- columns when the query is invoked. If the query in the
- scenario detailed <xref linkend="ch11.loadscen.ex"/> is
+ columns when the query is invoked. If the query is
<literal>on-find</literal> optimized, JBoss will execute the
following query when the query is executed.</para>
<programlisting>SELECT t0_g.id, t0_g.name, t0_g.nick_name, \
t0_g.badness @@ -2997,7 +2996,7 @@
</enterprise-beans>
</jbosscmp-jdbc></programlisting>
<para>With this strategy, the query for the finder method in
- <xref linkend="ch11.loadscen.ex"/> remains \
unchanged.</para> + remains unchanged.</para>
<programlisting>SELECT t0_g.id
FROM gangster t0_g
ORDER BY t0_g.id ASC </programlisting>
@@ -3464,7 +3463,8 @@
(gangster.id=6) OR (gangster.id=7))</programlisting>
<para>The following table shows the execution of the \
queries:</para> <table>
- <title>Gangster Location</title> --> <title>on-find
+ <!-- <title>Gangster Location</title> -->
+ <title>on-find
Optimized Relationship Query Execution</title>
<tgroup cols="9">
<colspec colname="c1" colnum="1" colwidth=".5*"/>
@@ -3585,7 +3585,7 @@
</section>
<section>
<title>Lazy loading result sets</title>
- <para>By default, when a multiobject finder or select method is
+ <para>By default, when a multi-object finder or select method is
executed the JDBC result set is read to the end immediately. The
client receives a collection of
<literal>EJBLocalObject</literal> or CMP field values which it
@@ -3593,7 +3593,7 @@
not efficient. In some cases it is better to delay reading the
next row in the result set until the client tries to read the
corresponding value from the collection. You can get this
- behaviour for a query using the
+ behavior for a query using the
<literal>lazy-resultset-loading</literal> element.</para>
<programlisting><query>
<query-method>
@@ -3625,8 +3625,7 @@
back, the data in the preload cache is lost. This can result in a
severe negative performance impact.</para>
<para>The performance impact of running without a transaction will be
- demonstrated with an example similar to <xref
- linkend="ch11.loadscen.ex"/>. This example uses an
+ demonstrated with an example that uses an
<literal>on-find</literal> optimized query that selects the first
four gangsters (to keep the result set small), and it is executed
without a wrapper transaction. The example code follows:</para>
@@ -3704,7 +3703,8 @@
<literal>trans-attribute</literal> in the
<literal>assembly-descriptor</literal>. If the code is not running
in an EJB, a user transaction is necessary. The following code wraps
- a call to the declared method with a user transaction:</para> \ \
<programlisting>public String createGangsterHtmlTable_with_tx() + a call \
to the declared method with a user transaction:</para> + \
<programlisting>public String createGangsterHtmlTable_with_tx() throws \
FinderException {
UserTransaction tx = null;
@@ -4012,7 +4012,7 @@
<literal>org.jboss.ejb.plugins.cmp.jdbc.JDBCInsertPKCreateCommand</literal>
if the command must insert the generated key.</para>
<para> The optional <literal>attribute</literal> element(s) allows for
- the specification of arbitrary name/value property paris that will
+ the specification of arbitrary name/value property pairs that will
be available to the entity command implementation class. The
<literal>attribute</literal> element has a required
<literal>name</literal> attribute that specifies the name property,
@@ -4078,7 +4078,7 @@
\
(<literal>org.jboss.ejb.plugins.cmp.jdbc.keygen.JDBCOracleCreateCommand</literal>)
The <literal>JDBCOracleCreateCommand</literal> is a
create command for use with Oracle that uses a sequence
- in conjuction with a <literal>RETURNING</literal> clause
+ in conjunction with a <literal>RETURNING</literal> clause
to generate keys in a single statement. It has a
required <literal>sequence</literal> element that
specifies the name of the sequence column.</para>
@@ -4124,10 +4124,10 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">postgresql-fetch-seq</emphasis>"
+ <emphasis role="bold">postgresql-fetch-seq</emphasis>:
\
(<literal>org.jboss.ejb.plugins.cmp.jdbc.keygen.JDBCPostgreSQLCreateCommand</literal>)
The <literal>JDBCPostgreSQLCreateCommand</literal> for
- PostgreSQL that fetches the currval of the sequence. The
+ PostgreSQL that fetches the current value of the sequence. \
The
optional <literal>sequence</literal> attribute can be
used to change the name of the sequence, with the
default being \
<literal>table_pkColumn_seq</literal>.</para> @@ -4567,7 +4567,7 @@
<para>
<emphasis role="bold">alter-column-template</emphasis>:
When <literal>alter-table</literal> is true, this SQL
- template specifies the syntax for droping a column to
+ template specifies the syntax for dropping a column to
from an existing table. The default value is
<literal>ALTER TABLE ?1 ALTER ?2 TYPE ?3</literal>.
The parameters are: </para>
@@ -4587,7 +4587,7 @@
<para>
<emphasis role="bold">drop-column-template</emphasis>:
When <literal>alter-table</literal> is true, this SQL
- template specifies the syntax for droping a column to
+ template specifies the syntax for dropping a column to
from an existing table. The default value is
<literal>ALTER TABLE ?1 DROP ?2</literal>. The
parameters are: </para>
@@ -4748,7 +4748,7 @@
<listitem>
<para>
<emphasis role="bold">result-reader</emphasis>: This
- option element specfies the fully qualified name of the
+ option element specifies the fully qualified name of the
<literal>JDBCResultSetReader</literal> implementation
for this mapping.</para>
</listitem>
@@ -4791,7 +4791,7 @@
Object toFieldValue(Object columnValue);
}</programlisting>
<para>A prototypical use case is the mapping of an integer type to
- its type-safe Java enum instance. The content model of the
+ its type-safe Java enumeration instance. The content model of the
<literal>user-type-mappings</literal> element consists of one or
more <literal>user-type-mapping</literal> elements, the content
model of which is shown in <xref \
linkend="ch11.usertype.fig"/>.</para> @@ -4839,7 +4839,7 @@
<listitem>
<para>
<emphasis role="bold">state-factory</emphasis>: This
- specfies class name of a state factory object which can
+ specifies class name of a state factory object which can
perform dirty checking for this field. State factory
classes must implement the
<literal>CMPFieldStateFactory</literal> interface. </para>
1.5 +1 -1 jboss-docs/adminguide/docbook/en/modules/chap5.xml
Index: chap5.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/chap5.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- chap5.xml 31 Dec 2004 08:43:23 -0000 1.4
+++ chap5.xml 31 Dec 2004 23:43:35 -0000 1.5
@@ -2694,7 +2694,7 @@
employs two types of locks to ensure data integrity and to
conform to the EJB spec.</para>
<itemizedlist>
- <lwistitem>
+ <listitem>
<para>
<emphasis role="bold">Method Lock</emphasis>: The method
lock ensures that only one thread of execution at a time
1.4 +27 -29 jboss-docs/adminguide/docbook/en/modules/chap6.xml
Index: chap6.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/chap6.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- chap6.xml 13 Dec 2004 05:19:10 -0000 1.3
+++ chap6.xml 31 Dec 2004 23:43:35 -0000 1.4
@@ -30,22 +30,20 @@
<itemizedlist>
<listitem>
<para>The location of the
- <literal>javax.jms.QueueConnectionFactory</literal> and
- <literal>javax.jms.TopicConnectionFactory</literal>. In
+ queue and topic connect factories: In
JBoss both connection factory implementations are located
under the JNDI name \
<literal>ConnectionFactory</literal>.</para> </listitem>
<listitem>
<para>How to lookup JMS destinations
- (<literal>javax.jmx.Queue</literal> and
- <literal>javax.jms.Topic</literal>). Destinations are
+ (queues and topics): Destinations are
configured via MBeans as we will see when we discuss the
messaging MBeans. JBoss comes with a few queues and topics
preconfigured. You can find them under the
<literal>jboss.mq.destination</literal> domain in the JMX \
Console..</para> </listitem>
<listitem>
- <para>Which JARS are required to us JMS. These include
+ <para>Which JARS JMS requires: These include
<literal>concurrent.jar</literal>,
<literal>jbossmq-client.jar</literal>,
<literal>jboss-common-client.jar</literal>,
@@ -65,7 +63,7 @@
not need to be listening to the queue at the time the message is
sent. <xref linkend="ch6.p2pjmsclient.ex"/> shows a complete P2P
example that sends a <literal>javax.jms.TextMessage</literal> to
- a the queue <literal>queue/testQueue</literal> and
+ the queue <literal>queue/testQueue</literal> and
asynchronously receives the message from the same queue.</para>
<example id="ch6.p2pjmsclient.ex">
<title>A P2P JMS client example</title>
@@ -94,7 +92,7 @@
* message from the same Queue.
*
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
*/
public class SendRecvClient
{
@@ -224,7 +222,7 @@
* Topic.
*
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
*/
public class TopicSendRecvClient
@@ -339,7 +337,7 @@
* A JMS client example program that sends a TextMessage to a Topic
*
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
*/
public class TopicSendClient
{
@@ -418,7 +416,7 @@
* A JMS client example program that synchronously receives a message a Topic
*
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
*/
public class TopicRecvClient
{
@@ -530,7 +528,7 @@
* A JMS client example program that synchronously receives a message a Topic
*
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
*/
public class DurableTopicRecvClient
{
@@ -703,7 +701,7 @@
* JMSReplyTo header.
*
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
*/
public class TextMDB
implements MessageDrivenBean, MessageListener
@@ -863,7 +861,7 @@
* TextMDB from Queue A.
*
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
*/
public class SendRecvClient
{
@@ -1086,7 +1084,7 @@
<listitem>
<para>
<emphasis role="bold">UIL2 IL</emphasis>: The Unified
- Invocation Layer version 2(UIL2) is the prefered
+ Invocation Layer version 2(UIL2) is the preferred
invocation layer for remote messaging. A multiplexing
layer is used to provide bidirectional communication.
The multiplexing layer creates two virtual sockets over
@@ -1247,7 +1245,7 @@
<emphasis
role="bold">deploy/hsqldb-jdbc-state-service.xml</emphasis>:
This configures the JDBC state service for storing state in
- the embeded Hypersonic database.</para>
+ the embedded Hypersonic database.</para>
</listitem>
<listitem>
<para>
@@ -1461,7 +1459,7 @@
<listitem>
<para>
<emphasis role="bold">ServerSocketFactory</emphasis>:
- The the <literal>javax.net.ServerSocketFactory</literal>
+ The <literal>javax.net.ServerSocketFactory</literal>
implementation class name to use to create the service
<literal>java.net.ServerSocket</literal>. If not
specified the default factory will be obtained from \
<literal>javax.net.ServerSocketFactory.getDefault()</literal>.</para> @@ -1546,13 \
+1544,13 @@ <para>
<emphasis
\
role="bold">org.jboss.mq.il.uil2.useServerHost</emphasis>:
- This system property allows a client to to connect
+ This system property allows a client to connect
to the server
<literal>InetAddress.getHostName</literal> rather
than
the<literal>InetAddress.getHostAddress</literal>
- value. This will only make a difference if there
- different address to name resolution between the
+ value. This will only make a difference if
+ name resolution differs between the
server and client environments.</para>
</listitem>
<listitem>
@@ -1575,7 +1573,7 @@
\
role="bold">org.jboss.mq.il.uil2.serverAddr</emphasis>:
This system property allows a client to override the
address to which it attempts to connect to. This is
- useful for networks where NAT is ocurring between
+ useful for networks where NAT is occcurring between
the client and JMS server.</para>
</listitem>
<listitem>
@@ -1584,7 +1582,7 @@
\
role="bold">org.jboss.mq.il.uil2.serverPort</emphasis>:
This system property allows a client to override the
port to which it attempts to connect. This is useful
- for for networks where port forwarding is ocurring
+ for networks where port forwarding is occurring
between the client and jms server.</para>
</listitem>
<listitem>
@@ -1595,7 +1593,7 @@
to retry connecting to the JMS server. Retries are
only made for
<literal>java.net.ConnectException</literal>
- failures. A value <= 0 means no retry atempts
+ failures. A value <= 0 means no retry attempts
will be made.</para>
</listitem>
<listitem>
@@ -1828,7 +1826,7 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">rcreate</emphasis>:
+ <emphasis role="bold">create</emphasis>:
The <literal>create</literal> attribute is a
true/false value that indicates whether the
role has the ability to create durable
@@ -1968,7 +1966,7 @@
<literal>DestinationManager</literal> provides
<literal>createQueue</literal> and
<literal>createTopic</literal> operations for this. Both methods
- have a one argument version which takes the destiniation name
+ have a one argument version which takes the destination name
and a two argument version which takes the destination and the
JNDI name of the destination. Queues and topics can be removed
using the <literal>destroyQueue</literal> and
@@ -2273,12 +2271,12 @@
<emphasis role="bold">MaxDepth</emphasis>: The
<literal>MaxDepth</literal> is an upper limit to the
backlog of messages that can exist for a
- destination, and if exceeded, attempts to add new
+ destination. If exceeded, attempts to add new
messages will result in a
\
<literal>org.jboss.mq.DestinationFullException</literal>.
The <literal>MaxDepth</literal> can still be
exceeded in a number of situations, e.g. when a
- message is knacked back into the queue. Also
+ message is placed back into the queue. Also
transactions performing read committed processing,
look at the current size of queue, ignoring any
messages that may be added as a result of the
@@ -2594,7 +2592,7 @@
<literal>JMSProviderAdapter</literal> instance into JNDI
under
<literal>java:/<ProviderName></literal>
- unless overriden by the
+ unless overridden by the
<literal>AdapterJNDIName</literal> attribute.</para>
</listitem>
<listitem>
@@ -2615,7 +2613,7 @@
<listitem>
<para>
<emphasis role="bold">AdapterJNDIName</emphasis>:
- Specify the exact name into JNDI uner which the
+ Specify the exact name into JNDI under which the
<literal>JMSProviderAdapter</literal> instance will be \
bound.</para> </listitem>
<listitem>
@@ -2672,7 +2670,7 @@
</MDBConfig>
</proxy-factory-config></programlisting>
</example>
- <para>Incidently, because one can specify multiple
+ <para>Incidentally, because one can specify multiple
<literal>invoker-proxy-binding</literal> elements, this allows
an MDB to listen to the same queue/topic on multiple servers by
configuring multiple bindings with different
1.4 +23 -23 jboss-docs/adminguide/docbook/en/modules/chap7.xml
Index: chap7.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/chap7.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- chap7.xml 14 Dec 2004 01:56:22 -0000 1.3
+++ chap7.xml 31 Dec 2004 23:43:35 -0000 1.4
@@ -68,7 +68,7 @@
server is extended to provide support for the JCA SPI to allow a
resource adaptor to integrate with the server connection pooling,
transaction management and security management facilities. This
- integration API defines a three part system contract.</para>
+ integration API defines a three-part system contract.</para>
<itemizedlist>
<listitem>
<para>
@@ -179,7 +179,7 @@
<literal>NoTxConnectionManager</literal>,
<literal>LocalTxConnectionManager</literal> and
<literal>XATxConnectionManager</literal>. These correspond to
- resource adapators that support no transactions, local
+ resource adaptors that support no transactions, local
transaction and XA transaction respectively. You choose which
subclass to use based on the type of transaction semantics you
want, provided the JCA resource adaptor supports the
@@ -267,8 +267,8 @@
where the
<literal><ra-display-name></literal> is
the <literal>ra.xml</literal> descriptor
- <literal>display-name</literal> attribute value. This is
- created by the <literal>RARDeployer</literal> when it
+ <literal>display-name</literal> attribute value. The \
<literal>RARDeployer</literal> + creates this when it
deploys a RAR file. This attribute will likely be
removed in the future.</para>
</listitem>
@@ -276,7 +276,7 @@
<para>
<emphasis
role="bold">ManagedConenctionFactoryProperties</emphasis>:
- This is a collection of (name, type, value) tripples
+ This is a collection of (name, type, value) triples
that define attributes of the
<literal>ManagedConnectionFactory</literal> instance.
Therefore, the names of the attributes depend on the
@@ -345,7 +345,7 @@
MBean that creates
\
<literal>javax.resource.spi.ManagedConnectionFactory</literal>
instances. Normally this is configured as an embedded
- mbean in a depends element rather than a separate MBean
+ MBean in a depends element rather than a separate MBean
reference using the <literal>RARDeployment</literal>
MBean. The MBean must provide an appropriate
<literal>startManagedConnectionFactory</literal>
@@ -369,7 +369,7 @@
<listitem>
<para>
<emphasis role="bold">BlockingTimeoutMillis</emphasis>:
- This attribute indicates the maximum time to blockwhile
+ This attribute indicates the maximum time to block while
waiting for a connection before throwing an exception.
Note that this blocks only while waiting for a permit
for a connection, and will never throw an exception if
@@ -389,10 +389,10 @@
Setting this to true doubles the available pools. One
pool is for connections used outside a transaction the
other inside a transaction. The actual pools are lazily
- constructed on first use. This is only relevent when
+ constructed on first use. This is only relevant when
setting the pool parameters associated with the
<literal>LocalTxConnectionManager</literal> and
- <literal>XATxConnectionManager</literal>. It's use case
+ <literal>XATxConnectionManager</literal>. Its use case
is for Oracle (and possibly other vendors) XA
implementations that don't like using an XA connection
with and without a JTA transaction.</para>
@@ -417,7 +417,7 @@
<listitem>
<para>
<emphasis role="bold">ByApplication</emphasis>:
- use app supplied params only</para>
+ use application supplied parameters only</para>
</listitem>
<listitem>
<para>
@@ -446,7 +446,7 @@
configured in the core <literal>jboss-service.xml</literal>
descriptor. It is used by
<literal>CachedConnectionInterceptor</literal>, JTA
- <literal>UserTransaction</literal> implementation, and all
+ <literal>UserTransaction</literal> implementation and all
<literal>BaseConnectionManager2</literal> instances. The
configurable attributes of the
<literal>CachedConnectionManager</literal> MBean are:</para>
@@ -457,7 +457,7 @@
this boolean attribute for spec compliant non-shareable
connections reconnect processing. This allows a
connection to be opened in one call and used in another.
- Note that specifying this behavior disables connecion
+ Note that specifying this behavior disables connection
close processing.</para>
</listitem>
<listitem>
@@ -498,7 +498,7 @@
for a non-transacted file system adaptor. The source to the
example adaptor can be found in the
<literal>src/main/org/jboss/chap7/ex1</literal> directory of the
- book examples. A class diagram that shows the the mapping from
+ book examples. A class diagram that shows the mapping from
the required <literal>javax.resource.spi</literal> interfaces to
the resource adaptor implementation is given in <xref \
linkend="ch7.fsrar.fig"/>.</para> <figure id="ch7.fsrar.fig">
@@ -612,7 +612,7 @@
lookup the connection factory instance from JNDI, here a
proprietary resource adaptor value,
\
<literal>org.jboss.chap7.ex1.ra.DirContextFactory</literal>.
- This value will be needed when we create the the JBoss
+ This value will be needed when we create the JBoss
<literal>ds.xml</literal> to use the resource. </para>
</listitem>
<listitem>
@@ -627,7 +627,7 @@
<para>
<emphasis role="bold">connection-interface</emphasis>:
This is the interface for the connections returned by
- the resource adpator connection factory, here the JNDI
+ the resource adaptor connection factory, here the JNDI
<literal>javax.naming.directory.DirContext</literal> \
interface.</para> </listitem>
<listitem>
@@ -711,7 +711,7 @@
</itemizedlist>
<para>To deploy the RAR and connection manager configuration to the
JBoss server, run the following:</para>
- <programlisting>[nr@toki examples]$ ant -Dchap=chap7 \
config</programlisting> + <programlisting>[examples]$ ant -Dchap=chap7 \
config</programlisting>
<para>The server console will display some logging output indicating
that the resource adaptor has been deployed. </para>
<para>Now we want to test access of the resource adaptor by a J2EE
@@ -722,7 +722,7 @@
creates a connection, and then immediately closes the
connection. The <literal>echo</literal> method code is shown \
below.</para> <example id="ch7.ssbechomethod.ex">
- <title>The stateless session bean echo method code which shows
+ <title>The stateless session bean echo method code that shows
the access of the resource adaptor connection factory.</title>
<programlisting>public String echo(String arg)
{
@@ -1015,7 +1015,7 @@
<literal>use-java-context</literal> is set to false.
<literal>DataSource</literal> wrappers are not usable
outside of the server VM, so they are normally bound under
- the <literal>java:/</literal> which isn't shared outside the
+ the <literal>java:/</literal>, which isn't shared outside the
local VM.</para>
</listitem>
<listitem>
@@ -1116,8 +1116,8 @@
<para>
<emphasis role="bold">check-valid-connection-sql</emphasis>:
A SQL statement that should be run on a connection before it
- is returned from the pool to test its validity. This allows
- for the dection of stale pool connections. An example
+ is returned from the pool to test its validity to test
+ for stale pool connections. An example
statement could be: <literal>select count(*) from \
x</literal>.</para> </listitem>
<listitem>
@@ -1173,7 +1173,7 @@
<emphasis
role="bold">prepared-statement-cache-size</emphasis>: This
element specifies the number of prepared statements per
- connection in an LRU cache which is keyed by the SQL query.
+ connection in an LRU cache, which is keyed by the SQL query.
Setting this to zero disables the cache.</para>
</listitem>
<listitem>
@@ -1251,8 +1251,8 @@
<emphasis role="bold">no-tx-separate-pools</emphasis>: The
presence of this element indicates that two connection pools
are required to isolate connections used with JTA
- transaction from thoses used without a JTA transaction. The
- pools are lazily constructed on first use. It's use case is
+ transaction from those used without a JTA transaction. The
+ pools are lazily constructed on first use. Its use case is
for Oracle (and possibly other vendors) XA implementations
that don't like using an XA connection with and without a
JTA transaction.</para>
1.5 +44 -44 jboss-docs/adminguide/docbook/en/modules/chap8.xml
Index: chap8.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/chap8.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- chap8.xml 28 Dec 2004 03:35:32 -0000 1.4
+++ chap8.xml 31 Dec 2004 23:43:35 -0000 1.5
@@ -15,7 +15,7 @@
subjects. The security proxy layer allows custom security that cannot be
described using the declarative model to be added to an EJB in a way
that is independent of the EJB business object. Before getting into the
- JBoss security implementation details, we will revie EJB and Servlet
+ JBoss security implementation details, we will review EJB and Servlet
specification security models as well as JAAS to establish the
foundation for these details.</para>
<section>
@@ -36,7 +36,7 @@
descriptors. You secure access to EJBs and web components in an
enterprise application by using the <literal>ejb-jar.xml</literal>
and <literal>web.xml</literal> deployment descriptors. We'll look at
- the the purpose and usage of the various security elements in the
+ the purpose and usage of the various security elements in the
following subsections.</para>
<section>
<title>Security References</title>
@@ -65,8 +65,8 @@
<xref linkend="ch8.ejbsecrole.fig"/> shows the use of
<literal>security-role-ref</literal> in an \
<literal>ejb-jar.xml</literal>.</para> <example id="ch8.ejbjarsec.ex">
- <title>An example ejb-jar.xml descriptor fragments which
- illustrate the security-role-ref element usage.</title>
+ <title>An example ejb-jar.xml descriptor fragment that
+ illustrates the security-role-ref element usage.</title>
<programlisting><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
<enterprise-beans>
@@ -86,7 +86,7 @@
<xref linkend="ch8.websecrole.fig"/> shows the use of
<literal>security-role-ref</literal> in a \
<literal>web.xml</literal>.</para> <example id="ch8.webxmlsec.ex">
- <title>An example web.xml descriptor fragments which illustrate
+ <title>An example web.xml descriptor fragment that illustrates
the security-role-ref element usage.</title>
<programlisting><web-app>
<servlet>
@@ -143,7 +143,7 @@
<literal>security-identity</literal> element usage is presented
in <xref linkend="ch8.ejbjarsecid.ex"/>.</para>
<example id="ch8.ejbjarsecid.ex">
- <title>An example ejb-jar.xml descriptor fragment which
+ <title>An example ejb-jar.xml descriptor fragment that
illustrates the security-identity element usage.</title>
<programlisting><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
@@ -213,8 +213,8 @@
<literal>security-role</literal> in an
<literal>ejb-jar.xml</literal> file. </para>
<example id="ch8.ejbsecrole.fig">
- <title>An example ejb-jar.xml descriptor fragments which
- illustrate the security-role element usage.</title>
+ <title>An example ejb-jar.xml descriptor fragment that
+ illustrates the security-role element usage.</title>
<programlisting><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
<!-- ... -->
@@ -231,7 +231,7 @@
<literal>security-role</literal> in an
<literal>web.xml</literal> file.</para>
<example id="ch8.websecrole.fig">
- <title>An example web.xml descriptor fragment which illustrate
+ <title>An example web.xml descriptor fragment that illustrates
the security-role element usage.</title>
<programlisting><!-- A sample web.xml fragment -->
<web-app>
@@ -330,7 +330,7 @@
<xref linkend="ch8.ejbjarmethodperm.ex"/> provides complete
examples of the <literal>method-permission</literal> element \
usage.</para> <example id="ch8.ejbjarmethodperm.ex">
- <title>An example ejb-jar.xml descriptor fragment which
+ <title>An example ejb-jar.xml descriptor fragment that
illustrates the method-permission element usage.</title>
<programlisting><ejb-jar>
<assembly-descriptor>
@@ -434,7 +434,7 @@
the data sent between the client and server be sent in such a
way that it can't be changed in transit. A value of
<literal>CONFIDENTIAL</literal> means that the application
- requires the data be transmitted in a fashion that prevents
+ requires the data to be transmitted in a fashion that prevents
other entities from observing the contents of the transmission.
In most cases, the presence of the <literal>INTEGRAL</literal>
or <literal>CONFIDENTIAL</literal> flag indicates that the use
@@ -612,7 +612,7 @@
with a subject, two methods are available:</para>
<programlisting>public Set getPrincipals() {...}
public Set getPrincipals(Class c) {...} </programlisting>
- <para>The first method returns all princiaps contained in
+ <para>The first method returns all principals contained in
the subject. The second method only returns those
principals that are instances of class
<literal>c</literal> or one of its subclasses. An empty
@@ -1046,7 +1046,7 @@
<para>The <literal>unauthenticated-principal</literal> element
specifies the name to use for the <literal>Principal</literal>
object returned by the
- <literal>EJBContext.getUserPrincpal</literal> method when an
+ <literal>EJBContext.getUserPrincipal</literal> method when an
unauthenticated user invokes an EJB. Note that this conveys no
special permissions to an unauthenticated caller. Its primary
purpose is to allow unsecured servlets and JSP pages to invoke
@@ -1099,7 +1099,7 @@
/** A simple example of a custom SecurityProxy implementation
* that demonstrates method argument based security checks.
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.4 $
+ * @version $Revision: 1.5 $
*/
public class EchoSecurityProxy implements SecurityProxy
{
@@ -1171,7 +1171,7 @@
installs the <literal>EchoSecurityProxy</literal> as the custom
proxy for the <literal>EchoBean</literal> is given in <xref \
linkend="ch8.echo1dd.ex"/>.</para> <example id="ch8.echo1dd.ex">
- <title>The jboss.xml descriptor which configures the
+ <title>The jboss.xml descriptor, which configures the
EchoSecurityProxy as the custom security proxy for the \
EchoBean.</title> <programlisting><jboss>
<security-domain>java:/jaas/other</security-domain>
@@ -1740,7 +1740,7 @@
<literal>{CLASS}classname[:ctorarg]</literal>
where the <literal>[:ctorarg]</literal> is an
optional string that will be passed to the
- constructor when instantiating the the
+ constructor when instantiating the
<literal>classname</literal>. The password is
obtained from classname by invoking a
<literal>toCharArray()</literal> method if
@@ -1994,7 +1994,7 @@
together in a stack at runtime. This allows one to push a login
configuration onto the stack and latter pop it. This is a
feature used by the security unit tests to install custom login
- configurations into a default JBoss installation. Pusing a new
+ configurations into a default JBoss installation. Pushing a new
configuration is done using:</para>
<programlisting>public void pushLoginConfig(String objectName) throws
JMException, MalformedObjectNameException;</programlisting>
@@ -2018,7 +2018,7 @@
includes standard base class implementations that help enforce
the expected <literal>LoginModule</literal> to
<literal>Subject</literal> usage pattern that was described in
- the<xref linkend="ch8.custom.sect"/>. These implementations
+ <xref linkend="ch8.custom.sect"/>. These implementations
allow for easy integration of your own authentication protocol,
if none of the bundled login modules prove suitable. In this
section we will first describe the useful bundled login modules
@@ -2297,7 +2297,7 @@
<para>
<emphasis role="bold">principalDNSuffix</emphasis>:
A suffix to add to the username when forming the
- user distiguished name. This is useful if you prompt
+ user distinguished name. This is useful if you prompt
a user for a username and you don't want the user to
have to enter the fully distinguished name. Using
this property and
@@ -2366,7 +2366,7 @@
<emphasis
role="bold">roleNameAttributeID</emphasis>: The name
of the attribute of the in the context pointed to by
- the <literal>roleCtxDN</literal> distiguished name
+ the <literal>roleCtxDN</literal> distinguished name
value which contains the role name. If the
<literal>roleAttributeIsDN</literal> property is set
to true, this property is used to find the role
@@ -2427,7 +2427,7 @@
passed to the LDAP server. An empty password is
treated as an anonymous login by some LDAP servers
and this may not be a desirable feature. Set this to
- false to reject empty passwords, true to have the
+ false to reject empty passwords or true to have the
LDAP server validate the empty password. The default
is true.</para>
</listitem>
@@ -2571,7 +2571,7 @@
identity and authentication services but is unable to use
the authorization services. This is because application
roles don't always map well onto LDAP groups, and LDAP
- administrators are often hesistant to allow external
+ administrators are often hesitant to allow external
application-specific data in central LDAP servers. For this
reason, the LDAP authentication module is often paired with
another login module, such as the database login module,
@@ -2716,7 +2716,7 @@
option that specifies a <literal>Principal</literal>
implementation class. This must support a
constructor taking a string argument for the
- princpal name.</para>
+ principal name.</para>
</listitem>
</itemizedlist>
<para>As an example <literal>DatabaseServerLoginModule</literal>
@@ -2743,7 +2743,7 @@
<section>
<title>BaseCertLoginModule</title>
<para> This is a login module which authenticates users based on
- X509 certificates. A typical usecase for this login module
+ X509 certificates. A typical use case for this login module
is <literal>CLIENT-CERT</literal> authentication in the web
tier. This login module only performs authentication. You
need to combine it with another login module capable of
@@ -3172,7 +3172,7 @@
*/
abstract protected Group[] getRoleSets() throws LoginException;
}</programlisting>
- <para>You'll need to to pay attention to the
+ <para>You'll need to pay attention to the
<literal>loginOk</literal> instance variable. This must be
set to true if the login succeeds, false otherwise by any
subclasses that override the login method. Failure to set
@@ -3294,7 +3294,7 @@
<literal>UsernamePasswordLoginModule</literal>, otherwise
subclass <literal>AbstractServerLoginModule</literal>.</para>
<para>The steps you are required to perform when writing a
- custom login module are summerized in the following
+ custom login module are summarized in the following
depending on which base login module class you choose. When
writing a custom login module that integrates with your
security infrastructure, you should start by subclassing
@@ -3386,7 +3386,7 @@
of the form
<literal>password/<username></literal> where
<literal><username></literal> is the current
- user being authenticated. Similary, a lookup of the form
+ user being authenticated. Similarly, a lookup of the form
<literal>roles/<username></literal> returns
the requested user's roles.</para>
<para>The source code for the example is located in the
@@ -3420,7 +3420,7 @@
* for a user from a JNDI lookup.
*
* @author Scott.Stark@jboss.org
- * @version $Revision: 1.4 $
+ * @version $Revision: 1.5 $
*/
public class JndiUserAndPass
extends UsernamePasswordLoginModule
@@ -3584,7 +3584,7 @@
authentication caches when the service is stopped.</para>
</listitem>
</itemizedlist>
- <para> Here is an examble MBean definition using the
+ <para> Here is an example MBean definition using the
<literal>DynamicLoginConfig</literal> service. </para>
<programlisting><server>
<mbean code="org.jboss.security.auth.login.DynamicLoginConfig" \
name="..."> @@ -3607,7 +3607,7 @@
<para>This will load the specified <literal>AuthConfig</literal>
resource using the specified
<literal>LoginConfigService</literal> MBean by invoking
- <literal>loadConfig</literal> with the apropriate resource URL.
+ <literal>loadConfig</literal> with the appropriate resource URL.
When the service is stopped the configurations are removed. The
resource specified may be either an XML file, or a Sun JAAS
login configuration.</para>
@@ -3750,9 +3750,9 @@
</itemizedlist>
<para>Any other options passed in that do not match one of the previous
named options is treated as a JNDI property to use for the
- environment passed to the <literal>IntialContext</literal>
+ environment passed to the <literal>InitialContext</literal>
constructor. This is useful if the SRP server interface is not
- available from the default <literal>IntialContext</literal>.</para>
+ available from the default <literal>InitialContext</literal>.</para>
<para>The <literal>SRPLoginModule</literal> needs to be configured along
with the standard <literal>ClientLoginModule</literal> to allow the
SRP authentication credentials to be used for validation of access
@@ -3842,7 +3842,7 @@
<listitem>
<para>
<emphasis role="bold">RequireAuxChallenge</emphasis>: Set if
- the client must supply an auxillary challenge as part of the
+ the client must supply an auxiliary challenge as part of the
verify phase. This gives control over whether the
<literal>SRPLoginModule</literal> configuration used by the
client must have the <literal>useAuxChallenge</literal>
@@ -3856,7 +3856,7 @@
behavior of the server SRP session cache when clients have
not enabled the multiple session per user mode. The default
is false meaning that the second attempt by a user to
- authentication will succeeed, but the resulting SRP session
+ authentication will succeed, but the resulting SRP session
will not overwrite the previous SRP session state.</para>
</listitem>
</itemizedlist>
@@ -3948,10 +3948,10 @@
throws IOException;
/**
- * Verify an optional auxillary challenge sent from the client to
+ * Verify an optional auxiliary challenge sent from the client to
* the server. The auxChallenge object will have been decrypted
* if it was sent encrypted from the client. An example of a
- * auxillary challenge would be the validation of a hardware token
+ * auxiliary challenge would be the validation of a hardware token
* (SafeWord, SecureID, iButton) that the server validates to
* further strengthen the SRP password exchange.
*/
@@ -4025,10 +4025,10 @@
the creation of a hashed version of the password
information. If your passwords are already store in an
irreversible hashed form, then this can only be done on a
- per-user basis as part of an upgrade proceedure for example.
+ per-user basis as part of an upgrade procedure for example.
Note that the <literal>setUserVerifier(String,
VerifierInfo)</literal> method is not used by the current
- SRPSerivce and may be implemented as noop method, or even
+ SRPSerivce and may be implemented as no-op method, or even
one that throws an exception stating that the store is \
read-only.</para> <para>Step 2 is the creation of the custom
<literal>SRPVerifierStore</literal> interface implementation
@@ -4124,7 +4124,7 @@
by invoking the
<literal>SRPClientSession.verify</literal> method. If
this succeeds, mutual authentication of the client to
- server, and server to client have been completed.The
+ server, and server to client have been completed. The
client side <literal>SRPLoginModule</literal> next
creates a challenge <literal>M1</literal> to the server
by invoking <literal>SRPClientSession.response</literal>
@@ -4226,7 +4226,7 @@
example demonstrates client side authentication of the user
via SRP as well as subsequent secured access to a simple EJB
using the SRP session challenge as the user credential. The
- test code deploys an EJB JAR that includes a sar for the
+ test code deploys an EJB JAR that includes a SAR for the
configuration of the server side login module configuration
and SRP services. As in the previous examples we will
dynamically install the server side login module
@@ -4585,7 +4585,7 @@
<para>Listing the
<literal>src/main/org/jboss/chap8/chap8.keystore</literal> examples
file contents using the keytool shows one self-signed \
certificate:</para>
- <programlisting>[nr@toki examples]$ keytool -list -v -keystore \
src/main/org/jboss/chap8/chap8.keystore + <programlisting>[examples]$ keytool \
-list -v -keystore src/main/org/jboss/chap8/chap8.keystore Enter keystore password: \
rmi+ssl
Keystore type: jks
@@ -4647,7 +4647,7 @@
<literal>TrustManagerFactory</literal> access. It extends the basic
security manager to allow support for SSL and other cryptographic
operations that require security keys. This configuration simply
- loads the chap8.keystore from the example 4 MBean sar using the
+ loads the chap8.keystore from the example 4 MBean SAR using the
indicated password.</para>
<para>The second step is to define an EJB invoker configuration that
uses the JBossSX RMI socket factories that support SSL. To do this
@@ -4980,7 +4980,7 @@
represent invocations that should be dispatched onto the
<literal>MBeanServer</literal>. Effectively this allows access
to MBeans that support the detached invoker operation via HTTP
- since one could figure out how to format an approriate HTTP
+ since one could figure out how to format an appropriate HTTP
post. To security this access point you would need to secure the
<literal>JMXInvokerServlet</literal> servlet found in the
<literal>http-invoker.sar/invoker.war/WEB-INF/web.xml</literal>
@@ -5002,7 +5002,7 @@
section. In the future this service will be deployed as an
XMBean with a security interceptor that supports role based
access checks. If your so inclined this is a configuration that
- can setup today following the proceedure demonstrated in XMBean
+ can setup today following the procedure demonstrated in XMBean
example: <xref linkend="ch2.jndimapv3.sect"/>.</para>
</section>
</section>
1.5 +1 -1 jboss-docs/adminguide/docbook/en/modules/chap9.xml
Index: chap9.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/chap9.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- chap9.xml 31 Dec 2004 08:43:23 -0000 1.4
+++ chap9.xml 31 Dec 2004 23:43:35 -0000 1.5
@@ -47,7 +47,7 @@
<listitem>
<para>
<emphasis role="bold">LenientEjbLink</emphasis>: This flag \
indicates that
- <literal>ejb-link</literal> errors should be ignored in favour \
of trying the + <literal>ejb-link</literal> errors should be \
ignored in favor of trying the
<literal>jndi-name</literal> in the \
<literal>jboss-web.xml</literal>. The default is true.</para>
</listitem>
1.2 +586 -381 jboss-docs/adminguide/docbook/en/modules/jbossaop.xml
Index: jbossaop.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/adminguide/docbook/en/modules/jbossaop.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- jbossaop.xml 23 Dec 2004 19:52:29 -0000 1.1
+++ jbossaop.xml 31 Dec 2004 23:43:35 -0000 1.2
@@ -1,45 +1,78 @@
<?xml version='1.0' encoding="iso-8859-1"?>
<chapter id="aop.chapt">
-
- <title>Aspect Oriented Programming (AOP) Support</title>
- <subtitle>JBoss AOP delivers EJB-style services to plain Java objects</subtitle>
-
- <para>Support for Aspect-Oriented middleware is a key innovation in JBoss \
application server 4.0. It drastically simplifies the development of enterprise \
middleware applications. In this chapter, we first introduce the basic concepts of \
Aspect Oriented Programming (AOP). Then, we discuss how to configure AOP support \
inside the JBoss application server and how to deploy AOP-enabled applications in \
various scenarios.</para>
-
- <section id="aop-why">
- <title>Why AOP</title>
-
- <para>AOP extends the traditional Object Oriented Programming (OOP) model to \
improve code reuse across different object hierarchies. The basic concept in AOP is \
an aspect, which is a common behavior that's typically scattered across methods, \
classes, object hierarchies, or even entire object models. For example, metrics is \
one common aspect. To generate useful logs from your application, you have to \
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 an orthogonal behavior that \
requires duplicated code in traditional OOP systems.</para>
-
- <para>In AOP, a feature like metrics is called a crosscutting concern, 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 into aspects.</para>
-
- <para>In the context of enterprise middleware, container managed services are \
crosscutting concerns. Once deployed, each J2EE component (e.g., a EJB or a servlet) \
automatically gets services, such as logging, security and transaction, from the \
container. Those services are orthogonal to the core business logic. The application \
developers could reuse those services without writing any code. The J2EE services \
have the basic characteristics of "aspects" as we discussed before. However, compared \
with a true AOP solution, the J2EE services model has a number of \
limitations.</para>
-
- <itemizedlist>
- <listitem>The J2EE component classes must implement certain base classes or \
interfaces in the J2EE framework. It is impossible for components to inherit from \
each other. That makes it difficult to build a complex OOP system based on those \
components.</listitem>
-
- <listitem>The J2EE infrastructure code and deployment descriptors are \
complex. They are designed for fully distributed services and prove to be an overkill \
for many smaller scale middleware applications.</listitem>
-
- <listitem>You cannot extend the J2EE container for more services that are \
not shipped with the application server.</listitem>
-
- <listitem>You cannot use J2EE services in standalone applications without \
the J2EE application server.</listitem>
- </itemizedlist>
-
- <para>JBoss AOP helps you solve all the above problems. It works with plain \
old Java objects (POJOs) as opposed to pre-defined "components". JBoss AOP allows you \
to apply EJB-style services to POJOs without the complex EJB infrastructure code and \
deployment descriptors. You can develop new aspects and deploy them into the \
application server for all applications to use. That essentially extends the existing \
container services. JBoss AOP can also be used in standalone Java applications. A \
detailed introduction to aspect-oriented programming and the JBoss AOP framework can \
be found on JBoss web site.</para>
-
- </section>
-
- <section id="aop-intro">
- <title>AOP Basic Concepts</title>
-
- <para>In this section, let's first introduce some basic AOP concepts via some \
examples. These concepts and terms will be used frequently throughout the rest of \
this chapter.</para>
-
- <section id="aop-intro-join">
- <title>Joinpoint and Invocation</title>
-
- <para>A joinpoint is simply any point in your java program. The call of a \
method. The execution of a constructor, the access of a field are all joinpoints. The \
joinpoints are places where the aspects provide services to the object. Let's see an \
example POJO <literal>Foo</literal>.</para>
-
- <programlisting>
+ <title>Aspect Oriented Programming (AOP) Support</title>
+ <subtitle>JBoss AOP delivers EJB-style services to plain Java \
objects</subtitle> + <para>Support for Aspect-Oriented middleware is a key \
innovation in JBoss + application server 4.0. It drastically simplifies the \
development of + enterprise middleware applications. In this chapter, we \
first introduce + the basic concepts of Aspect Oriented Programming (AOP). \
Then, we + discuss how to configure AOP support inside the JBoss application \
server + and how to deploy AOP-enabled applications in various \
scenarios.</para> + <section id="aop-why">
+ <title>Why AOP</title>
+ <para>AOP extends the traditional Object Oriented Programming (OOP)
+ model to improve code reuse across different object hierarchies. The
+ basic concept in AOP is an aspect, which is a common behavior that's
+ typically scattered across methods, classes, object hierarchies, or
+ even entire object models. For example, metrics is one common
+ aspect. To generate useful logs from your application, you have to
+ 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 an orthogonal behavior that
+ requires duplicated code in traditional OOP systems.</para>
+ <para>In AOP, a feature like metrics is called a crosscutting concern,
+ 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 into aspects.</para>
+ <para>In the context of enterprise middleware, container managed
+ services are crosscutting concerns. Once deployed, each J2EE
+ component (e.g., a EJB or a servlet) automatically gets services,
+ such as logging, security and transaction, from the container. Those
+ services are orthogonal to the core business logic. The application
+ developers could reuse those services without writing any code. The
+ J2EE services have the basic characteristics of "aspects" as we
+ discussed before. However, compared with a true AOP solution, the
+ J2EE services model has a number of limitations.</para>
+ <itemizedlist>
+ <listitem><para>The J2EE component classes must implement certain base
+ classes or interfaces in the J2EE framework. It is impossible
+ for components to inherit from each other. That makes it
+ difficult to build a complex OOP system based on those \
components.</para></listitem> + <listitem><para>The J2EE infrastructure \
code and deployment descriptors + are complex. They are designed for \
fully distributed services + and prove to be an overkill for many \
smaller scale middleware applications.</para></listitem> + \
<listitem><para>You cannot extend the J2EE container for more services + \
that are not shipped with the application server.</para></listitem> + \
<listitem><para>You cannot use J2EE services in standalone applications + \
without the J2EE application server.</para></listitem> + </itemizedlist>
+ <para>JBoss AOP helps you solve all the above problems. It works with
+ plain old Java objects (POJOs) as opposed to pre-defined
+ "components". JBoss AOP allows you to apply EJB-style services to
+ POJOs without the complex EJB infrastructure code and deployment
+ descriptors. You can develop new aspects and deploy them into the
+ application server for all applications to use. That essentially
+ extends the existing container services. JBoss AOP can also be used
+ in standalone Java applications. A detailed introduction to
+ aspect-oriented programming and the JBoss AOP framework can be found
+ on JBoss web site.</para>
+ </section>
+ <section id="aop-intro">
+ <title>AOP Basic Concepts</title>
+ <para>In this section, let's first introduce some basic AOP concepts via
+ some examples. These concepts and terms will be used frequently
+ throughout the rest of this chapter.</para>
+ <section id="aop-intro-join">
+ <title>Joinpoint and Invocation</title>
+ <para>A joinpoint is simply any point in your java program. The call
+ of a method. The execution of a constructor, the access of a
+ field are all joinpoints. The joinpoints are places where the
+ aspects provide services to the object. Let's see an example
+ POJO <literal>Foo</literal>.</para>
+ <programlisting>
<![CDATA[
public class Foo {
public int fooField;
@@ -54,26 +87,39 @@
}
]]>
</programlisting>
-
- <para>All the following actions on the <literal>Foo</literal> class and its \
instance objects are jointpoints.</para>
-
- <programlisting>
+ <para>All the following actions on the <literal>Foo</literal> class
+ and its instance objects are joinpoints.</para>
+ <programlisting>
<![CDATA[
Foo foo = new Foo ();
int k = foo.fooField;
String s = foo.fooMethod (0);
]]>
</programlisting>
-
- <para>Inside the JBoss AOP, a joinpiont is encapsulated by an \
<literal>Invocation</literal> object at runtime. This object could contain \
information like which method is being called, the arguments of the method, etc. It \
is available to developers via the JBoss AOP framework API.</para>
- </section>
-
- <section id="aop-intro-advice">
- <title>Advice and Aspect</title>
-
- <para>The AOP system dynamically modifies an object's behavior at \
joinpoints. The injected behavior, such as logging, security check, transaction etc., \
is specified in regular Java methods known as "advices". In the following example, \
the <literal>trace()</literal> method is an advice. When the execution flow reaches a \
joinpoint that is bound to the <literal>trace()</literal> advice (we will see how to \
specify the binding later), the JVM executes the <literal>trace()</literal> method \
instead of the joinpoint. Here, the <literal>trace()</literal> method prints out a \
message, instructs the AOP runtime to execute the joinpoint and then prints another \
message. The <literal>invocation</literal> object contains information about the \
joinpoint where this advice is applied. We can apply the advice to any joinpoint to \
log an event.</para>
-
- <programlisting>
+ <para>Inside the JBoss AOP, a joinpiont is encapsulated by an
+ <literal>Invocation</literal> object at runtime. This object
+ could contain information like which method is being called, the
+ arguments of the method, etc. It is available to developers via
+ the JBoss AOP framework API.</para>
+ </section>
+ <section id="aop-intro-advice">
+ <title>Advice and Aspect</title>
+ <para>The AOP system dynamically modifies an object's behavior at
+ joinpoints. The injected behavior, such as logging, security
+ check, transaction etc., is specified in regular Java methods
+ known as "advices". In the following example, the
+ <literal>trace()</literal> method is an advice. When the
+ execution flow reaches a joinpoint that is bound to the
+ <literal>trace()</literal> advice (we will see how to specify
+ the binding later), the JVM executes the
+ <literal>trace()</literal> method instead of the joinpoint.
+ Here, the <literal>trace()</literal> method prints out a
+ message, instructs the AOP runtime to execute the joinpoint and
+ then prints another message. The <literal>invocation</literal>
+ object contains information about the joinpoint where this
+ advice is applied. We can apply the advice to any joinpoint to
+ log an event.</para>
+ <programlisting>
<![CDATA[
public class FooAspect {
@@ -89,22 +135,28 @@
}
]]>
</programlisting>
-
- <para>In JBoss AOP, an Aspect class is a regular Java class that holds one \
or many advice methods. For example, the <literal>FooAspect</literal> class is an \
aspect. A special kind of aspect class in JBoss AOP is "interceptor". It must \
implement the <literal>Interceptor</literal> interface, which defines only one advice \
method <literal>invoke()</literal>. This interface helps developers to enforce \
compile time type check for the interceptor type of aspect \
classes.</para>
-
- </section>
-
- <section id="aop-intro-pointcut">
- <title>Pointcut</title>
-
- <para>The advice is bound to a specific set of joinpoints known as a \
pointcut. As a developer, you specify the mapping rules to group jointpoints into \
pointcuts using an expression language supported by JBoss AOP. There are three ways \
to specify the pointcut.</para>
-
- <section id="aop-intro-pointcut-xml">
- <title>Use XML configuration file</title>
-
- <para>The following listing from the <literal>jboss-aop.xml</literal> \
descriptor specifies that the <literal>trace()</literal> advice is bound to the \
<literal>Foo.fooMethod()</literal> method call joinpoint.</para>
-
- <programlisting>
+ <para>In JBoss AOP, an Aspect class is a regular Java class that
+ holds one or many advice methods. For example, the
+ <literal>FooAspect</literal> class is an aspect. A special kind
+ of aspect class in JBoss AOP is "interceptor". It must implement
+ the <literal>Interceptor</literal> interface, which defines only
+ one advice method <literal>invoke()</literal>. This interface
+ helps developers to enforce compile time type check for the
+ interceptor type of aspect classes.</para>
+ </section>
+ <section id="aop-intro-pointcut">
+ <title>Pointcut</title>
+ <para>The advice is bound to a specific set of joinpoints known as a
+ pointcut. As a developer, you specify the mapping rules to group
+ joinpoints into pointcuts using an expression language
+ supported by JBoss AOP. There are three ways to specify the \
pointcut.</para> + <section id="aop-intro-pointcut-xml">
+ <title>Use XML configuration file</title>
+ <para>The following listing from the
+ <literal>jboss-aop.xml</literal> descriptor specifies that
+ the <literal>trace()</literal> advice is bound to the
+ <literal>Foo.fooMethod()</literal> method call \
joinpoint.</para> + <programlisting>
<![CDATA[
<aop>
<aspect class="FooAspect" scope="PER_VM"/>
@@ -115,17 +167,19 @@
</aop>
]]>
</programlisting>
-
- <para>You can find a complete reference of the elements in the \
<literal>jboss-aop.xml</literal> file in the JBoss AOP manual.</para>
-
- </section>
-
- <section id="aop-intro-pointcut-anno">
- <title>Use annotations</title>
-
- <para>If you do not wish to manage a separate \
<literal>jboss-aop.xml</literal> configuration file, you can declare the aspect and \
specify its bindings in the aspect class's source code using annotations. In JDK 5.0, \
annotation is an officially supported Java language feature. You can just use JBoss \
AOP defined annotations to tag your aspect class and advice \
methods.</para>
-
- <programlisting>
+ <para>You can find a complete reference of the elements in the
+ <literal>jboss-aop.xml</literal> file in the JBoss AOP \
manual.</para> + </section>
+ <section id="aop-intro-pointcut-anno">
+ <title>Use annotations</title>
+ <para>If you do not wish to manage a separate
+ <literal>jboss-aop.xml</literal> configuration file, you can
+ declare the aspect and specify its bindings in the aspect
+ class's source code using annotations. In JDK 5.0,
+ annotation is an officially supported Java language feature.
+ You can just use JBoss AOP defined annotations to tag your
+ aspect class and advice methods.</para>
+ <programlisting>
<![CDATA[
@Aspect (scope = Scope.PER_VM)
public class FooAspect {
@@ -143,10 +197,14 @@
}
]]>
</programlisting>
-
- <para>In JDK 1.4, however, annotation is not supported by the Java \
compiler. JBoss AOP allows you to embed the annotations in Java doclet comments. You \
can use the JBoss annotation compiler (see <xref linkend=""/>) to extract the \
annotation from the source code and then add them to the compiled bytecode files or \
store them in a separate XML file for further processing.</para>
-
- <programlisting>
+ <para>In JDK 1.4, however, annotation is not supported by the
+ Java compiler. JBoss AOP allows you to embed the annotations
+ in JavaDoc comments. You can use the JBoss annotation
+ compiler <!--(see <xref linkend=""/>)--> to extract the \
annotation + from the source code and then add them to the \
compiled + bytecode files or store them in a separate XML file \
for + further processing.</para>
+ <programlisting>
<![CDATA[
/**
* @@Aspect (scope = Scope.PER_VM)
@@ -168,17 +226,23 @@
}
]]>
</programlisting>
-
- <para>Annotation is easier to use than the \
<literal>jboss-aop.xml</literal> configuration file since it is closer to the source \
code it is supposed to control.</para>
-
- </section>
-
- <section id="aop-intro-pointcut-anno2">
- <title>Use Annotation in Application Classes</title>
-
- <para>So far, you have seen how to bind advices to pointcuts using the \
signature pattern of the joinpoints (e.g., the method signature). A more general way \
to specify pointcuts is to directly tag the joinpoints in the application code using \
annotations. Then, in the <literal>jboss-aop.xml</literal> file, you can map the \
annotations to the advices. In the following <literal>jboss-aop.xml</literal> file, \
the <literal>trace()</literal> advice is mapped to the <literal>@FooTrace</literal> \
annotation tag.</para>
-
- <programlisting>
+ <para>Annotation is easier to use than the
+ <literal>jboss-aop.xml</literal> configuration file since it
+ is closer to the source code it is supposed to control.</para>
+ </section>
+ <section id="aop-intro-pointcut-anno2">
+ <title>Use Annotation in Application Classes</title>
+ <para>So far, you have seen how to bind advices to pointcuts
+ using the signature pattern of the joinpoints (e.g., the
+ method signature). A more general way to specify pointcuts
+ is to directly tag the joinpoints in the application code
+ using annotations. Then, in the
+ <literal>jboss-aop.xml</literal> file, you can map the
+ annotations to the advices. In the following
+ <literal>jboss-aop.xml</literal> file, the
+ <literal>trace()</literal> advice is mapped to the
+ <literal>@FooTrace</literal> annotation tag.</para>
+ <programlisting>
<![CDATA[
<aop>
<aspect class="FooAspect" scope="PER_VM"/>
@@ -189,10 +253,9 @@
</aop>
]]>
</programlisting>
-
- <para>Here is the application code that makes use of the \
<literal>@FooTrace</literal> annotation in JDK 5.0.</para>
-
- <programlisting>
+ <para>Here is the application code that makes use of the
+ <literal>@FooTrace</literal> annotation in JDK 5.0.</para>
+ <programlisting>
<![CDATA[
public class Foo {
public int fooField;
@@ -207,10 +270,9 @@
}
]]>
</programlisting>
-
- <para>The version in JDK 1.4 with the JBoss annotation compiler is as \
follows.</para>
-
- <programlisting>
+ <para>The version in JDK 1.4 with the JBoss annotation compiler
+ is as follows.</para>
+ <programlisting>
<![CDATA[
public class Foo {
public int fooField;
@@ -228,29 +290,39 @@
}
]]>
</programlisting>
-
- <para>Notice that you do not need to annotate the aspect class anymore in \
this setup. The ability to specify pointcuts via annotations in the application code \
allows us to develop pre-packaged aspects and then publish the annotation API for all \
to use. That is exactly what JBoss did to support pre-packaged EJB-style AOP services \
inside the JBoss application server (see <xref linkend=""/>).</para>
-
- </section>
-
- </section>
-
- <section id="aop-intro-mixin">
- <title>Introduction and Mixin</title>
-
- <para>The aspects you have seen so far are "interceptor" type aspects. \
Another key AOP feature is "introduction" or "mixin" of classes from independent \
inheritance trees. An introduction modifies the type and structure of a Java class. \
It can be used to force an existing class to implement an interface using methods \
from another class. It essentially allows developers to create C++ style multiple \
inheritance object systems in Java. The following example shows that the methods in \
<literal>FooMixin</literal> class is used to make <literal>Foo</literal> class to \
implement the <literal>FooMixinInt</literal> interface at runtime. Here is the \
<literal>FooMixinInt</literal> interface.</para>
-
- <programlisting>
+ <para>Notice that you do not need to annotate the aspect class
+ anymore in this setup. The ability to specify pointcuts via
+ annotations in the application code allows us to develop
+ pre-packaged aspects and then publish the annotation API for
+ all to use. That is exactly what JBoss did to support
+ pre-packaged EJB-style AOP services inside the JBoss
+ application server. <!-- (see <xref linkend=""/>)--></para>
+ </section>
+ </section>
+ <section id="aop-intro-mixin">
+ <title>Introduction and Mixin</title>
+ <para>The aspects you have seen so far are "interceptor" type
+ aspects. Another key AOP feature is "introduction" or "mixin" of
+ classes from independent inheritance trees. An introduction
+ modifies the type and structure of a Java class. It can be used
+ to force an existing class to implement an interface using
+ methods from another class. It essentially allows developers to
+ create C++ style multiple inheritance object systems in Java.
+ The following example shows that the methods in
+ <literal>FooMixin</literal> class is used to make
+ <literal>Foo</literal> class to implement the
+ <literal>FooMixinInt</literal> interface at runtime. Here is the
+ <literal>FooMixinInt</literal> interface.</para>
+ <programlisting>
<![CDATA[
public interface FooMixinInt {
public String fooMethod2 (int i);
}
]]>
</programlisting>
-
- <para>The <literal>FooMixin</literal> class implements the \
<literal>FooMixinInt</literal> interface.</para>
-
- <programlisting>
+ <para>The <literal>FooMixin</literal> class implements the
+ <literal>FooMixinInt</literal> interface.</para>
+ <programlisting>
<![CDATA[
public class FooMixin implements FooMixinInt {
@@ -261,10 +333,13 @@
}
]]>
</programlisting>
-
- <para>However, the <literal>Foo</literal> class does not implement the \
<literal>FooMixinInt</literal> interface. The following \
<literal>jboss-aop.xml</literal> file forces the <literal>Foo</literal> class to \
implement the <literal>FooMixinInt</literal> using the method from the \
<literal>FooMixin</literal> class.</para>
-
- <programlisting>
+ <para>However, the <literal>Foo</literal> class does not implement
+ the <literal>FooMixinInt</literal> interface. The following
+ <literal>jboss-aop.xml</literal> file forces the
+ <literal>Foo</literal> class to implement the
+ <literal>FooMixinInt</literal> using the method from the
+ <literal>FooMixin</literal> class.</para>
+ <programlisting>
<![CDATA[
<introduction class="Foo">
<mixin>
@@ -275,56 +350,71 @@
</introduction>
]]>
</programlisting>
-
- <para>Then, in the application code, you can cast a <literal>Foo</literal> \
instance to the <literal>FooMixinInt</literal> type at \
runtime.</para>
-
- <programlisting>
+ <para>Then, in the application code, you can cast a
+ <literal>Foo</literal> instance to the
+ <literal>FooMixinInt</literal> type at runtime.</para>
+ <programlisting>
<![CDATA[
Foo foo = new Foo ();
FooMixinInt fooint = (FooMixinInt) foo;
String s = foo.fooMethod2 (-2);
]]>
</programlisting>
-
- <para>The <literal>fooMethod2()</literal> method, which is defined in \
<literal>FooMixin</literal> class but not in the <literal>Foo</literal> class, is now \
available in the <literal>Foo</literal> instance at the AOP \
runtime.</para>
-
- </section>
-
- </section>
-
- <section id="aop-build">
- <title>Build JBoss AOP Applications</title>
-
- <para>Building JBoss AOP applications is slightly different from building \
plain Java applications since the aspects and advices need to be instrumented into \
the compiled Java bytecode. For example, if an advice is bound to a method invocation \
joinpoint, the AOP instrumentation process would modify the joinpoint bytecode to \
call out to the advice method with the properly composed \
<literal>invocation</literal> object as an argument.</para>
-
- <section id="aop-build-compile">
- <title>Compile to bytecode</title>
-
- <para>The first step is to compile the all classes, including the aspect \
classes, to bytecode using the regular <literal>javac</literal> utility. If you use \
JDK 5.0 and the J2SE 5.0 style annotation, the annotation is automatically compiled \
into the bytecode class files.</para>
- </section>
-
- <section id="aop-build-annotation">
- <title>Compile annotation</title>
-
- <para>You can skip this step if you use Java annotations with the JDK 5.0. \
However, if you want to use JBoss AOP annotation with JDK 1.4, you have to embed the \
annotations in the Java doclet comments. They are not processed by the \
<literal>javac</literal> compiler. You have to use a annotation compiler provided by \
JBoss AOP to process the source code. The annotation compiler can directly add \
annotation to the bytecode class files or generate the annotation data in a separate \
XML file called <literal>metadata.xml</literal>. The following example compiles the \
annotation in <literal>Foo.java</literal> file into the <literal>Foo.class</literal> \
file.</para>
-
- <programlisting>
+ <para>The <literal>fooMethod2()</literal> method, which is defined
+ in <literal>FooMixin</literal> class but not in the
+ <literal>Foo</literal> class, is now available in the
+ <literal>Foo</literal> instance at the AOP runtime.</para>
+ </section>
+ </section>
+ <section id="aop-build">
+ <title>Build JBoss AOP Applications</title>
+ <para>Building JBoss AOP applications is slightly different from
+ building plain Java applications since the aspects and advices need
+ to be instrumented into the compiled Java bytecode. For example, if
+ an advice is bound to a method invocation joinpoint, the AOP
+ instrumentation process would modify the joinpoint bytecode to call
+ out to the advice method with the properly composed
+ <literal>invocation</literal> object as an argument.</para>
+ <section id="aop-build-compile">
+ <title>Compile to bytecode</title>
+ <para>The first step is to compile the all classes, including the
+ aspect classes, to bytecode using the regular
+ <literal>javac</literal> utility. If you use JDK 5.0 and the
+ J2SE 5.0 style annotation, the annotation is automatically
+ compiled into the bytecode class files.</para>
+ </section>
+ <section id="aop-build-annotation">
+ <title>Compile annotation</title>
+ <para>You can skip this step if you use Java annotations with the
+ JDK 5.0. However, if you want to use JBoss AOP annotation with
+ JDK 1.4, you have to embed the annotations in the JavaDoc
+ comments. They are not processed by the <literal>javac</literal>
+ compiler. You have to use a annotation compiler provided by
+ JBoss AOP to process the source code. The annotation compiler
+ can directly add annotation to the bytecode class files or
+ generate the annotation data in a separate XML file called
+ <literal>metadata.xml</literal>. The following example compiles
+ the annotation in <literal>Foo.java</literal> file into the
+ <literal>Foo.class</literal> file.</para>
+ <programlisting>
<![CDATA[
annotationc <classpath of the Foo.class file> -bytecode Foo.java
]]>
</programlisting>
-
- <para>The following example compiles the annotation into a \
<literal>metadata.xml</literal> file in the current directory and does not alter the \
<literal>Foo.class</literal> file. The <literal>metadata.xml</literal> file can be \
used later in the AOP bytecode instrumentation process.</para>
-
- <programlisting>
+ <para>The following example compiles the annotation into a
+ <literal>metadata.xml</literal> file in the current directory
+ and does not alter the <literal>Foo.class</literal> file. The
+ <literal>metadata.xml</literal> file can be used later in the
+ AOP bytecode instrumentation process.</para>
+ <programlisting>
<![CDATA[
annotationc <classpath> -xml Foo.java
]]>
</programlisting>
-
- <para>You can also run the annotation compiler within an ANT build script. \
The following example modifies the Java bytecode class files directly to add \
annotations.</para>
-
- <programlisting>
+ <para>You can also run the annotation compiler within an ANT build
+ script. The following example modifies the Java bytecode class
+ files directly to add annotations.</para>
+ <programlisting>
<![CDATA[
<taskdef name="annotationc"
classname="org.jboss.aop.ant.AnnotationC"
@@ -340,40 +430,49 @@
</target>
]]>
</programlisting>
-
- <para>In this book, we build applications using ANT. So, the ANT version of \
the annotation compiler is used.</para>
-
- </section>
-
-
- <section id="aop-build-aopc">
- <title>AOP Intrumentation</title>
-
- <para>The AOP instrumentation process modifies the Java bytecode to add \
runtime hooks around pointcuts. Those hooks collect reflection information and invoke \
advices. The <literal>aopc</literal> utility in JBoss AOP instruments the bytecode \
offline for JDK 1.4. If you use JDK 5.0, you have to replace all the \
<literal>aopc</literal> below to <literal>aopc15</literal>. It takes pointcuts \
definition from the <literal>jboss-aop.xml</literal> file or the \
<literal>metadata.xml</literal> file or the annotation tags already embedded in the \
bytecode by the annotation compiler. The following example shows how to invoke \
<literal>aopc</literal> from the command line with an associated \
<literal>jboss-aop.xml</literal> file.</para>
-
- <programlisting>
+ <para>In this book, we build applications using ANT. So, the ANT
+ version of the annotation compiler is used.</para>
+ </section>
+ <section id="aop-build-aopc">
+ <title>AOP Intrumentation</title>
+ <para>The AOP instrumentation process modifies the Java bytecode to
+ add runtime hooks around pointcuts. Those hooks collect
+ reflection information and invoke advices. The
+ <literal>aopc</literal> utility in JBoss AOP instruments the
+ bytecode offline for JDK 1.4. If you use JDK 5.0, you have to
+ replace all the <literal>aopc</literal> below to
+ <literal>aopc15</literal>. It takes pointcuts definition from
+ the <literal>jboss-aop.xml</literal> file or the
+ <literal>metadata.xml</literal> file or the annotation tags
+ already embedded in the bytecode by the annotation compiler. The
+ following example shows how to invoke <literal>aopc</literal>
+ from the command line with an associated
+ <literal>jboss-aop.xml</literal> file.</para>
+ <programlisting>
<![CDATA[
aopc <classpath> -aoppath jboss-aop.xml Foo.class
]]>
</programlisting>
-
- <para>If both <literal>jboss-aop.xml</literal> and \
<literal>metadata.xml</literal> files are present, you can put them in one directory \
and pass the directory name to <literal>aopc</literal>. In fact, all the \
<literal>*-aop.xml</literal> files in this directory will be treated as \
<literal>jboss-aop.xml</literal> by the <literal>aopc</literal> \
compiler.</para>
-
- <programlisting>
+ <para>If both <literal>jboss-aop.xml</literal> and
+ <literal>metadata.xml</literal> files are present, you can put
+ them in one directory and pass the directory name to
+ <literal>aopc</literal>. In fact, all the
+ <literal>*-aop.xml</literal> files in this directory will be
+ treated as <literal>jboss-aop.xml</literal> by the
+ <literal>aopc</literal> compiler.</para>
+ <programlisting>
<![CDATA[
aopc <classpath> -aoppath <directory to XML files> Foo.class
]]>
</programlisting>
-
- <programlisting>
+ <programlisting>
<![CDATA[
aopc <classpath> -aopclasspath <classpath to annotated aspect classes> Foo.class \
]]>
</programlisting>
-
- <para>The following example shows how to invoke <literal>aopc</literal> \
within an ANT build script.</para>
-
- <programlisting>
+ <para>The following example shows how to invoke
+ <literal>aopc</literal> within an ANT build script.</para>
+ <programlisting>
<![CDATA[
<taskdef name="aopc"
classname="org.jboss.aop.ant.AopC"
@@ -390,47 +489,75 @@
</target>
]]>
</programlisting>
-
- <para>The <literal>aopc</literal> instrumented bytecode can run directly in \
any JVM. Another option is to instrument the bytecode at the class load time. This \
way, you do not need to run the separate <literal>aopc</literal> program. In fact, if \
you use JDK 5.0 style annotations or do not use annotations, you do not even need to \
run the <literal>annotatec</literal> program. The JBoss application server can be \
configured to instrument AOP bytecode at class load time (see <xref \
linkend="aop-deployer-conf"/>).</para>
-
- </section>
-
- </section>
-
- <section id="aop-deployer">
- <title>JBoss AOP Deployer</title>
-
- <para>JBoss AOP applications are supported in the <literal>standard</literal> \
and <literal>all</literal> configurations in JBoss AS 4.0.0 (the \
<literal>default</literal> and <literal>all</literal> configurations in JBoss AS \
4.0.1). The <literal>jboss-aop.deployer</literal> service in the \
<literal>deploy</literal> directory deploys AOP applications inside the JBoss \
application server. The structure of the <literal>jboss-aop.deployer</literal> \
directory is shown in <xref linkend="aop-deployer.fig"/>. Please notice that the \
<literal>jboss-aop.deployer</literal> service archive in JBoss AS 4.0.0 is a zip file \
instead of a directory. It includes the following components:</para>
-
- <itemizedlist>
- <listitem>Java libraries for the JBoss AOP framework including utilities to \
instrument AOP classes at load time.</listitem>
-
- <listitem>A pre-packaged set of aspects, which are available in all \
applications deployed on the server. Those pre-packaged aspects handle crosscutting \
concerns, such as security, transaction and spawning asynchronous threads, for \
applications.</listitem>
-
- <listitem>A default aspect binding configuration file \
<literal>base-aop.xml</literal>. It binds pre-packaged aspects to certain annotations \
and method signature patterns. So, in your applications, you can just use those \
pre-defined annotations and method signatures to take advantage of the pre-packaged \
aspects.</listitem>
- </itemizedlist>
-
- <figure id="aop-deployer.fig">
- <title>The directory structure of the JBoss AOP deployer in JBoss \
AS.</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/aop-deployer.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <section id="aop-deployer-install">
- <title>Install the latest jboss-aop.deployer</title>
-
- <para>Since JBoss AOP is a fast evolving technology, it is probably a good \
idea to keep your <literal>jboss-aop.deployer</literal> service up-to-date with the \
latest JBoss AOP release. After you unzip the JBoss AOP release file, the \
<literal>jboss-40-install</literal> directory contains the \
<literal>jboss-aop.deployer</literal> archive for the JDK 1.4 and JDK 5.0 environment \
respectively. You can just copy those files to your JBoss server's \
<literal>deploy</literal> directory to replace the JBoss AOP service shipped with the \
application server.</para>
- </section>
-
- <section id="aop-deployer-conf">
- <title>Configure the AOP service</title>
-
- <para>By default, the <literal>jboss-aop.deployer</literal> service disables \
load-time bytecode instrumentation. You have to instrument your code offline with the \
<literal>aopc</literal> utility. We recommend you to enable load-time instrumentation \
by editing the <literal>META-INF/jboss-service.xml</literal> file in the \
<literal>jboss-aop.deployer</literal> directory. You can just change the the \
<literal>EnableTransformer</literal> attribute value to <literal>true</literal> as \
follows.</para>
-
- <programlisting>
+ <para>The <literal>aopc</literal> instrumented bytecode can run
+ directly in any JVM. Another option is to instrument the
+ bytecode at the class load time. This way, you do not need to
+ run the separate <literal>aopc</literal> program. In fact, if
+ you use JDK 5.0 style annotations or do not use annotations, you
+ do not even need to run the <literal>annotatec</literal>
+ program. The JBoss application server can be configured to
+ instrument AOP bytecode at class load time (see <xref \
linkend="aop-deployer-conf"/>).</para> + </section>
+ </section>
+ <section id="aop-deployer">
+ <title>JBoss AOP Deployer</title>
+ <para>JBoss AOP applications are supported in the
+ <literal>standard</literal> and <literal>all</literal>
+ configurations in JBoss AS 4.0.0 (the <literal>default</literal> and
+ <literal>all</literal> configurations in JBoss AS 4.0.1). The
+ <literal>jboss-aop.deployer</literal> service in the
+ <literal>deploy</literal> directory deploys AOP applications inside
+ the JBoss application server. The structure of the
+ <literal>jboss-aop.deployer</literal> directory is shown in <xref
+ linkend="aop-deployer.fig"/>. Please notice that the
+ <literal>jboss-aop.deployer</literal> service archive in JBoss AS
+ 4.0.0 is a zip file instead of a directory. It includes the
+ following components:</para>
+ <itemizedlist>
+ <listitem><para>Java libraries for the JBoss AOP framework including
+ utilities to instrument AOP classes at load \
time.</para></listitem> + <listitem><para>A pre-packaged set of aspects, \
which are available in all + applications deployed on the server. \
Those pre-packaged aspects + handle crosscutting concerns, such as \
security, transaction and + spawning asynchronous threads, for \
applications.</para></listitem> + <listitem><para>A default aspect \
binding configuration file + <literal>base-aop.xml</literal>. It \
binds pre-packaged aspects + to certain annotations and method \
signature patterns. So, in + your applications, you can just use \
those pre-defined + annotations and method signatures to take \
advantage of the + pre-packaged aspects.</para></listitem>
+ </itemizedlist>
+ <figure id="aop-deployer.fig">
+ <title>The directory structure of the JBoss AOP deployer in JBoss \
AS.</title> + <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/aop-deployer.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <section id="aop-deployer-install">
+ <title>Install the latest jboss-aop.deployer</title>
+ <para>Since JBoss AOP is a fast evolving technology, it is probably
+ a good idea to keep your <literal>jboss-aop.deployer</literal>
+ service up-to-date with the latest JBoss AOP release. After you
+ unzip the JBoss AOP release file, the
+ <literal>jboss-40-install</literal> directory contains the
+ <literal>jboss-aop.deployer</literal> archive for the JDK 1.4
+ and JDK 5.0 environment respectively. You can just copy those
+ files to your JBoss server's <literal>deploy</literal> directory
+ to replace the JBoss AOP service shipped with the application \
server.</para> + </section>
+ <section id="aop-deployer-conf">
+ <title>Configure the AOP service</title>
+ <para>By default, the <literal>jboss-aop.deployer</literal> service
+ disables load-time bytecode instrumentation. You have to
+ instrument your code offline with the <literal>aopc</literal>
+ utility. We recommend you to enable load-time instrumentation by
+ editing the <literal>META-INF/jboss-service.xml</literal> file
+ in the <literal>jboss-aop.deployer</literal> directory. You can
+ just change the <literal>EnableTransformer</literal>
+ attribute value to <literal>true</literal> as follows.</para>
+ <programlisting>
<![CDATA[
<mbean code="org.jboss.aop.deployment.AspectManagerService"
name="jboss.aop:service=AspectManager">
@@ -449,56 +576,68 @@
</mbean>
]]>
</programlisting>
-
- <para>Other attributes in the above mbean controls the behavior of the JBoss \
AOP deployer. Those attributes are manageable via the JBoss JMX console when the \
server is running.</para>
-
- </section>
-
- <section id="aop-deployer-aspects">
- <title>Pre-packaged aspects library</title>
-
- <para>The key value proposition of AOP is to promote code reuse. For \
example, we can reuse common aspects across different object trees in different \
applications.</para>
-
- <itemizedlist>
-
- <listitem>Transaction: JBoss AOP allows you to declare transaction \
requirements and properties on any POJO method. You can inject the current \
transaction manager anywhere in the code via annotation and save the trouble to write \
lookup code.</listitem>
-
- <listitem>Security: You can declare EJB-style security constraints on any \
POJO method to limit the access to them. We cover an security aspect example later in \
this chapter.</listitem>
-
- <listitem>Observer: You can transparently add observers to any POJO via \
annotation. For example, the observer could log all the call invocations against \
methods in the object. The previously mentioned <literal>trace()</literal> example \
shows the observer in action. This aspect can be used outside of the JBoss AS in \
standalone applications.</listitem>
-
- <listitem>Asynchronous method invocation: You can annotate a method to \
specify that it should be executed in a separate background thread. This aspect can \
be used outside of the JBoss AS in standalone applications. It is especially useful \
in Swing or SWT UI applications.</listitem>
-
- <listitem>ThreadBased: Any field value tagged with the annotation defined \
by this aspect would behave as though its value were stored in a \
<literal>java.lang.ThreadLocal</literal>. This aspect can be used outside of the \
JBoss AS in standalone applications.</listitem>
-
- <listitem>Read/Write Lock: It allows you to define at the method level a \
read/write lock using annotation The implementation is based on the concurrent \
package from Doug Lea. This aspect can be used outside of the JBoss AS in standalone \
applications.</listitem>
-
- </itemizedlist>
-
- <para>The pre-packaged aspect library in JBoss AOP is still under \
development. For the most up-to-date documentation on the currently available \
aspects, please refer to the <literal>docs/aspect-library/index.html</literal> \
document.</para>
-
- </section>
-
-
- </section>
-
- <section id="aop-deploy">
- <title>Package and deploy AOP applications to JBoss</title>
-
- <para>In this section, we use an example application to cover the common \
scenarios of packaging and deploying AOP applications inside JBoss. The example is an \
online mortgage payment calculator application (see <xref \
linkend="aop-calculator.fig"/>).</para>
-
- <figure id="aop-calculator.fig">
- <title>The Mortgage Calculator sample application.</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/aop-calculator.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The servlet uses the <literal>Calculator</literal> class to calculate \
the monthly payment based on the loan principal, term and interest \
rate.</para>
-
- <programlisting>
+ <para>Other attributes in the above mbean controls the behavior of
+ the JBoss AOP deployer. Those attributes are manageable via the
+ JBoss JMX console when the server is running.</para>
+ </section>
+ <section id="aop-deployer-aspects">
+ <title>Pre-packaged aspects library</title>
+ <para>The key value proposition of AOP is to promote code reuse. For
+ example, we can reuse common aspects across different object
+ trees in different applications.</para>
+ <itemizedlist>
+ <listitem><para>Transaction: JBoss AOP allows you to declare
+ transaction requirements and properties on any POJO method.
+ You can inject the current transaction manager anywhere in
+ the code via annotation and save the trouble to write lookup \
code.</para></listitem> + <listitem><para>Security: You can declare \
EJB-style security + constraints on any POJO method to limit the \
access to them. + We cover an security aspect example later in \
this chapter.</para></listitem> + <listitem><para>Observer: You can \
transparently add observers to any + POJO via annotation. For \
example, the observer could log all + the call invocations \
against methods in the object. The + previously mentioned \
<literal>trace()</literal> example + shows the observer in \
action. This aspect can be used + outside of the JBoss AS in \
standalone applications.</para></listitem> + \
<listitem><para>Asynchronous method invocation: You can annotate a + \
method to specify that it should be executed in a separate + \
background thread. This aspect can be used outside of the + JBoss \
AS in standalone applications. It is especially useful + in Swing \
or SWT UI applications.</para></listitem> + \
<listitem><para>ThreadBased: Any field value tagged with the + \
annotation defined by this aspect would behave as though its + \
value were stored in a + \
<literal>java.lang.ThreadLocal</literal>. This aspect can be + \
used outside of the JBoss AS in standalone applications.</para></listitem> + \
<listitem><para>Read/Write Lock: It allows you to define at the method + \
level a read/write lock using annotation The implementation + is \
based on the concurrent package from Doug Lea. This + aspect can \
be used outside of the JBoss AS in standalone applications.</para></listitem> + \
</itemizedlist> + <para>The pre-packaged aspect library in JBoss AOP is \
still under + development. For the most up-to-date documentation on \
the + currently available aspects, please refer to the
+ <literal>docs/aspect-library/index.html</literal> document.</para>
+ </section>
+ </section>
+ <section id="aop-deploy">
+ <title>Package and deploy AOP applications to JBoss</title>
+ <para>In this section, we use an example application to cover the common
+ scenarios of packaging and deploying AOP applications inside JBoss.
+ The example is an online mortgage payment calculator application
+ (see <xref linkend="aop-calculator.fig"/>).</para>
+ <figure id="aop-calculator.fig">
+ <title>The Mortgage Calculator sample application.</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" \
fileref="images/aop-calculator.png"/> + </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The servlet uses the <literal>Calculator</literal> class to
+ calculate the monthly payment based on the loan principal, term and
+ interest rate.</para>
+ <programlisting>
<![CDATA[
public class CalculatorServlet extends HttpServlet {
@@ -548,10 +687,9 @@
}
]]>
</programlisting>
-
- <para>The <literal>Calculator</literal> class represents a plain old Java \
object (POJO).</para>
-
- <programlisting>
+ <para>The <literal>Calculator</literal> class represents a plain old
+ Java object (POJO).</para>
+ <programlisting>
<![CDATA[
public class Calculator {
@@ -567,17 +705,42 @@
}
]]>
</programlisting>
-
- <para>In the world of J2EE containers, the <literal>Calculator</literal> POJO \
cannot make use of container services since it does not follow the pre-defined \
component models (e.g., it is not an EJB). But with JBoss AOP, we can apply EJB-style \
services as well as custom developed container services to the POJO at runtime. In \
the next two sections, we will show you how.</para>
-
- <section id="aop-deploy-prepackaged">
- <title>Use pre-packaged aspects</title>
-
- <para>As we have discussed in <xref linkend="aop-deployer-aspects"/>, JBoss \
application server 4 comes with several pre-packaged aspects. One of the most useful \
aspects is the security aspect. It supports access control to any POJO methods, just \
as the EJB security service constrains access to EJB methods. In this example, we \
demonstrate how to apply the pre-packaged security aspect to the \
<literal>Calculator.getPayment()</literal> method in the above mortgage calculator \
example.</para>
-
- <para>To develop applications using the pre-packaged aspects is easy. You \
can simply use the pre-defined annotation to mark up your source code and then use \
the annotation compiler to process the bytecode. In this example, the security domain \
is <literal>other</literal> indicating that the usernames, passwords and roles are \
stored in the <literal>users.properties</literal> and \
<literal>roles.properties</literal> files in the classpath. The security domain here \
has the same meaning as the security domain in EJB configuration file \
<literal>jboss.xml</literal> (see <xref linkend=""/>). Before the \
<literal>getPayment()</literal> method is invoked, the JBoss AOP security aspect \
transparently checks the user role based on the username obtained by the servlet in \
the web context. Please refer to <xref linkend=""/> for more details on how the \
security context is configured in the servlet layer. Only users with role \
<literal>Authorized</literal> can invoke the <literal>getPaym ent()</literal> \
method. The following is the annotated POJO code using the JDK 1.4 style \
annotation.</para>
-
- <programlisting>
+ <para>In the world of J2EE containers, the <literal>Calculator</literal>
+ POJO cannot make use of container services since it does not follow
+ the pre-defined component models (e.g., it is not an EJB). But with
+ JBoss AOP, we can apply EJB-style services as well as custom
+ developed container services to the POJO at runtime. In the next two
+ sections, we will show you how.</para>
+ <section id="aop-deploy-prepackaged">
+ <title>Use pre-packaged aspects</title>
+ <para>As we have discussed in <xref
+ linkend="aop-deployer-aspects"/>, JBoss application server 4
+ comes with several pre-packaged aspects. One of the most useful
+ aspects is the security aspect. It supports access control to
+ any POJO methods, just as the EJB security service constrains
+ access to EJB methods. In this example, we demonstrate how to
+ apply the pre-packaged security aspect to the
+ <literal>Calculator.getPayment()</literal> method in the above
+ mortgage calculator example.</para>
+ <para>To develop applications using the pre-packaged aspects is
+ easy. You can simply use the pre-defined annotation to mark up
+ your source code and then use the annotation compiler to process
+ the bytecode. In this example, the security domain is
+ <literal>other</literal> indicating that the usernames,
+ passwords and roles are stored in the
+ <literal>users.properties</literal> and
+ <literal>roles.properties</literal> files in the classpath. The
+ security domain here has the same meaning as the security domain
+ in EJB configuration file <literal>jboss.xml</literal>. Before the
+ <literal>getPayment()</literal> method is invoked, the JBoss AOP
+ security aspect transparently checks the user role based on the
+ username obtained by the servlet in the web context. <!-- Please
+ refer to <xref linkend=""/> for more details on how the security
+ context is configured in the servlet layer. --> Only users with \
role + <literal>Authorized</literal> can invoke the
+ <literal>getPayment()</literal> method. The following is the
+ annotated POJO code using the JDK 1.4 style annotation.</para>
+ <programlisting>
<![CDATA[
/**
* @@org.jboss.aspects.security.SecurityDomain ("other")
@@ -603,10 +766,8 @@
}
]]>
</programlisting>
-
- <para>The following is the POJO code with JDK 5.0 style annotation.</para>
-
- <programlisting>
+ <para>The following is the POJO code with JDK 5.0 style \
annotation.</para> + <programlisting>
<![CDATA[
@SecurityDomain ("other")
public class Calculator {
@@ -626,30 +787,50 @@
}
]]>
</programlisting>
-
- <para>No special packaging is required for deploying this application. You \
can just package the annotation-enhanced class files as regular Java classes in your \
<literal>.war</literal> or <literal>.ear</literal> applications. <xref \
linkend="aop-securityerror.fig"/> shows that the server refuses to invoke the \
<literal>Calculator.getPayment()</literal> method when the current user does not have \
the required <literal>Authorized</literal> role.</para>
-
- <figure id="aop-securityerror.fig">
- <title>Users with inadequate security roles are detected and rejected by \
the pre-packaged security aspect.</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/aop-securityerror.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Notice that your application does not have a \
<literal>jboss-aop.xml</literal> file since the default annotation tags and bindings \
are already defined in the <literal>base-aop.xml</literal> file that comes within the \
<literal>jboss-aop.deployer</literal> package. The down side is that you cannot \
easily instrument your bytecode outside the server container. The easiest way to \
deploy this application is to enable the load-time AOP instrumentation in the server \
(see section <xref linkend="aop-deployer-conf"/>).</para>
-
- </section>
-
- <section id="aop-deploy-custom">
- <title>Develop your own aspects</title>
-
- <para>In addition to the pre-packaged aspect services, JBoss AOP allows you \
to develop your own aspects to extend the AOP container services. In the following \
example, we show how to develop an aspect to limit the number of times the user can \
invoke certain POJO methods. When this aspect is applied to the \
<literal>Calculator</literal> object, you can make the mortgage calculator stop \
working after certain number of queries (i.e., put the calculator in the "trial \
software" mode).</para>
-
- <para>As we have discussed, the JBoss AOP aspect class itself is just a \
simple Java class. The advice method takes the <literal>Invocation</literal> object \
from the joinpoint as argument and checks how many times it has been invoked. If it \
has been invoked for more than 5 times, the aspect will stop the invocation and throw \
an exception.</para>
-
- <programlisting>
+ <para>No special packaging is required for deploying this
+ application. You can just package the annotation-enhanced class
+ files as regular Java classes in your <literal>.war</literal> or
+ <literal>.ear</literal> applications. <xref
+ linkend="aop-securityerror.fig"/> shows that the server refuses
+ to invoke the <literal>Calculator.getPayment()</literal> method
+ when the current user does not have the required
+ <literal>Authorized</literal> role.</para>
+ <figure id="aop-securityerror.fig">
+ <title>Users with inadequate security roles are detected and
+ rejected by the pre-packaged security aspect.</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" \
fileref="images/aop-securityerror.png"/> + </imageobject>
+ </mediaobject>
+ </figure>
+ <para>Notice that your application does not have a
+ <literal>jboss-aop.xml</literal> file since the default
+ annotation tags and bindings are already defined in the
+ <literal>base-aop.xml</literal> file that comes within the
+ <literal>jboss-aop.deployer</literal> package. The down side is
+ that you cannot easily instrument your bytecode outside the
+ server container. The easiest way to deploy this application is
+ to enable the load-time AOP instrumentation in the server (see
+ section <xref linkend="aop-deployer-conf"/>).</para>
+ </section>
+ <section id="aop-deploy-custom">
+ <title>Develop your own aspects</title>
+ <para>In addition to the pre-packaged aspect services, JBoss AOP
+ allows you to develop your own aspects to extend the AOP
+ container services. In the following example, we show how to
+ develop an aspect to limit the number of times the user can
+ invoke certain POJO methods. When this aspect is applied to the
+ <literal>Calculator</literal> object, you can make the mortgage
+ calculator stop working after certain number of queries (i.e.,
+ put the calculator in the "trial software" mode).</para>
+ <para>As we have discussed, the JBoss AOP aspect class itself is
+ just a simple Java class. The advice method takes the
+ <literal>Invocation</literal> object from the joinpoint as
+ argument and checks how many times it has been invoked. If it
+ has been invoked for more than 5 times, the aspect will stop the
+ invocation and throw an exception.</para>
+ <programlisting>
<![CDATA[
package com.jboss.aspect;
@@ -672,10 +853,14 @@
}
]]>
</programlisting>
-
- <para>Following the example of pre-packaged aspects, the easiest way to bind \
the custom aspect to applications is to use annotations. You can define custom \
annotations for this aspect and then publish them as part of the service API. In \
JBoss AOP, each annotation is a Java interface. The following \
<literal>TrialLimit</literal> interface defines the <literal>TrialLimit</literal> \
annotation tag.</para>
-
- <programlisting>
+ <para>Following the example of pre-packaged aspects, the easiest way
+ to bind the custom aspect to applications is to use annotations.
+ You can define custom annotations for this aspect and then
+ publish them as part of the service API. In JBoss AOP, each
+ annotation is a Java interface. The following
+ <literal>TrialLimit</literal> interface defines the
+ <literal>TrialLimit</literal> annotation tag.</para>
+ <programlisting>
<![CDATA[
package com.jboss.aspect;
@@ -683,10 +868,9 @@
}
]]>
</programlisting>
-
- <para>In the <literal>jboss-aop.xml</literal> file, you can specify the \
binding between the annotation tag and the advice method.</para>
-
- <programlisting>
+ <para>In the <literal>jboss-aop.xml</literal> file, you can specify
+ the binding between the annotation tag and the advice \
method.</para> + <programlisting>
<![CDATA[
<aop>
<aspect class="com.jboss.aspect.TrialLimitAspect"
@@ -699,10 +883,11 @@
</aop>
]]>
</programlisting>
-
- <para>Finally, in the application code, you just need to tag your methods, \
which need invocation limit control, with the annotation as you did with the \
pre-packaged aspects. Notice the second tag on the <literal>getPayment()</literal> \
method.</para>
-
- <programlisting>
+ <para>Finally, in the application code, you just need to tag your
+ methods, which need invocation limit control, with the
+ annotation as you did with the pre-packaged aspects. Notice the
+ second tag on the <literal>getPayment()</literal> method.</para>
+ <programlisting>
<![CDATA[
/**
* @@org.jboss.aspects.security.SecurityDomain ("other")
@@ -728,59 +913,79 @@
}
]]>
</programlisting>
-
- <para><xref linkend="aop-triallimit.fig"/> shows the servlet displaying an \
error message once the invocation limit has been reached.</para>
-
- <figure id="aop-triallimit.fig">
- <title>The custom aspect detects that the user has reached the invocation \
limit for this POJO method.</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/aop-triallimit.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- </section>
-
-
- <section id="aop-deploy-jar">
- <title>Package and deploy custom aspects</title>
-
- <para>In order to deploy the <literal>TrialLimitAspect</literal> aspect or \
any other custom aspects, you have to package them properly so that the JBoss \
application server can recognize them as aspect libraries. You have the following two \
options.</para>
-
- <itemizedlist>
- <listitem>First, you can package the aspect classes, annotation interfaces \
and configuration files together in a JAR archive file with the file name extension \
<literal>.aop</literal>. The <literal>jboss-aop.xml</literal> and \
<literal>metadata.xml</literal> files must reside in the <literal>META-INF</literal> \
directory in the <literal>.aop</literal> JAR archive. In this example, you can bundle \
the <literal>.aop</literal> file with the <literal>.war</literal> in the same \
<literal>.jar</literal> repository (see <xref linkend="aop-package-jar.fig"/>), and \
then deploy the <literal>.jar</literal> file as a single application. Or, you can \
deploy them side-by-side on the server. If you use custom aspects in EJB \
applications, you can include the <literal>.aop</literal> file directly inside your \
<literal>.ear</literal> file.</listitem>
-
- <listitem>Second, you can simply package the aspect classes and annotation \
interfaces in a <literal>.jar</literal> file and then specify the binding in a \
<literal>*-aop.xml</literal> file. You can copy the <literal>.jar</literal> file and \
the <literal>*-aop.xml</literal> files into the <literal>deploy</literal> directory \
(see <xref linkend="aop-package-xml.fig"/>). The aspects and their bindings become \
available to all applications deployed in this server.</listitem>
- </itemizedlist>
-
- <figure id="aop-package-jar.fig">
- <title>Package the aspect library, binding configuration file and web \
application into one JAR file for easy deployment.</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/aop-package-jar.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <figure id="aop-package-xml.fig">
- <title>The aspect library, binding configuration file and web application \
are deployed separately.</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/aop-package-xml.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The example application for this chapter uses the first approach and \
build a <literal>TrialLimitAspect.aop</literal> and a \
<literal>MortgageCalculator.war</literal> file side-by-side. All other applications \
deployed in the server can make use of the aspect in the \
<literal>TrialLimitAspect.aop</literal> file as well.</para>
-
-<!--
+ <para>
+ <xref linkend="aop-triallimit.fig"/> shows the servlet
+ displaying an error message once the invocation limit has been \
reached.</para> + <figure id="aop-triallimit.fig">
+ <title>The custom aspect detects that the user has reached the
+ invocation limit for this POJO method.</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" \
fileref="images/aop-triallimit.png"/> + </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="aop-deploy-jar">
+ <title>Package and deploy custom aspects</title>
+ <para>In order to deploy the <literal>TrialLimitAspect</literal>
+ aspect or any other custom aspects, you have to package them
+ properly so that the JBoss application server can recognize them
+ as aspect libraries. You have the following two options.</para>
+ <itemizedlist>
+ <listitem><para>First, you can package the aspect classes, \
annotation + interfaces and configuration files together in a JAR \
archive + file with the file name extension \
<literal>.aop</literal>. + The <literal>jboss-aop.xml</literal> \
and + <literal>metadata.xml</literal> files must reside in the
+ <literal>META-INF</literal> directory in the
+ <literal>.aop</literal> JAR archive. In this example, you
+ can bundle the <literal>.aop</literal> file with the
+ <literal>.war</literal> in the same <literal>.jar</literal>
+ repository (see <xref linkend="aop-package-jar.fig"/>), and
+ then deploy the <literal>.jar</literal> file as a single
+ application. Or, you can deploy them side-by-side on the
+ server. If you use custom aspects in EJB applications, you
+ can include the <literal>.aop</literal> file directly inside
+ your <literal>.ear</literal> file.</para></listitem>
+ <listitem><para>Second, you can simply package the aspect classes \
and + annotation interfaces in a <literal>.jar</literal> file and
+ then specify the binding in a <literal>*-aop.xml</literal>
+ file. You can copy the <literal>.jar</literal> file and the
+ <literal>*-aop.xml</literal> files into the
+ <literal>deploy</literal> directory (see <xref
+ linkend="aop-package-xml.fig"/>). The aspects and their
+ bindings become available to all applications deployed in
+ this server.</para></listitem>
+ </itemizedlist>
+ <figure id="aop-package-jar.fig">
+ <title>Package the aspect library, binding configuration file
+ and web application into one JAR file for easy \
deployment.</title> + <mediaobject>
+ <imageobject>
+ <imagedata align="center" \
fileref="images/aop-package-jar.png"/> + </imageobject>
+ </mediaobject>
+ </figure>
+ <figure id="aop-package-xml.fig">
+ <title>The aspect library, binding configuration file and web
+ application are deployed separately.</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" \
fileref="images/aop-package-xml.png"/> + </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The example application for this chapter uses the first
+ approach and build a <literal>TrialLimitAspect.aop</literal> and
+ a <literal>MortgageCalculator.war</literal> file side-by-side.
+ All other applications deployed in the server can make use of
+ the aspect in the <literal>TrialLimitAspect.aop</literal> file
+ as well.</para>
+ <!--
<para>For your reference, here is the ANT <literal>build.xml</literal> \
script we used to build and package the mortgage calculator application with the \
<literal>TrialLimitAspect</literal> aspect. The <literal>all</literal> task builds a \
single <literal>.jar</literal> file containing the <literal>.aop</literal> and \
<literal>.war</literal> files in the <literal>build/jar</literal> directory; the \
<literal>all2</literal> task builds the <literal>.aop</literal> and \
<literal>.war</literal> files side-by-side; the <literal>all2</literal> task builds \
the <literal>.war</literal> file, the <literal>.jar</literal> file for the aspect \
classes and the <literal>TrialLimit-aop.xml</literal> file which is a copy of the \
<literal>jboss-aop.xml</literal> file.</para>
-->
-
+ </section>
</section>
-
- </section>
-
-</chapter>
\ No newline at end of file
+</chapter>
-------------------------------------------------------
The SF.Net email is sponsored by: Beat the post-holiday blues
Get a FREE limited edition SourceForge.net t-shirt from ThinkGeek.
It's fun and FREE -- well, almost....http://www.thinkgeek.com/sfshirt
_______________________________________________
jboss-cvs-commits mailing list
jboss-cvs-commits@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/jboss-cvs-commits
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic