Skip to content

Commit

Permalink
Remove remaining Kotlin "translations" of Java APIs in the reference …
Browse files Browse the repository at this point in the history 
…manual
  • Loading branch information
@sbrannen
sbrannen committed Feb 16, 2021
1 parent 1e57e57 commit efc335e
Show file tree
Hide file tree
Showing 5 changed files with 33 additions and 427 deletions.
104 changes: 8 additions & 96 deletions src/docs/asciidoc/core/core-aop-api.adoc
View file
Expand Up @@ -25,26 +25,13 @@ target different advice with the same pointcut.
The `org.springframework.aop.Pointcut` interface is the central interface, used to
target advices to particular classes and methods. The complete interface follows:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface Pointcut {
ClassFilter getClassFilter();
MethodMatcher getMethodMatcher();
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface Pointcut {
fun getClassFilter(): ClassFilter
fun getMethodMatcher(): MethodMatcher
}
----

Expand All @@ -56,27 +43,17 @@ The `ClassFilter` interface is used to restrict the pointcut to a given set of t
classes. If the `matches()` method always returns true, all target classes are
matched. The following listing shows the `ClassFilter` interface definition:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface ClassFilter {
boolean matches(Class clazz);
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface ClassFilter {
fun matches(clazz: Class<*>): Boolean
}
----

The `MethodMatcher` interface is normally more important. The complete interface follows:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface MethodMatcher {
Expand All @@ -87,18 +64,6 @@ The `MethodMatcher` interface is normally more important. The complete interface
boolean matches(Method m, Class targetClass, Object[] args);
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface MethodMatcher {
val isRuntime: Boolean
fun matches(m: Method, targetClass: Class<*>): Boolean
fun matches(m: Method, targetClass: Class<*>, args: Array<Any>): Boolean
}
----

The `matches(Method, Class)` method is used to test whether this pointcut ever
matches a given method on a target class. This evaluation can be performed when an AOP
Expand Down Expand Up @@ -335,22 +300,13 @@ Spring is compliant with the AOP `Alliance` interface for around advice that use
interception. Classes that implement `MethodInterceptor` and that implement around advice should also implement the
following interface:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface MethodInterceptor extends Interceptor {
Object invoke(MethodInvocation invocation) throws Throwable;
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface MethodInterceptor : Interceptor {
fun invoke(invocation: MethodInvocation) : Any
}
----

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
Expand Down Expand Up @@ -413,22 +369,13 @@ interceptor chain.

The following listing shows the `MethodBeforeAdvice` interface:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface MethodBeforeAdvice extends BeforeAdvice {
void before(Method m, Object[] args, Object target) throws Throwable;
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface MethodBeforeAdvice : BeforeAdvice {
fun before(m: Method, args: Array<Any>, target: Any)
}
----

(Spring's API design would allow for
field before advice, although the usual objects apply to field interception and it is
Expand Down Expand Up @@ -591,23 +538,14 @@ TIP: Throws advice can be used with any pointcut.
An after returning advice in Spring must implement the
`org.springframework.aop.AfterReturningAdvice` interface, which the following listing shows:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface AfterReturningAdvice extends Advice {
void afterReturning(Object returnValue, Method m, Object[] args, Object target)
throws Throwable;
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface AfterReturningAdvice : Advice {
fun afterReturning(returnValue: Any, m: Method, args: Array<Any>, target: Any)
}
----

An after returning advice has access to the return value (which it cannot modify),
the invoked method, the method's arguments, and the target.
Expand Down Expand Up @@ -660,22 +598,13 @@ Spring treats introduction advice as a special kind of interception advice.
Introduction requires an `IntroductionAdvisor` and an `IntroductionInterceptor` that
implement the following interface:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface IntroductionInterceptor extends MethodInterceptor {
boolean implementsInterface(Class intf);
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface IntroductionInterceptor : MethodInterceptor {
fun implementsInterface(intf: Class<*>): Boolean
}
----

The `invoke()` method inherited from the AOP Alliance `MethodInterceptor` interface must
implement the introduction. That is, if the invoked method is on an introduced
Expand All @@ -686,8 +615,7 @@ Introduction advice cannot be used with any pointcut, as it applies only at the
rather than the method, level. You can only use introduction advice with the
`IntroductionAdvisor`, which has the following methods:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface IntroductionAdvisor extends Advisor, IntroductionInfo {
Expand All @@ -701,22 +629,6 @@ rather than the method, level. You can only use introduction advice with the
Class<?>[] getInterfaces();
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface IntroductionAdvisor : Advisor, IntroductionInfo {
val classFilter: ClassFilter
@Throws(IllegalArgumentException::class)
fun validateInterfaces()
}
interface IntroductionInfo {
val interfaces: Array<Class<*>>
}
----

There is no `MethodMatcher` and, hence, no `Pointcut` associated with introduction
advice. Only class filtering is logical.
Expand Down
92 changes: 8 additions & 84 deletions src/docs/asciidoc/core/core-beans.adoc
View file
Expand Up @@ -3406,16 +3406,10 @@ The `org.springframework.beans.factory.InitializingBean` interface lets a bean
perform initialization work after the container has set all necessary properties on the
bean. The `InitializingBean` interface specifies a single method:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
void afterPropertiesSet() throws Exception;
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
fun afterPropertiesSet()
----

We recommend that you do not use the `InitializingBean` interface, because it
unnecessarily couples the code to Spring. Alternatively, we suggest using
Expand Down Expand Up @@ -3491,16 +3485,10 @@ Implementing the `org.springframework.beans.factory.DisposableBean` interface le
bean get a callback when the container that contains it is destroyed. The
`DisposableBean` interface specifies a single method:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
void destroy() throws Exception;
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
fun destroy()
----

We recommend that you do not use the `DisposableBean` callback interface, because it
unnecessarily couples the code to Spring. Alternatively, we suggest using
Expand Down Expand Up @@ -3711,8 +3699,7 @@ Destroy methods are called in the same order:
The `Lifecycle` interface defines the essential methods for any object that has its own
lifecycle requirements (such as starting and stopping some background process):

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface Lifecycle {
Expand All @@ -3723,27 +3710,14 @@ lifecycle requirements (such as starting and stopping some background process):
boolean isRunning();
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface Lifecycle {
fun start()
fun stop()
val isRunning: Boolean
}
----

Any Spring-managed object may implement the `Lifecycle` interface. Then, when the
`ApplicationContext` itself receives start and stop signals (for example, for a stop/restart
scenario at runtime), it cascades those calls to all `Lifecycle` implementations
defined within that context. It does this by delegating to a `LifecycleProcessor`, shown
in the following listing:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface LifecycleProcessor extends Lifecycle {
Expand All @@ -3752,16 +3726,6 @@ in the following listing:
void onClose();
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface LifecycleProcessor : Lifecycle {
fun onRefresh()
fun onClose()
}
----

Notice that the `LifecycleProcessor` is itself an extension of the `Lifecycle`
interface. It also adds two other methods for reacting to the context being refreshed
Expand All @@ -3788,27 +3752,17 @@ prior to objects of another type. In those cases, the `SmartLifecycle` interface
another option, namely the `getPhase()` method as defined on its super-interface,
`Phased`. The following listing shows the definition of the `Phased` interface:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface Phased {
int getPhase();
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface Phased {
val phase: Int
}
----

The following listing shows the definition of the `SmartLifecycle` interface:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface SmartLifecycle extends Lifecycle, Phased {
Expand All @@ -3817,16 +3771,6 @@ The following listing shows the definition of the `SmartLifecycle` interface:
void stop(Runnable callback);
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface SmartLifecycle : Lifecycle, Phased {
val isAutoStartup: Boolean
fun stop(callback: Runnable)
}
----

When starting, the objects with the lowest phase start first. When stopping, the
reverse order is followed. Therefore, an object that implements `SmartLifecycle` and
Expand Down Expand Up @@ -3938,23 +3882,13 @@ When an `ApplicationContext` creates an object instance that implements the
with a reference to that `ApplicationContext`. The following listing shows the definition
of the `ApplicationContextAware` interface:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface ApplicationContextAware {
void setApplicationContext(ApplicationContext applicationContext) throws BeansException;
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface ApplicationContextAware {
@Throws(BeansException::class)
fun setApplicationContext(applicationContext: ApplicationContext)
}
----

Thus, beans can programmatically manipulate the `ApplicationContext` that created them,
through the `ApplicationContext` interface or by casting the reference to a known
Expand Down Expand Up @@ -3983,23 +3917,13 @@ When an `ApplicationContext` creates a class that implements the
a reference to the name defined in its associated object definition. The following listing
shows the definition of the BeanNameAware interface:

[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface BeanNameAware {
void setBeanName(String name) throws BeansException;
}
----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
interface BeanNameAware {
@Throws(BeansException::class)
fun setBeanName(name: String)
}
----

The callback is invoked after population of normal bean properties but before an
initialization callback such as `InitializingBean`, `afterPropertiesSet`, or a custom
Expand Down

0 comments on commit efc335e

Please sign in to comment.