Remove admonitions surrounding code snippets

This commit is contained in:
Brian Clozel
2018-11-26 23:15:55 +01:00
parent 8c768e48fa
commit 33cbe2e77a
29 changed files with 139 additions and 3191 deletions

View File

@@ -42,7 +42,6 @@ Note that this interface is defined in plain Java. Dependent objects that are
injected with a reference to the `Messenger` do not know that the underlying
implementation is a Groovy script. The following listing shows the `Messenger` interface:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -54,11 +53,9 @@ implementation is a Groovy script. The following listing shows the `Messenger` i
}
----
====
The following example defines a class that has a dependency on the `Messenger` interface:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -78,11 +75,9 @@ The following example defines a class that has a dependency on the `Messenger` i
}
----
====
The following example implements the `Messenger` interface in Groovy:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -99,7 +94,6 @@ The following example implements the `Messenger` interface in Groovy:
}
----
====
[NOTE]
====
@@ -118,7 +112,6 @@ Finally, the following example shows the bean definitions that effect the inject
Groovy-defined `Messenger` implementation into an instance of the
`DefaultBookingService` class:
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -141,7 +134,6 @@ Groovy-defined `Messenger` implementation into an instance of the
</beans>
----
====
The `bookingService` bean (a `DefaultBookingService`) can now use its private
`messenger` member variable as normal, because the `Messenger` instance that was injected
@@ -244,7 +236,6 @@ So, if we stick with <<dynamic-language-a-first-example,the example>> from earli
chapter, the following example shows what we would change in the Spring XML configuration to effect
refreshable beans:
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -263,7 +254,6 @@ refreshable beans:
</beans>
----
====
That really is all you have to do. The `refresh-check-delay` attribute defined on the
`messenger` bean definition is the number of milliseconds after which the bean is
@@ -281,7 +271,6 @@ the program resumes execution.
The following listing shows this sample application:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -301,14 +290,12 @@ The following listing shows this sample application:
}
}
----
====
Assume then, for the purposes of this example, that all calls to the
`getMessage()` method of `Messenger` implementations have to be changed such that the
message is surrounded by quotation marks. The following listing shows the changes that you (the developer) should make to the
`Messenger.groovy` source file when the execution of the program is paused:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -328,7 +315,6 @@ message is surrounded by quotation marks. The following listing shows the change
}
}
----
====
When the program runs, the output before the input pause will be `I Can Do The
Frug`. After the change to the source file is made and saved and the program resumes
@@ -363,7 +349,6 @@ embedded directly in Spring bean definitions. More specifically, the
inside a Spring configuration file. An example might clarify how the inline script
feature works:
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -382,7 +367,6 @@ feature works:
<lang:property name="message" value="I Can Do The Frug" />
</lang:groovy>
----
====
If we put to one side the issues surrounding whether it is good practice to define
dynamic language source inside a Spring configuration file, the `<lang:inline-script/>`
@@ -404,7 +388,6 @@ constructors and properties 100% clear, the following mixture of code and config
does not work:
.An approach that cannot work
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -443,7 +426,6 @@ does not work:
</lang>
----
====
In practice this limitation is not as significant as it first appears, since setter
injection is the injection style favored by the overwhelming majority of developers
@@ -477,7 +459,6 @@ If you have read this chapter straight from the top, you have already
<<dynamic-language-a-first-example,seen an example>> of a Groovy-dynamic-language-backed
bean. Now consider another example (again using an example from the Spring test suite):
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -489,11 +470,9 @@ bean. Now consider another example (again using an example from the Spring test
}
----
====
The following example implements the `Calculator` interface in Groovy:
====
[source,groovy,indent=0]
[subs="verbatim,quotes"]
----
@@ -508,11 +487,9 @@ The following example implements the `Calculator` interface in Groovy:
}
----
====
The following bean definition uses the calculator defined in Groovy:
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -521,11 +498,9 @@ The following bean definition uses the calculator defined in Groovy:
<lang:groovy id="calculator" script-source="classpath:calculator.groovy"/>
</beans>
----
====
Finally, the following small application exercises the preceding configuration:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -543,7 +518,6 @@ Finally, the following small application exercises the preceding configuration:
}
}
----
====
The resulting output from running the above program is (unsurprisingly) `10`.
(For more interesting examples,
@@ -566,7 +540,6 @@ implementations of this interface could invoke any required initialization metho
set some default property values, or specify a custom `MetaClass`. The following listing
shows the `GroovyObjectCustomizer` interface definition:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -575,7 +548,6 @@ shows the `GroovyObjectCustomizer` interface definition:
void customize(GroovyObject goo);
}
----
====
The Spring Framework instantiates an instance of your Groovy-backed bean and
then passes the created `GroovyObject` to the specified `GroovyObjectCustomizer` (if one
@@ -583,7 +555,6 @@ has been defined). You can do whatever you like with the supplied `GroovyObject`
reference. We expect that most people want to set a custom `MetaClass` with this callback,
and the following example shows how to do so:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -603,7 +574,6 @@ and the following example shows how to do so:
}
----
====
A full discussion of meta-programming in Groovy is beyond the scope of the Spring
reference manual. See the relevant section of the Groovy reference manual or do a
@@ -611,7 +581,6 @@ search online. Plenty of articles address this topic. Actually, making use
of a `GroovyObjectCustomizer` is easy if you use the Spring namespace support, as the
following example shows:
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -623,12 +592,10 @@ following example shows:
script-source="classpath:org/springframework/scripting/groovy/Calculator.groovy"
customizer-ref="tracingCustomizer"/>
----
====
If you do not use the Spring namespace support, you can still use the
`GroovyObjectCustomizer` functionality, as the following example shows:
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -642,7 +609,6 @@ If you do not use the Spring namespace support, you can still use the
<bean class="org.springframework.scripting.support.ScriptFactoryPostProcessor"/>
----
====
NOTE: As of Spring Framework 4.3.3, you may also specify a Groovy `CompilationCustomizer`
(such as an `ImportCustomizer`) or even a full Groovy `CompilerConfiguration` object
@@ -684,7 +650,6 @@ Now we can show a fully working example of using a BeanShell-based bean that imp
the `Messenger` interface that was defined earlier in this chapter. We again show the
definition of the `Messenger` interface:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -696,12 +661,10 @@ definition of the `Messenger` interface:
}
----
====
The following example shows the BeanShell "`implementation`" (we use the term loosely here) of the
`Messenger` interface:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -715,12 +678,10 @@ The following example shows the BeanShell "`implementation`" (we use the term lo
message = aMessage;
}
----
====
The following example shows the Spring XML that defines an "`instance`" of the above "`class`" (again,
we use these terms very loosely here):
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -730,7 +691,6 @@ we use these terms very loosely here):
<lang:property name="message" value="Hello World!" />
</lang:bsh>
----
====
See <<dynamic-language-scenarios>> for some scenarios where you might want to use
BeanShell-based beans.
@@ -773,7 +733,6 @@ beans, you have to enable the "`refreshable beans`" functionality. See
The following example shows an `org.springframework.web.servlet.mvc.Controller` implemented
by using the Groovy dynamic language:
====
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -809,7 +768,6 @@ by using the Groovy dynamic language:
<lang:property name="fortuneService" ref="fortuneService"/>
</lang:groovy>
----
====
@@ -836,7 +794,6 @@ by using the Groovy dynamic language (see <<core.adoc#validator,
Validation using Springs Validator interface>> for a discussion of the
`Validator` interface):
====
[source,groovy,indent=0]
[subs="verbatim,quotes"]
----
@@ -859,7 +816,6 @@ Validation using Springs Validator interface>> for a discussion of the
}
----
====
@@ -899,7 +855,6 @@ with "`regular`" beans.)
The following example uses the `scope` attribute to define a Groovy bean scoped as
a <<core.adoc#beans-factory-scopes-prototype,prototype>>:
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -920,7 +875,6 @@ a <<core.adoc#beans-factory-scopes-prototype,prototype>>:
</beans>
----
====
See <<core.adoc#beans-factory-scopes,Bean scopes>> in <<core.adoc#beans,The IoC container>>
for a full discussion of the scoping support in the Spring Framework.
@@ -943,7 +897,6 @@ the following preamble at the top of your Spring XML configuration file. The tex
following snippet references the correct schema so that the tags in the `lang` namespace
are available to you:
====
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -958,7 +911,6 @@ are available to you:
</beans>
----
====

View File

@@ -56,23 +56,19 @@ for their APIs, thus giving a better Kotlin development experience overall.
To retrieve a list of `User` objects in Java, you would normally write the following:
====
[source,java,indent=0]
----
Flux<User> users = client.get().retrieve().bodyToFlux(User.class)
----
====
With Kotlin and the Spring Framework extensions, you can instead write the following:
====
[source,kotlin,indent=0]
----
val users = client.get().retrieve().bodyToFlux<User>()
// or (both are equivalent)
val users : Flux<User> = client.get().retrieve().bodyToFlux()
----
====
As in Java, `users` in Kotlin is strongly typed, but Kotlin's clever type inference allows
for shorter syntax.
@@ -176,7 +172,6 @@ This mechanism is very efficient, as it does not require any reflection or CGLIB
In Java, you can, for example, write the following:
====
[source,java,indent=0]
----
GenericApplicationContext context = new GenericApplicationContext();
@@ -184,12 +179,10 @@ In Java, you can, for example, write the following:
context.registerBean(Bar.class, () -> new Bar(context.getBean(Foo.class))
);
----
====
In Kotlin, with reified type parameters and `GenericApplicationContext`
Kotlin extensions, you can instead write the following:
====
[source,kotlin,indent=0]
----
val context = GenericApplicationContext().apply {
@@ -197,7 +190,6 @@ Kotlin extensions, you can instead write the following:
registerBean { Bar(it.getBean<Foo>()) }
}
----
====
In order to allow a more declarative approach and cleaner syntax, Spring Framework provides
a {doc-root}/spring-framework/docs/{spring-version}/kdoc-api/spring-framework/org.springframework.context.support/-bean-definition-dsl/[Kotlin bean definition DSL]
@@ -205,7 +197,6 @@ It declares an `ApplicationContextInitializer` through a clean declarative API,
which lets you deal with profiles and `Environment` for customizing
how beans are registered. The following example creates a `Play` profile:
====
[source,kotlin,indent=0]
----
fun beans() = beans {
@@ -237,7 +228,6 @@ how beans are registered. The following example creates a `Play` profile:
}
}
----
====
In the preceding example, `bean<Routes>()` uses autowiring by constructor, and `ref<Routes>()`
is a shortcut for `applicationContext.getBean(Routes::class.java)`.
@@ -245,7 +235,6 @@ is a shortcut for `applicationContext.getBean(Routes::class.java)`.
You can then use this `beans()` function to register beans on the application context,
as the following example shows:
====
[source,kotlin,indent=0]
----
val context = GenericApplicationContext().apply {
@@ -253,7 +242,6 @@ as the following example shows:
refresh()
}
----
====
NOTE: This DSL is programmatic, meaning it allows custom registration logic of beans
through an `if` expression, a `for` loop, or any other Kotlin constructs.
@@ -281,7 +269,6 @@ Spring Framework now comes with a
that lets you use the <<web-reactive#webflux-fn,WebFlux functional
API>> to write clean and idiomatic Kotlin code, as the following example shows:
====
[source,kotlin,indent=0]
----
router {
@@ -301,7 +288,6 @@ API>> to write clean and idiomatic Kotlin code, as the following example shows:
resources("/**", ClassPathResource("static/"))
}
----
====
NOTE: This DSL is programmatic, meaning that it allows custom registration logic of beans
through an `if` expression, a `for` loop, or any other Kotlin constructs. That can be useful when you need to register routes
@@ -330,7 +316,6 @@ https://github.com/Kotlin/kotlinx.html[kotlinx.html] DSL or by a using Kotlin mu
This can let you write Kotlin templates with full autocompletion and
refactoring support in a supported IDE, as the following example shows:
====
[source,kotlin,indent=0]
----
import io.spring.demo.*
@@ -344,7 +329,6 @@ refactoring support in a supported IDE, as the following example shows:
${include("footer")}
"""
----
====
See the https://github.com/sdeleuze/kotlin-script-templating[kotlin-script-templating] example
project for more details.
@@ -399,12 +383,10 @@ you can write your Kotlin beans without any additional `open` keyword, as in Jav
In Kotlin, it is convenient and considered to be a best practice to declare read-only properties
within the primary constructor, as in the following example:
====
[source,kotlin,indent=0]
----
class Person(val name: String, val age: Int)
----
====
You can optionally add https://kotlinlang.org/docs/reference/data-classes.html[the `data` keyword]
to make the compiler automatically derive the following members from all properties declared
@@ -417,7 +399,6 @@ in the primary constructor:
As the following example shows, this allows for easy changes to individual properties, even if `Person` properties are read-only:
====
[source,kotlin,indent=0]
----
data class Person(val name: String, val age: Int)
@@ -425,7 +406,6 @@ As the following example shows, this allows for easy changes to individual prope
val jack = Person(name = "Jack", age = 1)
val olderJack = jack.copy(age = 2)
----
====
Common persistence technologies (such as JPA) require a default constructor, preventing this
kind of design. Fortunately, there is now a workaround for this
@@ -448,7 +428,6 @@ mappings (such as MongoDB, Redis, Cassandra, and others).
Our recommendation is to try and favor constructor injection with `val` read-only (and non-nullable when possible)
https://kotlinlang.org/docs/reference/properties.html[properties], as the following example shows:
====
[source,kotlin,indent=0]
----
@Component
@@ -457,7 +436,6 @@ https://kotlinlang.org/docs/reference/properties.html[properties], as the follow
private val solrClient: SolrClient
)
----
====
NOTE: As of Spring Framework 4.3, classes with a single constructor have their
parameters automatically autowired, that's why there is no need for an
@@ -466,7 +444,6 @@ explicit `@Autowired constructor` in the example shown above.
If you really need to use field injection, you can use the `lateinit var` construct,
as the following example shows:
====
[source,kotlin,indent=0]
----
@Component
@@ -479,7 +456,6 @@ as the following example shows:
lateinit var solrClient: SolrClient
}
----
====
@@ -494,7 +470,6 @@ character by writing `@Value("\${property}")`.
As an alternative, you can customize the properties placeholder prefix by declaring
the following configuration beans:
====
[source,kotlin,indent=0]
----
@Bean
@@ -502,12 +477,10 @@ the following configuration beans:
setPlaceholderPrefix("%{")
}
----
====
You can customize existing code (such as Spring Boot actuators or `@LocalServerPort`) that uses the `${...}` syntax,
with configuration beans, as the following example shows:
====
[source,kotlin,indent=0]
----
@Bean
@@ -519,7 +492,6 @@ with configuration beans, as the following example shows:
@Bean
fun defaultPropertyConfigurer() = PropertySourcesPlaceholderConfigurer()
----
====
NOTE: If you use Spring Boot, you can use
https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-typesafe-configuration-properties[`@ConfigurationProperties`]
@@ -543,7 +515,6 @@ specify it as a `vararg` parameter.
To understand what that means, consider `@RequestMapping` (which is one
of the most widely used Spring annotations) as an example. This Java annotation is declared as follows:
====
[source,java,indent=0]
----
public @interface RequestMapping {
@@ -559,7 +530,6 @@ of the most widely used Spring annotations) as an example. This Java annotation
// ...
}
----
====
The typical use case for `@RequestMapping` is to map a handler method to a specific path
and method. In Java, you can specify a single value for the
@@ -600,7 +570,6 @@ You can now change the default behavior to `PER_CLASS` thanks to a
The following example `@BeforeAll` and `@AfterAll` annotations on non-static methods:
====
[source]
----
class IntegrationTests {
@@ -630,7 +599,6 @@ class IntegrationTests {
}
}
----
====
@@ -639,7 +607,6 @@ class IntegrationTests {
You can create specification-like tests with JUnit 5 and Kotlin.
The following example shows how to do so:
====
[source]
----
class SpecificationLikeTests {
@@ -663,7 +630,6 @@ class SpecificationLikeTests {
}
}
----
====