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

Merge source and substitution configuration in reference docs 

Closes gh-25545
This commit is contained in:
diguage 2020-08-06 10:16:26 +08:00 committed by Sam Brannen
parent ee41ebc1ab
commit eab61f692f
12 changed files with 290 additions and 580 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/docs/asciidoc/core/core-appendix.adoc
View File

@ -682,8 +682,7 @@ XML extension (a custom XML element) that lets us configure objects of the type
`SimpleDateFormat` (from the `java.text` package). When we are done,
we will be able to define bean definitions of type `SimpleDateFormat` as follows:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<myns:dateformat id="dateFormat"
pattern="yyyy-MM-dd HH:mm"

12
src/docs/asciidoc/core/core-beans.adoc
View File

@ -135,8 +135,7 @@ dependency-inject domain objects with Spring>>.
The following example shows the basic structure of XML-based configuration metadata:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
@ -1980,8 +1979,7 @@ then nested `constructor-arg` elements.
The following example uses the `c:` namespace to do the same thing as the from
<<beans-constructor-injection>>:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -3428,8 +3426,7 @@ you can use the `init-method` attribute to specify the name of the method that h
no-argument signature. With Java configuration, you can use the `initMethod` attribute of
`@Bean`. See <<beans-java-lifecycle-callbacks>>. Consider the following example:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="exampleInitBean" class="examples.ExampleBean" init-method="init"/>
----
@ -7852,8 +7849,7 @@ To enable component scanning, you can annotate your `@Configuration` class as fo
Experienced Spring users may be familiar with the XML declaration equivalent from
Spring's `context:` namespace, shown in the following example:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<beans>
<context:component-scan base-package="com.acme"/>

3
src/docs/asciidoc/data-access.adoc
View File

@ -8844,8 +8844,7 @@ You can configure marshallers more concisely by using tags from the OXM namespac
To make these tags available, you must first reference the appropriate schema in the
preamble of the XML configuration file. The following example shows how to do so:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"

6
src/docs/asciidoc/data-access/data-access-appendix.adoc
View File

@ -32,8 +32,7 @@ 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 `tx` namespace
are available to you:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
@ -72,8 +71,7 @@ To use the elements in the `jdbc` schema, you need to have the following preambl
top of your Spring XML configuration file. The text in the following snippet references
the correct schema so that the elements in the `jdbc` namespace are available to you:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"

525
src/docs/asciidoc/integration.adoc
View File

File diff suppressed because it is too large Load Diff

51
src/docs/asciidoc/integration/integration-appendix.adoc
View File

@ -20,8 +20,7 @@ To use the elements in the `jee` schema, you need to have the following preamble
of your Spring XML configuration file. The text in the following snippet references the
correct schema so that the elements in the `jee` namespace are available to you:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
@ -43,8 +42,7 @@ correct schema so that the elements in the `jee` namespace are available to you:
The following example shows how to use JNDI to look up a data source without the `jee` schema:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="dataSource" class="org.springframework.jndi.JndiObjectFactoryBean">
<property name="jndiName" value="jdbc/MyDataSource"/>
@ -58,8 +56,7 @@ The following example shows how to use JNDI to look up a data source without the
The following example shows how to use JNDI to look up a data source with the `jee`
schema:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<jee:jndi-lookup id="dataSource" jndi-name="jdbc/MyDataSource"/>
@ -77,8 +74,7 @@ schema:
The following example shows how to use JNDI to look up an environment variable without
`jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
<property name="jndiName" value="jdbc/MyDataSource"/>
@ -92,8 +88,7 @@ The following example shows how to use JNDI to look up an environment variable w
The following example shows how to use JNDI to look up an environment variable with `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<jee:jndi-lookup id="simple" jndi-name="jdbc/MyDataSource">
<jee:environment>ping=pong</jee:environment>
@ -107,8 +102,7 @@ The following example shows how to use JNDI to look up an environment variable w
The following example shows how to use JNDI to look up multiple environment variables
without `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
<property name="jndiName" value="jdbc/MyDataSource"/>
@ -124,8 +118,7 @@ without `jee`:
The following example shows how to use JNDI to look up multiple environment variables with
`jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<jee:jndi-lookup id="simple" jndi-name="jdbc/MyDataSource">
<!-- newline-separated, key-value pairs for the environment (standard Properties format) -->
@ -143,8 +136,7 @@ The following example shows how to use JNDI to look up multiple environment vari
The following example shows how to use JNDI to look up a data source and a number of
different properties without `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
<property name="jndiName" value="jdbc/MyDataSource"/>
@ -159,8 +151,7 @@ different properties without `jee`:
The following example shows how to use JNDI to look up a data source and a number of
different properties with `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<jee:jndi-lookup id="simple"
jndi-name="jdbc/MyDataSource"
@ -181,8 +172,7 @@ The `<jee:local-slsb/>` element configures a reference to a local EJB Stateless
The following example shows how to configures a reference to a local EJB Stateless Session Bean
without `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="simple"
class="org.springframework.ejb.access.LocalStatelessSessionProxyFactoryBean">
@ -194,8 +184,7 @@ without `jee`:
The following example shows how to configures a reference to a local EJB Stateless Session Bean
with `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<jee:local-slsb id="simpleSlsb" jndi-name="ejb/RentalServiceBean"
business-interface="com.foo.service.RentalService"/>
@ -211,8 +200,7 @@ The `<jee:local-slsb/>` element configures a reference to a local EJB Stateless
The following example shows how to configures a reference to a local EJB Stateless Session Bean
and a number of properties without `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="complexLocalEjb"
class="org.springframework.ejb.access.LocalStatelessSessionProxyFactoryBean">
@ -227,8 +215,7 @@ and a number of properties without `jee`:
The following example shows how to configures a reference to a local EJB Stateless Session Bean
and a number of properties with `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<jee:local-slsb id="complexLocalEjb"
jndi-name="ejb/RentalServiceBean"
@ -247,8 +234,7 @@ The `<jee:remote-slsb/>` element configures a reference to a `remote` EJB Statel
The following example shows how to configures a reference to a remote EJB Stateless Session Bean
without `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="complexRemoteEjb"
class="org.springframework.ejb.access.SimpleRemoteStatelessSessionProxyFactoryBean">
@ -265,8 +251,7 @@ without `jee`:
The following example shows how to configures a reference to a remote EJB Stateless Session Bean
with `jee`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<jee:remote-slsb id="complexRemoteEjb"
jndi-name="ejb/MyRemoteBean"
@ -294,8 +279,7 @@ the following preamble at the top of your Spring XML configuration file. The tex
following snippet references the correct schema so that the elements in the `jms` namespace
are available to you:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
@ -332,8 +316,7 @@ To use the elements in the `cache` schema, you need to have the following preamb
top of your Spring XML configuration file. The text in the following snippet references
the correct schema so that the elements in the `cache` namespace are available to you:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"

78
src/docs/asciidoc/languages/dynamic-languages.adoc
View File

@ -33,8 +33,7 @@ implement. Note that this interface is defined in plain Java. Dependent objects
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"]
[source,java,indent=0,subs="verbatim,quotes"]
----
package org.springframework.scripting;
@ -46,8 +45,7 @@ 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"]
[source,java,indent=0,subs="verbatim,quotes"]
----
package org.springframework.scripting;
@ -67,8 +65,7 @@ The following example defines a class that has a dependency on the `Messenger` i
The following example implements the `Messenger` interface in Groovy:
[source,groovy,indent=0]
[subs="verbatim,quotes"]
[source,groovy,indent=0,subs="verbatim,quotes"]
----
// from the file 'Messenger.groovy'
package org.springframework.scripting.groovy;
@ -100,8 +97,7 @@ 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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -221,8 +217,7 @@ if we stick with <<dynamic-language-a-first-example, the example>> from earlier
this 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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<beans>
@ -256,8 +251,7 @@ on the dynamic-language-backed bean when the program resumes execution.
The following listing shows this sample application:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
@ -282,8 +276,7 @@ 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,groovy,indent=0]
[subs="verbatim,quotes"]
[source,groovy,indent=0,subs="verbatim,quotes"]
----
package org.springframework.scripting
@ -333,8 +326,7 @@ 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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<lang:groovy id="messenger">
<lang:inline-script>
@ -371,8 +363,7 @@ constructors and properties 100% clear, the following mixture of code and config
does not work:
.An approach that cannot work
[source,groovy,indent=0]
[subs="verbatim,quotes"]
[source,groovy,indent=0,subs="verbatim,quotes"]
----
// from the file 'Messenger.groovy'
package org.springframework.scripting.groovy;
@ -394,8 +385,7 @@ does not work:
}
----
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<lang:groovy id="badMessenger"
script-source="classpath:Messenger.groovy">
@ -430,8 +420,7 @@ 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"]
[source,java,indent=0,subs="verbatim,quotes"]
----
package org.springframework.scripting;
@ -443,8 +432,7 @@ 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"]
[source,groovy,indent=0,subs="verbatim,quotes"]
----
// from the file 'calculator.groovy'
package org.springframework.scripting.groovy
@ -459,8 +447,7 @@ 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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<!-- from the file 'beans.xml' -->
<beans>
@ -470,8 +457,7 @@ The following bean definition uses the calculator defined in Groovy:
Finally, the following small application exercises the preceding configuration:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
package org.springframework.scripting;
@ -507,8 +493,7 @@ 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"]
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface GroovyObjectCustomizer {
@ -522,8 +507,7 @@ 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"]
[source,java,indent=0,subs="verbatim,quotes"]
----
public final class SimpleMethodTracingCustomizer implements GroovyObjectCustomizer {
@ -548,8 +532,7 @@ 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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<!-- define the GroovyObjectCustomizer just like any other bean -->
<bean id="tracingCustomizer" class="example.SimpleMethodTracingCustomizer"/>
@ -563,8 +546,7 @@ following example shows:
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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="calculator" class="org.springframework.scripting.groovy.GroovyScriptFactory">
<constructor-arg value="classpath:org/springframework/scripting/groovy/Calculator.groovy"/>
@ -614,8 +596,7 @@ 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"]
[source,java,indent=0,subs="verbatim,quotes"]
----
package org.springframework.scripting;
@ -628,8 +609,7 @@ 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"]
[source,java,indent=0,subs="verbatim,quotes"]
----
String message;
@ -645,8 +625,7 @@ of the `Messenger` interface:
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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<lang:bsh id="messageService" script-source="classpath:BshMessenger.bsh"
script-interfaces="org.springframework.scripting.Messenger">
@ -697,8 +676,7 @@ 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,groovy,indent=0]
[subs="verbatim,quotes"]
[source,groovy,indent=0,subs="verbatim,quotes"]
----
// from the file '/WEB-INF/groovy/FortuneController.groovy'
package org.springframework.showcase.fortune.web
@ -722,8 +700,7 @@ by using the Groovy dynamic language:
}
----
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<lang:groovy id="fortune"
refresh-check-delay="3000"
@ -756,8 +733,7 @@ implemented by using the Groovy dynamic language (see <<core.adoc#validator,
Validation using Spring’s Validator interface>> for a discussion of the
`Validator` interface):
[source,groovy,indent=0]
[subs="verbatim,quotes"]
[source,groovy,indent=0,subs="verbatim,quotes"]
----
import org.springframework.validation.Validator
import org.springframework.validation.Errors
@ -815,8 +791,7 @@ as it is 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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -855,8 +830,7 @@ To use the elements in the `lang` schema, you need to have the following preambl
top of your Spring XML configuration file. The text in the 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"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"

6
src/docs/asciidoc/testing.adoc
View File

@ -4954,8 +4954,7 @@ The preceding code listings use the same XML context file referenced by the
`@ContextConfiguration` annotation (that is, `repository-config.xml`). The following
shows this configuration:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
@ -5116,8 +5115,7 @@ need to configure a theme in the mock session managed by the TestContext framewo
following example shows how to do so:
.Session-scoped bean configuration
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<beans>

15
src/docs/asciidoc/web/integration.adoc
View File

@ -42,8 +42,7 @@ set of Spring XML configuration files to load.
Consider the following `<listener/>` configuration:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
@ -52,8 +51,7 @@ Consider the following `<listener/>` configuration:
Further consider the following `<context-param/>` configuration:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<context-param>
<param-name>contextConfigLocation</param-name>
@ -74,8 +72,7 @@ created by the `ContextLoaderListener`.
The following example shows how to get the `WebApplicationContext`:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
WebApplicationContext ctx = WebApplicationContextUtils.getWebApplicationContext(servletContext);
----
@ -128,8 +125,7 @@ default resolver of the underlying JSF implementation.
Configuration-wise, you can define `SpringBeanFacesELResolver` in your JSF
`faces-context.xml` file, as the following example shows:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<faces-config>
<application>
@ -152,8 +148,7 @@ it takes a `FacesContext` parameter rather than a `ServletContext` parameter.
The following example shows how to use `FacesContextUtils`:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
ApplicationContext ctx = FacesContextUtils.getWebApplicationContext(FacesContext.getCurrentInstance());
----

3
src/docs/asciidoc/web/webmvc-view.adoc
View File

@ -905,8 +905,7 @@ called `spring-form.tld`.
To use the tags from this library, add the following directive to the top of your JSP
page:
[source,xml,indent=0]
[subs="verbatim,quotes"]
[source,xml,indent=0,subs="verbatim,quotes"]
----
<%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %>
----

6
src/docs/asciidoc/web/websocket-intro.adoc
View File

@ -10,8 +10,7 @@ A WebSocket interaction begins with an HTTP request that uses the HTTP `Upgrade`
to upgrade or, in this case, to switch to the WebSocket protocol. The following example
shows such an interaction:
[source,yaml,indent=0]
[subs="verbatim,quotes"]
[source,yaml,indent=0,subs="verbatim,quotes"]
----
GET /spring-websocket-portfolio/portfolio HTTP/1.1
Host: localhost:8080
@ -29,8 +28,7 @@ shows such an interaction:
Instead of the usual 200 status code, a server with WebSocket support returns output
similar to the following:
[source,yaml,indent=0]
[subs="verbatim,quotes"]
[source,yaml,indent=0,subs="verbatim,quotes"]
----
HTTP/1.1 101 Switching Protocols <1>
Upgrade: websocket

162
src/docs/asciidoc/web/websocket.adoc
View File

@ -29,8 +29,7 @@ Creating a WebSocket server is as simple as implementing `WebSocketHandler` or,
likely, extending either `TextWebSocketHandler` or `BinaryWebSocketHandler`. The following
example uses `TextWebSocketHandler`:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
import org.springframework.web.socket.WebSocketHandler;
import org.springframework.web.socket.WebSocketSession;
@ -49,8 +48,7 @@ example uses `TextWebSocketHandler`:
There is dedicated WebSocket Java configuration and XML namespace support for mapping the preceding
WebSocket handler to a specific URL, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
import org.springframework.web.socket.config.annotation.EnableWebSocket;
import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
@ -75,8 +73,7 @@ WebSocket handler to a specific URL, as the following example shows:
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -120,8 +117,7 @@ You can use such an interceptor to preclude the handshake or to make any attribu
available to the `WebSocketSession`. The following example uses a built-in interceptor
to pass HTTP session attributes to the WebSocket session:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocket
@ -138,8 +134,7 @@ to pass HTTP session attributes to the WebSocket session:
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -218,8 +213,7 @@ upgrade to a Servlet container version with JSR-356 support, it should
be possible to selectively enable or disable web fragments (and SCI scanning)
through the use of the `<absolute-ordering />` element in `web.xml`, as the following example shows:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -237,8 +231,7 @@ You can then selectively enable web fragments by name, such as Spring's own
`SpringServletContainerInitializer` that provides support for the Servlet 3
Java initialization API. The following example shows how to do so:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -267,8 +260,7 @@ and others.
For Tomcat, WildFly, and GlassFish, you can add a `ServletServerContainerFactoryBean` to your
WebSocket Java config, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocket
@ -287,8 +279,7 @@ WebSocket Java config, as the following example shows:
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -314,8 +305,7 @@ For Jetty, you need to supply a pre-configured Jetty `WebSocketServerFactory` an
that into Spring's `DefaultHandshakeHandler` through your WebSocket Java config.
The following example shows how to do so:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocket
@ -343,8 +333,7 @@ The following example shows how to do so:
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -408,8 +397,7 @@ The three possible behaviors are:
You can configure WebSocket and SockJS allowed origins, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
import org.springframework.web.socket.config.annotation.EnableWebSocket;
import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
@ -434,8 +422,7 @@ You can configure WebSocket and SockJS allowed origins, as the following example
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -544,8 +531,7 @@ https://sockjs.github.io/sockjs-protocol/sockjs-protocol-0.3.3.html[narrated tes
You can enable SockJS through Java configuration, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocket
@ -566,8 +552,7 @@ You can enable SockJS through Java configuration, as the following example shows
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -658,8 +643,7 @@ a URL from the same origin as the application.
The following example shows how to do so in Java configuration:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -787,8 +771,7 @@ to the server. At present there are two implementations:
The following example shows how to create a SockJS client and connect to a SockJS endpoint:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
List<Transport> transports = new ArrayList<>(2);
transports.add(new WebSocketTransport(new StandardWebSocketClient()));
@ -806,8 +789,7 @@ To use `SockJsClient` to simulate a large number of concurrent users, you
need to configure the underlying HTTP client (for XHR transports) to allow a sufficient
number of connections and threads. The following example shows how to do so with Jetty:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
HttpClient jettyHttpClient = new HttpClient();
jettyHttpClient.setMaxConnectionsPerDestination(1000);
@ -817,8 +799,7 @@ jettyHttpClient.setExecutor(new QueuedThreadPool(1000));
The following example shows the server-side SockJS-related properties (see javadoc for details)
that you should also consider customizing:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
public class WebSocketConfig extends WebSocketMessageBrokerConfigurationSupport {
@ -978,8 +959,7 @@ STOMP over WebSocket support is available in the `spring-messaging` and
`spring-websocket` modules. Once you have those dependencies, you can expose a STOMP
endpoints, over WebSocket with <<websocket-fallback>>, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
@ -1011,8 +991,7 @@ route messages whose destination header begins with `/topic `or `/queue` to the
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -1048,8 +1027,7 @@ https://github.com/JSteunou/webstomp-client[JSteunou/webstomp-client] is the mos
actively maintained and evolving successor of that library. The following example code
is based on it:
[source,javascript,indent=0]
[subs="verbatim,quotes"]
[source,javascript,indent=0,subs="verbatim,quotes"]
----
var socket = new SockJS("/spring-websocket-portfolio/portfolio");
var stompClient = webstomp.over(socket);
@ -1060,8 +1038,7 @@ is based on it:
Alternatively, if you connect through WebSocket (without SockJS), you can use the following code:
[source,javascript,indent=0]
[subs="verbatim,quotes"]
[source,javascript,indent=0,subs="verbatim,quotes"]
----
var socket = new WebSocket("/spring-websocket-portfolio/portfolio");
var stompClient = Stomp.over(socket);
@ -1091,8 +1068,7 @@ To configure the underlying WebSocket server, the information in
<<websocket-server-runtime-configuration>> applies. For Jetty, however you need to set
the `HandshakeHandler` and `WebSocketPolicy` through the `StompEndpointRegistry`:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -1180,8 +1156,7 @@ to broadcast to subscribed clients.
We can trace the flow through a simple example. Consider the following example, which sets up a server:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -1358,8 +1333,7 @@ when a subscription is stored and ready for broadcasts, a client should ask for
receipt if the server supports it (simple broker does not). For example, with the Java
<<websocket-stomp-client, STOMP client>>, you could do the following to add a receipt:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Autowired
private TaskScheduler messageBrokerTaskScheduler;
@ -1390,8 +1364,7 @@ An application can use `@MessageExceptionHandler` methods to handle exceptions f
itself or through a method argument if you want to get access to the exception instance.
The following example declares an exception through a method argument:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Controller
public class MyController {
@ -1427,8 +1400,7 @@ The easiest way to do so is to inject a `SimpMessagingTemplate` and
use it to send messages. Typically, you would inject it by
type, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Controller
public class GreetingController {
@ -1470,8 +1442,7 @@ https://stomp.github.io/stomp-specification-1.2.html#Heart-beating[STOMP heartbe
For that, you can declare your own scheduler or use the one that is automatically
declared and used internally. The following example shows how to declare your own scheduler:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -1515,8 +1486,7 @@ and run it with STOMP support enabled. Then you can enable the STOMP broker rela
The following example configuration enables a full-featured broker:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -1538,8 +1508,7 @@ The following example configuration enables a full-featured broker:
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -1617,8 +1586,7 @@ connectivity is lost, to the same host and port. If you wish to supply multiple
on each attempt to connect, you can configure a supplier of addresses, instead of a
fixed host and port. The following example shows how to do that:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -1658,8 +1626,7 @@ you are more used to messaging conventions, you can switch to using dot (`.`) as
The following example shows how to do so in Java configuration:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -1678,8 +1645,7 @@ The following example shows how to do so in Java configuration:
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -1705,8 +1671,7 @@ The following example shows the XML configuration equivalent of the preceding ex
After that, a controller can use a dot (`.`) as the separator in `@MessageMapping` methods,
as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Controller
@MessageMapping("red")
@ -1815,8 +1780,7 @@ the user header on the CONNECT `Message`. Spring notes and saves the authenticat
user and associate it with subsequent STOMP messages on the same session. The following
example shows how register a custom authentication interceptor:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -1873,8 +1837,7 @@ A message-handling method can send messages to the user associated with
the message being handled through the `@SendToUser` annotation (also supported on
the class-level to share a common destination), as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Controller
public class PortfolioController {
@ -1893,8 +1856,7 @@ to the given destination are targeted. However, sometimes, it may be necessary t
target only the session that sent the message being handled. You can do so by
setting the `broadcast` attribute to false, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Controller
public class MyController {
@ -1924,8 +1886,7 @@ component by, for example, injecting the `SimpMessagingTemplate` created by the
the XML namespace. (The bean name is `brokerMessagingTemplate` if required
for qualification with `@Qualifier`.) The following example shows how to do so:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Service
public class TradeServiceImpl implements TradeService {
@ -1974,8 +1935,7 @@ not match the exact order of publication.
If this is an issue, enable the `setPreservePublishOrder` flag, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -1992,8 +1952,7 @@ If this is an issue, enable the `setPreservePublishOrder` flag, as the following
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -2065,8 +2024,7 @@ of a STOMP connection but not for every client message. Applications can also re
`ChannelInterceptor` to intercept any message and in any part of the processing chain.
The following example shows how to intercept inbound messages from clients:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -2082,8 +2040,7 @@ The following example shows how to intercept inbound messages from clients:
A custom `ChannelInterceptor` can use `StompHeaderAccessor` or `SimpMessageHeaderAccessor`
to access information about the message, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
public class MyChannelInterceptor implements ChannelInterceptor {
@ -2118,8 +2075,7 @@ Spring provides a STOMP over WebSocket client and a STOMP over TCP client.
To begin, you can create and configure `WebSocketStompClient`, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
WebSocketClient webSocketClient = new StandardWebSocketClient();
WebSocketStompClient stompClient = new WebSocketStompClient(webSocketClient);
@ -2135,8 +2091,7 @@ use WebSocket or HTTP-based transport as a fallback. For more details, see
Next, you can establish a connection and provide a handler for the STOMP session,
as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
String url = "ws://127.0.0.1:8080/endpoint";
StompSessionHandler sessionHandler = new MyStompSessionHandler();
@ -2145,8 +2100,7 @@ as the following example shows:
When the session is ready for use, the handler is notified, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
public class MyStompSessionHandler extends StompSessionHandlerAdapter {
@ -2160,8 +2114,7 @@ public class MyStompSessionHandler extends StompSessionHandlerAdapter {
Once the session is established, any payload can be sent and is
serialized with the configured `MessageConverter`, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
session.send("/topic/something", "payload");
----
@ -2171,8 +2124,7 @@ for messages on the subscription and returns a `Subscription` handle that you ca
use to unsubscribe. For each received message, the handler can specify the target
`Object` type to which the payload should be deserialized, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
session.subscribe("/topic/something", new StompFrameHandler() {
@ -2231,8 +2183,7 @@ transport-level errors including `ConnectionLostException`.
Each WebSocket session has a map of attributes. The map is attached as a header to
inbound client messages and may be accessed from a controller method, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Controller
public class MyController {
@ -2251,8 +2202,7 @@ registered on the `clientInboundChannel`. Those are typically singletons and liv
longer than any individual WebSocket session. Therefore, you need to use a
scope proxy mode for WebSocket-scoped beans, as the following example shows:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Component
@Scope(scopeName = "websocket", proxyMode = ScopedProxyMode.TARGET_CLASS)
@ -2360,8 +2310,7 @@ documentation of the XML schema for important additional details.
The following example shows a possible configuration:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -2379,8 +2328,7 @@ The following example shows a possible configuration:
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -2415,8 +2363,7 @@ minimum.
The following example shows one possible configuration:
[source,java,indent=0]
[subs="verbatim,quotes"]
[source,java,indent=0,subs="verbatim,quotes"]
----
@Configuration
@EnableWebSocketMessageBroker
@ -2434,8 +2381,7 @@ The following example shows one possible configuration:
The following example shows the XML configuration equivalent of the preceding example:
[source,xml,indent=0]
[subs="verbatim,quotes,attributes"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"