Spring/spring-net
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update reference documentation generation tools to get source highlighting [SPRNET-1045]

Browse Source
This commit is contained in:
bbaia
2008-10-05 17:25:10 +00:00
parent 26cb75d4e0
commit 5dfa039603
125 changed files with 4487 additions and 7338 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
doc/reference/src/aop-aspect-library.xml
View File

@@ -1,8 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="aop-aspect-library">
<!--
/*
* Copyright 2002-2008 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-->
<chapter xml:id="aop-aspect-library" xmlns="http://docbook.org/ns/docbook" version="5">
<title>Aspect Library</title>
<sect1 id="aop-library-introduction">
<sect1 xml:id="aop-library-introduction">
<title>Introduction</title>
<para>Spring provides several aspects in the distribution. The most
@@ -15,7 +32,7 @@
release.</para>
</sect1>
<sect1 id="caching-aspect">
<sect1 xml:id="caching-aspect">
<title>Caching</title>
<para>Caching the return value of a method or the value of a method
@@ -34,12 +51,12 @@
functionality and its configuration.</para>
<para>The base cache interface that any cache implementation should
implement is <classname>Spring.Caching.ICache</classname> located in
<classname>Spring.Core.</classname> Two implementations are provided,
<classname>Spring.Caching.AspNetCache </classname>located in
<classname>Spring.Web</classname> which stores cache entries within an
implement is <literal>Spring.Caching.ICache</literal> located in
<literal>Spring.Core</literal>. Two implementations are provided,
<literal>Spring.Caching.AspNetCache</literal> located in
<literal>Spring.Web</literal> which stores cache entries within an
ASP.NET cache and a simple implementation,
<classname>Spring.Caching.NonExpiringCache</classname> that stores cache
<literal>Spring.Caching.NonExpiringCache</literal> that stores cache
entries in memory and never expires these entries. Custom implementations
based on 3rd party implementations, such as Oracle Coherence, or
memcached, can be used by implementing the <literal>ICache</literal>
@@ -59,18 +76,18 @@
<itemizedlist>
<listitem>
<para><literal>CacheResult - used to cache the return
value</literal></para>
<para><literal>CacheResult</literal> - used to cache the return
value</para>
</listitem>
<listitem>
<para><literal>CacheResultItems - used when returning a collection as
a return value </literal></para>
<para><literal>CacheResultItems</literal> - used when returning a collection as
a return value</para>
</listitem>
<listitem>
<para><literal>CacheParameter - used to cache a method
parameter</literal></para>
<para><literal>CacheParameter</literal> - used to cache a method
parameter</para>
</listitem>
<listitem>
@@ -79,9 +96,9 @@
</listitem>
</itemizedlist>
<para>Each <classname>CacheResult</classname>,
<classname>CacheResultItems</classname>, and
<classname>CacheParameter</classname> attributes define the following
<para>Each <literal>CacheResult</literal>,
<literal>CacheResultItems</literal>, and
<literal>CacheParameter</literal> attributes define the following
properties.</para>
<itemizedlist>
@@ -108,13 +125,13 @@
</listitem>
</itemizedlist>
<para>The <classname>InvalidateCache</classname> attribute has properties
<para>The <literal>InvalidateCache</literal> attribute has properties
for the CacheName, the Key as well as the Condition, with the same
meanings as listed previously.</para>
<para>Each <classname>ICache</classname> implementation will have
<para>Each <literal>ICache</literal> implementation will have
properties that are specific to a caching technology. In the case of
<classname>AspNetCache</classname>, the two important properties to
<literal>AspNetCache</literal>, the two important properties to
configure are:</para>
<itemizedlist>
@@ -166,12 +183,11 @@
sample application of the AirportDao implementation that implements an
interface with the method GetAirport(long id).</para>
<programlisting> [CacheResult("AspNetCache", "'Airport.Id=' + #id", TimeToLive = "0:1:0")]
public Airport GetAirport(long id)
{
// implementation not shown...
}
</programlisting>
<programlisting language="csharp">[<classname>CacheResult</classname>("AspNetCache", "'Airport.Id=' + #id", TimeToLive = "0:1:0")]
public <classname>Airport</classname> GetAirport(long id)
{
// implementation not shown...
}</programlisting>
<para>The first parameter is the cache name. The second string parameter
is the cache key and is a string expression that incorporates the argument
@@ -186,35 +202,35 @@
<para>The configuration to enable the caching aspect is shown below</para>
<programlisting> &lt;object id="CacheAspect" type="Spring.Aspects.Cache.CacheAspect, Spring.Aop"/&gt;
&lt;object id="AspNetCache" type="Spring.Caching.AspNetCache, Spring.Web"&gt;
&lt;property name="SlidingExpiration" value="true"/&gt;
&lt;property name="Priority" value="Low"/&gt;
&lt;property name="TimeToLive" value="00:02:00"/&gt;
&lt;/object&gt;
<programlisting language="myxml"><![CDATA[<object" id="CacheAspect" type="Spring.Aspects.Cache.CacheAspect, Spring.Aop"/>
<object id="AspNetCache" type="Spring.Caching.AspNetCache, Spring.Web">
<property name="SlidingExpiration" value="true"/>
<property name="Priority" value="Low"/>
<property name="TimeToLive" value="00:02:00"/>
</object>
&lt;!-- Apply aspects to DAOs --&gt;
&lt;object type="Spring.Aop.Framework.AutoProxy.ObjectNameAutoProxyCreator, Spring.Aop"&gt;
&lt;property name="ObjectNames"&gt;
&lt;list&gt;
&lt;value&gt;*Dao&lt;/value&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;property name="InterceptorNames"&gt;
&lt;list&gt;
&lt;value&gt;CacheAspect&lt;/value&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/object&gt;</programlisting>
<!-- Apply aspects to DAOs -->
<object type="Spring.Aop.Framework.AutoProxy.ObjectNameAutoProxyCreator, Spring.Aop">
<property name="ObjectNames">
<list>
<value>*Dao</value>
</list>
</property>
<property name="InterceptorNames">
<list>
<value>CacheAspect</value>
</list>
</property>
</object>]]></programlisting>
<para>in this example an <classname>ObjectNameAutoProxyCreator</classname>
<para>in this example an <literal>ObjectNameAutoProxyCreator</literal>
was used to apply the cache aspect to objects that have Dao in their name.
The AspNetCache setting for TimeToLive will override the TimeToLive value
set at the method level via the attribute.</para>
</sect1>
<sect1 id="exception-aspect">
<sect1 xml:id="exception-aspect">
<title>Exception Handling</title>
<para>In some cases existing code can be easily adopted to a simple error
@@ -252,13 +268,13 @@
could be referred to as a Domain Specific Language (DSL). Here is a simple
example, which should hopefully be self explanatory.</para>
<para><programlisting>&lt;object name="exceptionHandlingAdvice" type="Spring.Aspects.Exceptions.ExceptionHandlerAdvice, Spring.Aop"&gt;
&lt;property name="exceptionHandlers"&gt;
&lt;list&gt;
&lt;value&gt;<emphasis role="bold">on exception name ArithmeticException wrap System.InvalidOperationException</emphasis>&lt;/value&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/object&gt;</programlisting>What this is instructing the advice to do is
<para><programlisting language="myxml"><![CDATA[<object name="exceptionHandlingAdvice" type="Spring.Aspects.Exceptions.ExceptionHandlerAdvice, Spring.Aop">
<property name="exceptionHandlers">
<list>
<value>on exception name ArithmeticException wrap System.InvalidOperationException</value>
</list>
</property>
</object>]]></programlisting>What this is instructing the advice to do is
the following bit of code when an ArithmeticException is thrown, throw new
System.InvalidOperationException("Wrapped ArithmeticException", e), where
e is the original ArithmeticException. The default message, "Wrapped
@@ -283,7 +299,7 @@ on exception name ArithmeticException replace System.InvalidOperationException '
<para><programlisting>on exception name ArithmeticException translate new System.InvalidOperationException('My Message, Method Name ' + #method.Name, #e)</programlisting>What
we see here after the translate keyword is text that will be passed into
Spring's expression language (SpEL) for evaluation. Refer to the chapter
on the <link linkend="expression">expression language</link> for more
on the <link linkend="expressions">expression language</link> for more
details. One important feature of the expression evaluation is the
availability of variables relating to the calling context when the
exception was thrown. These are</para>
@@ -340,7 +356,7 @@ on exception name ArithmeticException return 12</programlisting>
action, i.e. log(Debug,"LoggerName").</para>
<para>Multiple exception handling statements can be specified within the
&lt;list&gt; shown above. The processing flow is on exception, the name of
list shown above. The processing flow is on exception, the name of
the exception listed in the statement is compared to the thrown exception
to see if there is a match. A comma separated list of exceptions can be
used to group together the same action taken for different exception
@@ -383,17 +399,17 @@ on exception name ArithmeticException return 12</programlisting>
for example setting the logging level and pass the exception into the
logging subsystem</para>
<programlisting>&lt;object name="exceptionHandlingAdvice" type="Spring.Aspects.Exceptions.ExceptionHandlerAdvice, Spring.Aop"&gt;
&lt;property name="exceptionHandlers"&gt;
&lt;list&gt;
&lt;object type="Spring.Aspects.Exceptions.LogExceptionHandler"&gt;
&lt;property name="LogName" value="Cms.Session.ExceptionHandler" /&gt;
&lt;property name="ConstraintExpressionText" value="#e is T(System.Threading.ThreadAbortException)" /&gt;
&lt;property name="ActionExpressionText" value="#log.Fatal('Request Timeout occured', #e)" /&gt;
&lt;/object&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/object&gt;</programlisting>
<programlisting language="myxml"><![CDATA[<object name="exceptionHandlingAdvice" type="Spring.Aspects.Exceptions.ExceptionHandlerAdvice, Spring.Aop">
<property name="exceptionHandlers">
<list>
<object type="Spring.Aspects.Exceptions.LogExceptionHandler">
<property name="LogName" value="Cms.Session.ExceptionHandler" />
<property name="ConstraintExpressionText" value="#e is T(System.Threading.ThreadAbortException)" />
<property name="ActionExpressionText" value="#log.Fatal('Request Timeout occured', #e)" />
</object>
</list>
</property>
</object>]]></programlisting>
<para>The configuration of the logger name, level, and weather or not to
pass the thrown exception as the second argument to the log method will be
@@ -455,12 +471,12 @@ on exception name ArithmeticException return 12</programlisting>
</sect2>
</sect1>
<sect1 id="logging-aspect">
<sect1 xml:id="logging-aspect">
<title>Logging</title>
<para>The logging advice lets you log the information on method entry,
exit and thrown exception (if any). The implementation is based on the
logging library, <link linkend="???">Common.Logging</link>, that provides
logging library, <ulink url="http://netcommon.sourceforge.net/">Common.Logging</ulink>, that provides
portability across different logging libraries. There are a number of
configuration options available, listed below</para>
@@ -492,21 +508,21 @@ on exception name ArithmeticException return 12</programlisting>
<para>You declare the logging advice in IoC container with the following
XML fragment. Alternatively, you can use the class
<classname>SimpleLoggingAdvice</classname> programatically.</para>
<literal>SimpleLoggingAdvice</literal> programatically.</para>
<programlisting>&lt;object name="loggingAdvice" type="Spring.Aspects.Logging.SimpleLoggingAdvice, Spring.Aop"&gt;
&lt;property name="logUniqueIdentifier" value="true"/&gt;
&lt;property name="logExecutionTime" value="true"/&gt;
&lt;property name="logMethodArguments" value="true"/&gt;
&lt;property name="LogReturnValue" value="true"/&gt;
<programlisting language="myxml"><![CDATA[<object name="loggingAdvice" type="Spring.Aspects.Logging.SimpleLoggingAdvice, Spring.Aop">
<property name="logUniqueIdentifier" value="true"/>
<property name="logExecutionTime" value="true"/>
<property name="logMethodArguments" value="true"/>
<property name="LogReturnValue" value="true"/>
&lt;property name="Separator" value=";"/&gt;
&lt;property name="LogLevel" value="Info"/&gt;
<property name="Separator" value=";"/>
<property name="LogLevel" value="Info"/>
&lt;property name="HideProxyTypeNames" value="true"/&gt;
&lt;property name="UseDynamicLogger" value="true"/&gt;
&lt;/object&gt;</programlisting>
<property name="HideProxyTypeNames" value="true"/>
<property name="UseDynamicLogger" value="true"/>
</object>]]></programlisting>
<para>The default values for LogUniqueIdentifier, LogExecutionTime,
LogMethodArguments and LogReturnValue are false. The default separator
@@ -526,8 +542,8 @@ on exception name ArithmeticException return 12</programlisting>
true target type and not the proxy type.</para>
<para>To further extend the functionality of the
<classname>SimpleLoggingAdvice</classname> you can subclass
<classname>SimpleLoggingAdvice</classname> and override the methods</para>
<literal>SimpleLoggingAdvice</literal> you can subclass
<literal>SimpleLoggingAdvice</literal> and override the methods</para>
<itemizedlist>
<listitem>
@@ -551,19 +567,19 @@ on exception name ArithmeticException return 12</programlisting>
<para>The default implementation to calculate a unique identifier is to
use a GUID. You can alter this behavior by overriding the method
<literal>string CreateUniqueIdentifier()</literal>. The
<classname>SimpleLoggingAdvice</classname> class inherits from
<classname>AbstractLoggingAdvice</classname>, which has the abstract
<literal>SimpleLoggingAdvice</literal> class inherits from
<literal>AbstractLoggingAdvice</literal>, which has the abstract
method <literal>object InvokeUnderLog(IMethodInvocation invocation, ILog
log)</literal> and you can also override the method <literal>ILog
GetLoggerForInvocation(IMethodInvocation invocation)</literal> to
customize the logger instance used for logging. Refer to the SDK
documentation for more details on subclassing
<classname>AbstractLoggingAdvice</classname>.</para>
<literal>AbstractLoggingAdvice</literal>.</para>
<para>As an example of the Logging advice's output, adding the advice to
the method</para>
<programlisting>public int Bark(string message, int[] luckyNumbers)
<programlisting language="csharp">public int Bark(string message, int[] luckyNumbers)
{
return 4;
}</programlisting>
@@ -586,7 +602,7 @@ Exiting Bark, 5d2bad47-62cd-435b-8de7-91f12b7f433e, 30453.125 ms, return=4</prog
using similar syntax to the retry and exception handling advice.</para>
</sect1>
<sect1 id="retry-aspect">
<sect1 xml:id="retry-aspect">
<title>Retry</title>
<para>When making a distributed call it is often a common requirement to
@@ -657,11 +673,11 @@ on exception (#e is T(System.ArithmeticException)) retry 3x rate (1*#n + 0.5)</p
</listitem>
</itemizedlist>You declare the advice in IoC container with the
following XML fragment. Alternatively, you can use the
<classname>RetryAdvice</classname> class programatically.</para>
<literal>RetryAdvice</literal> class programatically.</para>
<programlisting>&lt;object name="exceptionHandlingAdvice" type="Spring.Aspects.RetryAdvice, Spring.Aop"&gt;
&lt;property name="retryExpression" value="<emphasis role="bold">on exception name ArithmeticException retry 3x delay 1s</emphasis>"/&gt;
&lt;/object&gt;</programlisting>
<programlisting language="myxml"><![CDATA[<object name="exceptionHandlingAdvice" type="Spring.Aspects.RetryAdvice, Spring.Aop">
<property name="retryExpression" value="on exception name ArithmeticException retry 3x delay 1s"/>
</object>]]></programlisting>
<sect2>
<title>Language Reference</title>
@@ -679,14 +695,14 @@ on exception (#e is T(System.ArithmeticException)) retry 3x rate (1*#n + 0.5)</p
</sect2>
</sect1>
<sect1 id="tx-aspect">
<sect1 xml:id="tx-aspect">
<title>Transactions</title>
<para>The transaction aspect is more fully described in the section on
<link linkend="transaction">transaction management</link>.</para>
</sect1>
<sect1 id="parameter-validation">
<sect1 xml:id="parameter-validation">
<title>Parameter Validation</title>
<para>Spring provides a UI-agnostic <link linkend="validation">validation
@@ -705,15 +721,15 @@ on exception (#e is T(System.ArithmeticException)) retry 3x rate (1*#n + 0.5)</p
<para>To address some of the common needs for validation on the server
side, Spring provides parameter validation advice so that applies Spring's
validation rules to the method parameters. The class
<classname>ParameterValidationAdvice</classname> is used in conjunction
with the <classname>Validated</classname> attribute to specify which
<literal>ParameterValidationAdvice</literal> is used in conjunction
with the <literal>Validated</literal> attribute to specify which
validation rules are applied to method parameters. For example, to apply
parameter validation to the method SuggestFlights in the BookingAgent
class used in the <link linkend="springair">SpringAir sample
application</link>, you would apply the <classname>Validated</classname>
application</link>, you would apply the <literal>Validated</literal>
attribute to the method parameters as shown below.</para>
<programlisting>public FlightSuggestions SuggestFlights( [Validated("tripValidator")] Trip trip)
<programlisting language="csharp">public <classname>FlightSuggestions</classname> SuggestFlights( [<classname>Validated</classname>("tripValidator")] <classname>Trip</classname> trip)
{
// unmodified implementation goes here
}</programlisting>
@@ -721,34 +737,34 @@ on exception (#e is T(System.ArithmeticException)) retry 3x rate (1*#n + 0.5)</p
<para>The <literal>Validated</literal> attribute takes a string name that
specifies the name of the validation rule, i.e. the name of the IValidator
object in the Spring application context. The
<classname>Validated</classname> attribute is located in the namespace
<literal>Validated</literal> attribute is located in the namespace
<literal>Spring.Validation</literal> of the <literal>Spring.Core</literal>
assembly.</para>
<para>The configuration of the advice is to simply define the an instance
of the <literal>ParameterValidationAdvice</literal> class and apply the
advice, for example based on object names using an
<classname>ObjectNameAutoProxyCreator</classname>, as shown below,</para>
<literal>ObjectNameAutoProxyCreator</literal>, as shown below,</para>
<programlisting> &lt;object id="<emphasis role="bold">validationAdvice</emphasis>" type="Spring.Aspects.Validation.ParameterValidationAdvice, Spring.Aop"/&gt;
<programlisting language="myxml"><![CDATA[<object id="validationAdvice" type="Spring.Aspects.Validation.ParameterValidationAdvice, Spring.Aop"/>
&lt;object type="Spring.Aop.Framework.AutoProxy.ObjectNameAutoProxyCreator, Spring.Aop"&gt;
&lt;property name="ObjectNames"&gt;
&lt;list&gt;
&lt;value&gt;bookingAgent&lt;/value&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;property name="InterceptorNames"&gt;
&lt;list&gt;
&lt;value&gt;<emphasis role="bold">validationAdvice</emphasis>&lt;/value&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/object&gt;</programlisting>
<object type="Spring.Aop.Framework.AutoProxy.ObjectNameAutoProxyCreator, Spring.Aop">
<property name="ObjectNames">
<list>
<value>bookingAgent</value>
</list>
</property>
<property name="InterceptorNames">
<list>
<value>validationAdvice</value>
</list>
</property>
</object>]]></programlisting>
<para>When the advised method is invoked first the validation of each
method parameter is performed. If all validation succeeds, then the method
body is executed. If validation fails an exception of the type
<classname>ValidationException</classname> is thrown and you can retrieve
<literal>ValidationException</literal> is thrown and you can retrieve
errors information from its property <literal>ValidationErrors</literal>.
See the SDK documentation for details.</para>
</sect1>