root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Polish Spring AOP documentation

This commit is contained in:
Sam Brannen 2024-11-17 12:21:16 +01:00
parent 6544698078
commit 173084f81a
2 changed files with 21 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc
View File

@ -33,7 +33,7 @@ arbitrary advice types. This section describes the basic concepts and standard a
[[aop-api-advice-around]] [[aop-api-advice-around]]
=== Interception Around Advice === Interception Around Advice
The most fundamental advice type in Spring is interception around advice. The most fundamental advice type in Spring is _interception around advice_.
Spring is compliant with the AOP `Alliance` interface for around advice that uses method Spring is compliant with the AOP `Alliance` interface for around advice that uses method
interception. Classes that implement `MethodInterceptor` and that implement around advice should also implement the interception. Classes that implement `MethodInterceptor` and that implement around advice should also implement the
@ -49,8 +49,8 @@ following interface:
The `MethodInvocation` argument to the `invoke()` method exposes the method being The `MethodInvocation` argument to the `invoke()` method exposes the method being
invoked, the target join point, the AOP proxy, and the arguments to the method. The invoked, the target join point, the AOP proxy, and the arguments to the method. The
`invoke()` method should return the invocation's result: the return value of the join `invoke()` method should return the invocation's result: typically the return value of
point. the join point.
The following example shows a simple `MethodInterceptor` implementation: The following example shows a simple `MethodInterceptor` implementation:
@ -64,9 +64,9 @@ Java::
public Object invoke(MethodInvocation invocation) throws Throwable { public Object invoke(MethodInvocation invocation) throws Throwable {
System.out.println("Before: invocation=[" + invocation + "]"); System.out.println("Before: invocation=[" + invocation + "]");
Object rval = invocation.proceed(); Object result = invocation.proceed();
System.out.println("Invocation returned"); System.out.println("Invocation returned");
return rval; return result;
} }
} }
---- ----
@ -79,9 +79,9 @@ Kotlin::
override fun invoke(invocation: MethodInvocation): Any { override fun invoke(invocation: MethodInvocation): Any {
println("Before: invocation=[$invocation]") println("Before: invocation=[$invocation]")
val rval = invocation.proceed() val result = invocation.proceed()
println("Invocation returned") println("Invocation returned")
return rval return result
} }
} }
---- ----
@ -105,7 +105,7 @@ currently define pointcut interfaces.
[[aop-api-advice-before]] [[aop-api-advice-before]]
=== Before Advice === Before Advice
A simpler advice type is a before advice. This does not need a `MethodInvocation` A simpler advice type is a _before advice_. This does not need a `MethodInvocation`
object, since it is called only before entering the method. object, since it is called only before entering the method.
The main advantage of a before advice is that there is no need to invoke the `proceed()` The main advantage of a before advice is that there is no need to invoke the `proceed()`
@ -122,10 +122,6 @@ The following listing shows the `MethodBeforeAdvice` interface:
} }
---- ----
(Spring's API design would allow for
field before advice, although the usual objects apply to field interception and it is
unlikely for Spring to ever implement it.)
Note that the return type is `void`. Before advice can insert custom behavior before the join Note that the return type is `void`. Before advice can insert custom behavior before the join
point runs but cannot change the return value. If a before advice throws an point runs but cannot change the return value. If a before advice throws an
exception, it stops further execution of the interceptor chain. The exception exception, it stops further execution of the interceptor chain. The exception
@ -176,10 +172,10 @@ TIP: Before advice can be used with any pointcut.
[[aop-api-advice-throws]] [[aop-api-advice-throws]]
=== Throws Advice === Throws Advice
Throws advice is invoked after the return of the join point if the join point threw _Throws advice_ is invoked after the return of the join point if the join point threw
an exception. Spring offers typed throws advice. Note that this means that the an exception. Spring offers typed throws advice. Note that this means that the
`org.springframework.aop.ThrowsAdvice` interface does not contain any methods. It is a `org.springframework.aop.ThrowsAdvice` interface does not contain any methods. It is a
tag interface identifying that the given object implements one or more typed throws marker interface identifying that the given object implements one or more typed throws
advice methods. These should be in the following form: advice methods. These should be in the following form:
[source,java,indent=0,subs="verbatim,quotes"] [source,java,indent=0,subs="verbatim,quotes"]
@ -189,9 +185,10 @@ advice methods. These should be in the following form:
Only the last argument is required. The method signatures may have either one or four Only the last argument is required. The method signatures may have either one or four
arguments, depending on whether the advice method is interested in the method and arguments, depending on whether the advice method is interested in the method and
arguments. The next two listing show classes that are examples of throws advice. arguments. The next two listings show classes that are examples of throws advice.
The following advice is invoked if a `RemoteException` is thrown (including from subclasses): The following advice is invoked if a `RemoteException` is thrown (including subclasses of
`RemoteException`):
[tabs] [tabs]
====== ======
@ -220,9 +217,9 @@ Kotlin::
---- ----
====== ======
Unlike the preceding Unlike the preceding advice, the next example declares four arguments, so that it has
advice, the next example declares four arguments, so that it has access to the invoked method, method access to the invoked method, method arguments, and target object. The following advice
arguments, and target object. The following advice is invoked if a `ServletException` is thrown: is invoked if a `ServletException` is thrown:
[tabs] [tabs]
====== ======
@ -304,7 +301,7 @@ TIP: Throws advice can be used with any pointcut.
[[aop-api-advice-after-returning]] [[aop-api-advice-after-returning]]
=== After Returning Advice === After Returning Advice
An after returning advice in Spring must implement the An _after returning advice_ in Spring must implement the
`org.springframework.aop.AfterReturningAdvice` interface, which the following listing shows: `org.springframework.aop.AfterReturningAdvice` interface, which the following listing shows:
[source,java,indent=0,subs="verbatim,quotes"] [source,java,indent=0,subs="verbatim,quotes"]
@ -368,7 +365,7 @@ TIP: After returning advice can be used with any pointcut.
[[aop-api-advice-introduction]] [[aop-api-advice-introduction]]
=== Introduction Advice === Introduction Advice
Spring treats introduction advice as a special kind of interception advice. Spring treats _introduction advice_ as a special kind of interception advice.
Introduction requires an `IntroductionAdvisor` and an `IntroductionInterceptor` that Introduction requires an `IntroductionAdvisor` and an `IntroductionInterceptor` that
implement the following interface: implement the following interface:

6
spring-aop/src/main/java/org/springframework/aop/ThrowsAdvice.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright 2002-2008 the original author or authors. * Copyright 2002-2024 the original author or authors.
* *
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
@ -27,11 +27,11 @@ package org.springframework.aop;
* <p>Some examples of valid methods would be: * <p>Some examples of valid methods would be:
* *
* <pre class="code">public void afterThrowing(Exception ex)</pre> * <pre class="code">public void afterThrowing(Exception ex)</pre>
* <pre class="code">public void afterThrowing(RemoteException)</pre> * <pre class="code">public void afterThrowing(RemoteException ex)</pre>
* <pre class="code">public void afterThrowing(Method method, Object[] args, Object target, Exception ex)</pre> * <pre class="code">public void afterThrowing(Method method, Object[] args, Object target, Exception ex)</pre>
* <pre class="code">public void afterThrowing(Method method, Object[] args, Object target, ServletException ex)</pre> * <pre class="code">public void afterThrowing(Method method, Object[] args, Object target, ServletException ex)</pre>
* *
* The first three arguments are optional, and only useful if we want further * <p>The first three arguments are optional, and only useful if we want further
* information about the joinpoint, as in AspectJ <b>after-throwing</b> advice. * information about the joinpoint, as in AspectJ <b>after-throwing</b> advice.
* *
* <p><b>Note:</b> If a throws-advice method throws an exception itself, it will * <p><b>Note:</b> If a throws-advice method throws an exception itself, it will