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

Compact headings in Web Servlet section 

Optimized for viewing in left TOC.
This commit is contained in:
Rossen Stoyanchev 2017-10-06 13:11:15 -04:00
parent b47905f050
commit 9998c63ee4
6 changed files with 193 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,6 +1,6 @@
[[web-integration]]
= Other Web Frameworks
= 3rd Party Web Frameworks
[[intro]]
@ -19,7 +19,7 @@ popular third party web frameworks.
[[web-integration-common]]
== Common configuration
== Common config
Before diving into the integration specifics of each supported web framework, let us
first take a look at the Spring configuration that is __not__ specific to any one web
framework. (This section is equally applicable to Spring's own web framework, Spring
@ -103,7 +103,7 @@ has more detail on its specific integration strategies.
[[jsf]]
== JavaServer Faces 1.2
== JSF 1.2
JavaServer Faces (JSF) is the JCP's standard component-based, event-driven web user
interface framework. As of Java EE 5, it is an official part of the Java EE umbrella.
@ -123,10 +123,10 @@ http://projects.spring.io/spring-webflow[Spring Web Flow website] for details!
The key element in Spring's JSF integration is the JSF `ELResolver` mechanism.
[[jsf-springbeanfaceselresolver]]
=== SpringBeanFacesELResolver (JSF 1.2+)
=== Spring Bean Resolver
`SpringBeanFacesELResolver` is a JSF 1.2 compliant `ELResolver` implementation,
integrating with the standard Unified EL as used by JSF 1.2 and JSP 2.1. Like
`SpringBeanVariableResolver`, it delegates to the Spring's 'business context'
`SpringBeanVariableResolver`, it delegates to the Spring's 'business context'
`WebApplicationContext` __first__, then to the default resolver of the underlying JSF
implementation.

6
src/docs/asciidoc/web/webflux.adoc
View File

@ -435,7 +435,7 @@ of defaults along with the ability to override or replace those defaults.
[[webflux-dispatcher-handler]]
== The DispatcherHandler
== DispatcherHandler
[.small]#<<web.adoc#mvc-servlet,Same in Spring MVC>>#
Spring WebFlux, like Spring MVC, is designed around the front controller pattern where a
@ -1020,7 +1020,7 @@ easy to seem them in `WebFluxConfigurationSupport`, and if you want to learn mor
[[webflux-config-enable]]
=== Enable the configuration
=== Enable WebFlux config
[.small]#<<web.adoc#mvc-config-enable,Same in Spring MVC>>#
Use the `@EnableWebFlux` annotation in your Java config:
@ -1040,7 +1040,7 @@ available on the classpath -- for JSON, XML, etc.
[[webflux-config-customize]]
=== Configuration API
=== WebFlux config API
[.small]#<<web.adoc#mvc-config-customize,Same in Spring MVC>>#
In your Java config implement the `WebFluxConfigurer` interface:

12
src/docs/asciidoc/web/webmvc-cors.adoc
View File

@ -1,5 +1,5 @@
[[mvc-cors]]
= CORS Support
= CORS
== Introduction
@ -31,7 +31,7 @@ Since CORS requests are automatically dispatched, you *do not need* to change th
(`false`) is the recommended approach.
====
== Controller method CORS configuration
== @Controller CORS
You can add an
{api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`]
@ -109,14 +109,14 @@ public class AccountController {
}
----
== Global CORS configuration
== Global CORS
In addition to fine-grained, annotation-based configuration you'll probably want to
define some global CORS configuration as well. This is similar to using filters but can
be declared within Spring MVC and combined with fine-grained `@CrossOrigin` configuration.
By default all origins and `GET`, `HEAD`, and `POST` methods are allowed.
=== JavaConfig
=== MVC Java Config
Enabling CORS for the whole application is as simple as:
@ -156,7 +156,7 @@ public class WebConfig implements WebMvcConfigurer {
}
----
=== XML namespace
=== MVC XML Config
The following minimal XML configuration enables CORS for the `/**` path pattern with
the same default properties as with the aforementioned JavaConfig examples:
@ -205,7 +205,7 @@ It can be provided in various ways:
now does) in order to provide a {api-spring-framework}/web/cors/CorsConfiguration.html[CorsConfiguration]
instance for each request.
== Filter based CORS support
== CORS Filter
In order to support CORS with filter-based security frameworks like
http://projects.spring.io/spring-security/[Spring Security], or

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

@ -27,7 +27,7 @@ documentation section for more details.
[[mvc-view-groovymarkup]]
== Groovy Markup Templates
== Groovy Markup
The http://groovy-lang.org/templating.html#_the_markuptemplateengine[Groovy Markup Template Engine]
is another view technology, supported by Spring. This template engine is a template engine primarily
@ -157,7 +157,7 @@ for JSP's. So if your controller returns a ModelAndView object containing a view
[[mvc-views-freemarker]]
=== Advanced FreeMarker configuration
=== Advanced config
FreeMarker 'Settings' and 'SharedVariables' can be passed directly to the FreeMarker
`Configuration` object managed by Spring by setting the appropriate bean properties on
the `FreeMarkerConfigurer` bean. The `freemarkerSettings` property requires a
@ -185,7 +185,7 @@ the `Configuration` object.
[[mvc-view-freemarker-forms]]
=== Bind support and form handling
=== Form handling
Spring provides a tag library for use in JSP's that contains (amongst other things) a
`<spring:bind/>` tag. This tag primarily enables forms to display values from form
backing objects and to show the results of failed validations from a `Validator` in the
@ -251,7 +251,7 @@ They are explained in the next section.
[[mvc-views-form-macros]]
==== Form input generation macros
==== Input macros
Additional convenience macros for both languages simplify both binding and form
generation (including validation error display). It is never necessary to use these
macros to generate form input fields, and they can be mixed and matched with simple HTML
@ -456,7 +456,7 @@ user still sees the more user friendly city names.
[[mvc-views-form-macros-html-escaping]]
==== HTML escaping and XHTML compliance
==== HTML escaping
Default usage of the form macros above will result in HTML tags that are HTML 4.01
compliant and that use the default value for HTML escaping defined in your web.xml as
used by Spring's bind support. In order to make the tags XHTML compliant or to override
@ -560,7 +560,7 @@ under the `'WEB-INF'` directory, so there can be no direct access by clients.
[[mvc-view-jsp-jstl]]
=== 'Plain-old' JSPs versus JSTL
=== JSPs versus JSTL
When using the Java Standard Tag Library you must use a special view class, the
`JstlView`, as JSTL needs some preparation before things such as the I18N features will
work.
@ -568,7 +568,7 @@ work.
[[mvc-view-jsp-tags]]
=== Additional tags facilitating development
=== Spring tags
Spring provides data binding of request parameters to command objects as described in
earlier chapters. To facilitate the development of JSP pages in combination with those
data binding features, Spring provides a few tags that make things even easier. All
@ -581,7 +581,7 @@ or see the tag library description.
[[mvc-view-jsp-formtaglib]]
=== Using Spring's form tag library
=== Spring form tags
As of version 2.0, Spring provides a comprehensive set of data binding-aware tags for
handling form elements when using JSP and Spring Web MVC. Each tag provides support for
the set of attributes of its corresponding HTML tag counterpart, making the tags
@ -1338,7 +1338,7 @@ is the default type.
[[mvc-view-script]]
== Script templates
== Script views
It is possible to integrate any templating library running on top of a JSR-223
script engine in web applications using Spring. The following describes in a
@ -1355,7 +1355,7 @@ It has been tested with:
* https://docs.python.org/2/library/string.html#template-strings[String templates] running on http://www.jython.org/[Jython]
[[mvc-view-script-dependencies]]
=== Dependencies
=== Requirements
To be able to use script templates integration, you need to have available in your classpath
the script engine:
@ -1375,7 +1375,7 @@ in order to make your javascript libraries available in the classpath.
[[mvc-view-script-integrate]]
=== How to integrate script based templating
=== Script templates
To be able to use script templates, you have to configure it in order to specify various parameters
like the script engine to use, the script files to load and what function should be called to
@ -1535,7 +1535,7 @@ for more configuration examples.
[[mvc-view-xml-marshalling]]
== XML Marshalling View
== XML Marshalling
The `MarshallingView` uses an XML `Marshaller` defined in the `org.springframework.oxm`
package to render the response content as XML. The object to be marshalled can be set
explicitly using `MarhsallingView`'s `modelKey` bean property. Alternatively, the view
@ -1569,7 +1569,7 @@ to your project.
[[mvc-view-tiles-integrate]]
=== How to integrate Tiles
=== Configuration
To be able to use Tiles, you have to configure it using files containing definitions
(for basic information on definitions and other Tiles concepts, please have a look at
http://tiles.apache.org[]). In Spring this is done using the `TilesConfigurer`. Have a
@ -1626,7 +1626,7 @@ them otherwise in the file names for Tiles definitions.
[[mvc-view-tiles-url]]
==== UrlBasedViewResolver
==== View Resolver
The `UrlBasedViewResolver` instantiates the given `viewClass` for each view it has to
resolve.
@ -1641,7 +1641,7 @@ resolve.
[[mvc-view-tiles-resource]]
==== ResourceBundleViewResolver
==== Resource Bundle
The `ResourceBundleViewResolver` has to be provided with a property file containing
viewnames and viewclasses the resolver can use:
@ -1677,7 +1677,7 @@ box.
[[mvc-view-tiles-preparer]]
==== SimpleSpringPreparerFactory and SpringBeanPreparerFactory
==== Preparer Factories
As an advanced feature, Spring also supports two special Tiles `PreparerFactory`
implementations. Check out the Tiles documentation for details on how to use
@ -1728,10 +1728,6 @@ naturally deals with XML, or if your model can easily be converted to XML. The f
section shows how to produce an XML document as model data and have it transformed with
XSLT in a Spring Web MVC application.
[[mvc-view-xslt-firstwords]]
=== My First Words
This example is a trivial Spring application that creates a list of words in the
`Controller` and adds them to the model map. The map is returned along with the view
name of our XSLT view. See <<mvc-controller>> for details of Spring Web MVC's
@ -1740,7 +1736,7 @@ document ready for transformation.
[[mvc-view-xslt-beandefs]]
==== Bean definitions
=== Beans
Configuration is standard for a simple Spring application.
The MVC configuration has to define a `XsltViewResolver` bean and
regular MVC annotation configuration.
@ -1768,7 +1764,7 @@ And we need a Controller that encapsulates our word generation logic.
[[mvc-view-xslt-controllercode]]
==== Standard MVC controller code
=== Controller
The controller logic is encapsulated in a `@Controller` class, with the
handler method being defined like so...
@ -1814,7 +1810,7 @@ DOM document into it to generate our view.
[[mvc-view-xslt-transforming]]
==== Document transformation
=== Transformation
Finally, the `XsltViewResolver` will resolve the "home" XSLT template file and merge the
DOM document into it to generate our view. As shown in the `XsltViewResolver`
@ -1871,7 +1867,7 @@ This is rendered as:
----
[[mvc-view-document]]
== Document views (PDF/Excel)
== PDF, Excel
@ -1889,7 +1885,7 @@ for PDF generation, the iText library.
[[mvc-view-document-config]]
=== Configuration and setup
=== Configuration
Document based views are handled in an almost identical fashion to XSLT views, and the
following sections build upon the previous one by demonstrating how the same controller
used in the XSLT example is invoked to render the same model as both a PDF document and
@ -1897,7 +1893,7 @@ an Excel spreadsheet (which can also be viewed or manipulated in Open Office).
[[mvc-view-document-configviews]]
==== Document view definitions
=== View definition
First, let's amend the views.properties file (or xml equivalent) and add a simple view
definition for both document types. The entire file now looks like this with the XSLT
view shown from earlier:
@ -1919,7 +1915,7 @@ model data to, specify the location as the 'url' property in the view definition
[[mvc-view-document-configcontroller]]
==== Controller code
=== Controller
The controller code we'll use remains exactly the same from the XSLT example earlier
other than to change the name of the view to use. Of course, you could be clever and
have this selected based on a URL parameter or some other logic - proof that Spring
@ -1927,7 +1923,7 @@ really is very good at decoupling the views from the controllers!
[[mvc-view-document-configsubclasses]]
==== Subclassing for Excel views
=== Excel views
Exactly as we did for the XSLT example, we'll subclass suitable abstract classes in
order to implement custom behavior in generating our output documents. For Excel, this
involves writing a subclass of
@ -2011,7 +2007,7 @@ same page as before.
[[mvc-view-document-configsubclasspdf]]
==== Subclassing for PDF views
=== PDF views
The PDF version of the word list is even simpler. This time, the class extends
`org.springframework.web.servlet.view.document.AbstractPdfView` and implements the
`buildPdfDocument()` method as follows:
@ -2044,7 +2040,7 @@ document should appear listing each of the words in the model map.
[[mvc-view-feeds]]
== Feed Views
== RSS Feeds
Both `AbstractAtomFeedView` and `AbstractRssFeedView` inherit from the base class
`AbstractFeedView` and are used to provide Atom and RSS Feed views respectfully. They
are based on java.net's https://rome.dev.java.net[ROME] project and are located in the
@ -2105,10 +2101,11 @@ For an example of creating an Atom view please refer to Alef Arendsen's Spring T
https://spring.io/blog/2009/03/16/adding-an-atom-view-to-an-application-using-spring-s-rest-support[entry].
[[mvc-view-jackson]]
== Jackson
[[mvc-view-json-mapping]]
== JSON Mapping View
=== JSON
The `MappingJackson2JsonView` uses the Jackson library's `ObjectMapper` to render the response
content as JSON. By default, the entire contents of the model map (with the exception of
framework-specific classes) will be encoded as JSON. For cases where the contents of the
@ -2130,7 +2127,7 @@ name(s) could be customized through the `jsonpParameterNames` property.
[[mvc-view-xml-mapping]]
== XML Mapping View
=== XML
The `MappingJackson2XmlView` uses the
https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML extension]'s `XmlMapper`
to render the response content as XML. If the model contains multiples entries, the

239
src/docs/asciidoc/web/webmvc.adoc
View File

@ -19,7 +19,7 @@ covers Spring WebFlux.
[[mvc-servlet]]
== The DispatcherServlet
== DispatcherServlet
[.small]#<<web-reactive.adoc#webflux-dispatcher-handler,Same in Spring WebFlux>>#
Spring MVC, like many other web frameworks, is designed around the front controller
@ -66,7 +66,7 @@ public class MyWebApplicationInitializer implements WebApplicationInitializer {
====
In addition to using the ServletContext API directly, you can also extend
`AbstractAnnotationConfigDispatcherServletInitializer` and override specific methods
(see example under <<mvc-servlet-context-hierarchy,WebApplicationContext Hierarchy>>).
(see example under <<mvc-servlet-context-hierarchy>>).
====
Below is an example of `web.xml` configuration to register and initialize the `DispatcherServlet`:
@ -115,7 +115,7 @@ https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-featu
[[mvc-servlet-context-hierarchy]]
=== WebApplicationContext Hierarchy
=== Context Hierarchy
`DispatcherServlet` expects a `WebApplicationContext`, an extension of a plain
`ApplicationContext`, for its own configuration. `WebApplicationContext` has a link to the
@ -198,7 +198,7 @@ And the `web.xml` equivalent:
[[mvc-servlet-special-bean-types]]
=== Special Bean Types In the WebApplicationContext
=== Special Bean Types
[.small]#<<web-reactive.adoc#webflux-special-bean-types,Same in Spring WebFlux>>#
The `DispatcherServlet` delegates to special beans to process requests and render the
@ -251,7 +251,7 @@ customize, extend, or replace them.
[[mvc-servlet-config]]
=== `DispatcherServlet` Configuration
=== Initialization
For each type of special bean, the `DispatcherServlet` checks for the `WebApplicationContext` first.
If there are no matching bean types, it falls back on the default types listed in
https://github.com/spring-projects/spring-framework/blob/master/spring-webmvc/src/main/resources/org/springframework/web/servlet/DispatcherServlet.properties[DispatcherServlet.properties].
@ -270,7 +270,7 @@ provides many extra convenient options on top.
[[mvc-servlet-sequence]]
=== DispatcherServlet Processing Sequence
=== Processing Sequence
[.small]#<<web-reactive.adoc#webflux-dispatcher-handler-sequence,Same in Spring WebFlux>>#
The `DispatcherServlet` processes requests as follows:
@ -370,7 +370,7 @@ programming model described in this section.
[[mvc-ann-controller]]
=== Defining a controller with @Controller
=== @Controller Declaration
[.small]#<<web-reactive.adoc#webflux-ann-controller,Same in Spring WebFlux>>#
You can define controller beans using a standard Spring bean definition in the
@ -427,7 +427,7 @@ rendering).
[[mvc-ann-requestmapping]]
=== Mapping Requests With @RequestMapping
=== Mapping Requests
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping,Same in Spring WebFlux>>#
The `@RequestMapping` annotation is used to map requests to controllers methods. It has
@ -470,7 +470,7 @@ At the class level an `@RequestMapping` is more useful for expressing shared map
[[mvc-ann-requestmapping-proxying]]
==== @Controller and AOP Proxying
==== AOP proxies
In some cases a controller may need to be decorated with an AOP proxy at runtime.
One example is if you choose to have `@Transactional` annotations directly on the
@ -483,7 +483,7 @@ change to `<tx:annotation-driven proxy-target-class="true"/>`.
[[mvc-ann-requestmapping-uri-templates]]
==== URI Path Patterns
==== URI patterns
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-uri-templates,Same in Spring
WebFlux>>#
@ -554,7 +554,7 @@ Spring MVC uses the `PathMatcher` contract and the `AntPathMatcher` implementati
[[mvc-ann-requestmapping-pattern-comparison]]
==== Path Pattern Comparison
==== Pattern comparison
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-pattern-comparison,Same in Spring
WebFlux>>#
@ -578,7 +578,7 @@ in the configuration section.
[[mvc-ann-requestmapping-suffix-pattern-match]]
==== Suffix Pattern Matching
==== Suffix match
By default Spring MVC performs `".{asterisk}"` suffix pattern matching so that a
controller mapped to `/person` is also implicitly mapped to `/person.{asterisk}`.
@ -599,7 +599,7 @@ content negotiation consider using query parameters instead.
[[mvc-ann-requestmapping-rfd]]
==== Suffix Pattern Matching and RFD
==== Suffix match and RFD
Reflected file download (RFD) attack is similar to XSS in that it relies on request input,
e.g. query parameter, URI variable, being reflected in the response. However instead of
@ -628,7 +628,7 @@ recommendations related to RFD.
[[mvc-ann-matrix-variables]]
==== Matrix Variables
==== Matrix variables
The URI specification http://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] defines
the possibility of including name-value pairs within path segments. There is no specific
term used in the spec. The general "URI path parameters" could be applied although the
@ -752,7 +752,7 @@ to `false`.
====
[[mvc-ann-requestmapping-consumes]]
==== Consumable Media Types
==== Consumable media types
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-consumes,Same in Spring WebFlux>>#
You can narrow the request mapping based on the `Content-Type` of the request:
@ -781,7 +781,7 @@ will overrides rather than extend the class level declaration.
[[mvc-ann-requestmapping-produces]]
==== Producible Media Types
==== Producible media types
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-produces,Same in Spring WebFlux>>#
You can narrow the request mapping based on the `Accept` request header and the list of
@ -812,7 +812,7 @@ will overrides rather than extend the class level declaration.
[[mvc-ann-requestmapping-params-and-headers]]
==== Request Parameters and Header Values
==== Parameters, headers
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-params-and-headers,Same in Spring
WebFlux>>#
@ -849,7 +849,7 @@ instead.
[[mvc-ann-requestmapping-head-options]]
==== HTTP HEAD and OPTIONS
==== HTTP HEAD, OPTIONS
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-head-options,Same in Spring WebFlux>>#
`@GetMapping` -- and also `@RequestMapping(method=HttpMethod.GET)`, support HTTP HEAD
@ -876,14 +876,14 @@ is not necessary in the common case.
[[mvc-ann-methods]]
=== Defining @RequestMapping methods
=== Handler Methods
[.small]#<<web-reactive.adoc#webflux-ann-methods,Same in Spring WebFlux>>#
`@RequestMapping` handler methods have a flexible signature and can choose from a range of
supported controller method arguments and return values.
[[mvc-ann-arguments]]
==== Supported Controller Method Arguments
==== Method Arguments
[.small]#<<web-reactive.adoc#webflux-ann-arguments,Same in Spring WebFlux>>#
The table below shows supported controller method arguments. Reactive types are not supported
@ -1001,7 +1001,7 @@ as a result of a class-level `@SessionAttributes` declaration.
|===
[[mvc-ann-return-types]]
==== Supported Controller Method Return Values
==== Return Values
[.small]#<<web-reactive.adoc#webflux-ann-return-types,Same in Spring WebFlux>>#
The table below shows supported controller method return values. Reactive types are
@ -1086,7 +1086,7 @@ class name of the return type.
[[mvc-ann-requestparam]]
==== Binding request parameters to method parameters with @RequestParam
==== @RequestParam
Use the `@RequestParam` annotation to bind request parameters to a method parameter in
your controller.
@ -1128,7 +1128,7 @@ parameters.
[[mvc-ann-requestbody]]
==== Mapping the request body with the @RequestBody annotation
==== @RequestBody
The `@RequestBody` method parameter annotation indicates that a method parameter should
be bound to the value of the HTTP request body. For example:
@ -1206,7 +1206,7 @@ or the MVC Java config.
[[mvc-ann-responsebody]]
==== Mapping the response body with the @ResponseBody annotation
==== @ResponseBody
The `@ResponseBody` annotation is similar to `@RequestBody`. This annotation can be placed
on a method and indicates that the return type should be written straight to the HTTP
@ -1230,7 +1230,7 @@ an `HttpMessageConverter`. For more information on these converters, see the pre
section and <<integration.adoc#rest-message-conversion,Message Converters>>.
[[mvc-ann-restcontroller]]
==== Creating REST Controllers with the @RestController annotation
==== @RestController
It's a very common use case to have Controllers implement a REST API, thus serving only
JSON, XML or custom MediaType content. For convenience, instead of annotating all your
@ -1247,7 +1247,7 @@ As with regular ``@Controller``s, a `@RestController` may be assisted by
section for more details.
[[mvc-ann-httpentity]]
==== Using HttpEntity
==== HttpEntity
The `HttpEntity` is similar to `@RequestBody` and `@ResponseBody`. Besides getting
access to the request and response body, `HttpEntity` (and the response-specific
@ -1281,7 +1281,7 @@ Message Converters>>.
[[mvc-ann-modelattrib-methods]]
==== Using @ModelAttribute on a method
==== @ModelAttribute method
The `@ModelAttribute` annotation can be used on methods or on method arguments. This
section explains its usage on methods while the next section explains its usage on
@ -1349,7 +1349,7 @@ conventions instead, much like for methods returning `void` -- see <<mvc-coc-r2v
[[mvc-ann-modelattrib-method-args]]
==== Using @ModelAttribute on a method argument
==== @ModelAttribute arguments
As explained in the previous section `@ModelAttribute` can be used on methods or on
method arguments. This section explains its usage on method arguments.
@ -1497,10 +1497,11 @@ See <<core.adoc#validation-beanvalidation, Bean validation>> and
[[mvc-ann-sessionattrib]]
==== Using @SessionAttributes to store model attributes in the HTTP session between requests
[[mvc-ann-sessionattributes]]
==== @SessionAttributes
The type-level `@SessionAttributes` annotation declares session attributes used by a
`@SessionAttributes` is used to store model attributes in the HTTP session between
requests. It is a type-level annotation that declares session attributes used by a
specific handler. This will typically list the names of model attributes or types of
model attributes which should be transparently stored in the session or some
conversational storage, serving as form-backing beans between subsequent requests.
@ -1519,9 +1520,8 @@ attribute name:
}
----
[[mvc-ann-sessionattrib-global]]
==== Using @SessionAttribute to access pre-existing global session attributes
[[mvc-ann-sessionattribute]]
==== @SessionAttribute
If you need access to pre-existing session attributes that are managed globally,
i.e. outside the controller (e.g. by a filter), and may or may not be present
@ -1546,7 +1546,7 @@ workflow consider using `SessionAttributes` as described in
[[mvc-ann-requestattrib]]
==== Using @RequestAttribute to access request attributes
==== @RequestAttribute
Similar to `@SessionAttribute` the `@RequestAttribute` annotation can be used to
access pre-existing request attributes created by a filter or interceptor:
@ -1564,7 +1564,7 @@ access pre-existing request attributes created by a filter or interceptor:
[[mvc-ann-form-urlencoded-data]]
==== Working with "application/x-www-form-urlencoded" data
==== HTTP PUT form data
The previous sections covered use of `@ModelAttribute` to support form submission
requests from browser clients. The same annotation is recommended for use with requests
@ -1611,7 +1611,8 @@ String>` and `HttpEntity<MultiValueMap<String, String>>`.
[[mvc-ann-cookievalue]]
==== Mapping cookie values with the @CookieValue annotation
==== @CookieValue
The `@CookieValue` annotation allows a method parameter to be bound to the value of an
HTTP cookie.
@ -1639,7 +1640,7 @@ Type conversion is applied automatically if the target method parameter type is
[[mvc-ann-requestheader]]
==== Mapping request header attributes with the @RequestHeader annotation
==== @RequestHeader
The `@RequestHeader` annotation allows a method parameter to be bound to a request header.
Here is a sample request header:
@ -1686,7 +1687,7 @@ example a method parameter annotated with `@RequestHeader("Accept")` may be of t
[[mvc-ann-typeconversion]]
==== Method Parameters And Type Conversion
==== Type Conversion
String-based values extracted from the request including request parameters, path
variables, request headers, and cookie values may need to be converted to the target
type of the method parameter or field (e.g., binding a request parameter to a field in
@ -1697,15 +1698,14 @@ a `WebDataBinder` (see <<mvc-ann-webdatabinder>>) or by registering `Formatters`
the `FormattingConversionService` (see <<core.adoc#format, Spring Field Formatting>>).
[[mvc-ann-webdatabinder]]
==== Customizing WebDataBinder initialization
[[mvc-ann-initbinder]]
==== @InitBinder methods
To customize request parameter binding with PropertyEditors through Spring's
`WebDataBinder`, you can use `@InitBinder`-annotated methods within your controller,
`@InitBinder` methods within an `@ControllerAdvice` class, or provide a custom
`WebBindingInitializer`. See the <<mvc-ann-controller-advice>> section for more details.
[[mvc-ann-initbinder]]
===== Customizing data binding with @InitBinder
Annotating controller methods with `@InitBinder` allows you to configure web data
binding directly within your controller class. `@InitBinder` identifies methods that
initialize the `WebDataBinder` that will be used to populate command and form object
@ -1759,7 +1759,7 @@ controller-specific tweaking of the binding rules.
----
[[mvc-ann-webbindinginitializer]]
===== Configuring a custom WebBindingInitializer
==== WebBindingInitializer
To externalize data binding initialization, you can provide a custom implementation of
the `WebBindingInitializer` interface, which you then enable by supplying a custom bean
@ -1788,7 +1788,7 @@ which case they apply to matching controllers. This provides an alternative to u
[[mvc-ann-controller-advice]]
==== Advising controllers with @ControllerAdvice and @RestControllerAdvice
==== @ControllerAdvice
The `@ControllerAdvice` annotation is a component annotation allowing implementation
classes to be auto-detected through classpath scanning. It is automatically enabled when
@ -1825,7 +1825,7 @@ Check out the
documentation] for more details.
[[mvc-ann-jsonview]]
==== Jackson Serialization View Support
==== Jackson views
It can sometimes be useful to filter contextually the object that will be serialized to the
HTTP response body. In order to provide such capability, Spring MVC has built-in support for
@ -1903,7 +1903,7 @@ to the model:
----
[[mvc-ann-jsonp]]
==== Jackson JSONP Support
==== Jackson JSONP
In order to enable http://en.wikipedia.org/wiki/JSONP[JSONP] support for `@ResponseBody`
and `ResponseEntity` methods, declare an `@ControllerAdvice` bean that extends
@ -1928,7 +1928,11 @@ customized through `jsonpParameterNames` property.
[[mvc-ann-async]]
=== Asynchronous Request Processing
=== Async requests
[[mvc-ann-async-processing]]
==== Processing
Spring MVC 3.2 introduced Servlet 3 based asynchronous request processing. Instead of
returning a value, as usual, a controller method can now return a
`java.util.concurrent.Callable` and produce the return value from a Spring MVC managed thread.
@ -2023,7 +2027,7 @@ blog post series].
[[mvc-ann-async-exceptions]]
==== Exception Handling for Async Requests
==== Exception handling
What happens if a `Callable` returned from a controller method raises an
Exception while being executed? The short answer is the same as what happens
when a controller method raises an exception. It goes through the regular
@ -2036,7 +2040,7 @@ When using a `DeferredResult` you have a choice whether to call
[[mvc-ann-async-interception]]
==== Intercepting Async Requests
==== Async interceptors
A `HandlerInterceptor` can also implement `AsyncHandlerInterceptor` in order
to implement the `afterConcurrentHandlingStarted` callback, which is called
instead of `postHandle` and `afterCompletion` when asynchronous processing
@ -2056,7 +2060,7 @@ When using a `Callable` you can wrap it with an instance of `WebAsyncTask`
which also provides registration methods for timeout and completion.
[[mvc-ann-async-http-streaming]]
==== HTTP Streaming
==== Streaming response
A controller method can use `DeferredResult` and `Callable` to produce its
return value asynchronously and that can be used to implement techniques such as
@ -2097,7 +2101,7 @@ Note that `ResponseBodyEmitter` can also be used as the body in a
the response.
[[mvc-ann-async-sse]]
==== HTTP Streaming With Server-Sent Events
==== Server-Sent Events
`SseEmitter` is a sub-class of `ResponseBodyEmitter` providing support for
http://www.w3.org/TR/eventsource/[Server-Sent Events].
@ -2120,7 +2124,7 @@ For further background on this see
http://blog.pivotal.io/pivotal/products/websocket-architecture-in-spring-4-0[the following blog post].
[[mvc-ann-async-output-stream]]
==== HTTP Streaming Directly To The OutputStream
==== Streaming raw data
`ResponseBodyEmitter` allows sending events by writing Objects to the
response through an `HttpMessageConverter`. This is probably the most common
@ -2151,7 +2155,7 @@ the response.
[[mvc-ann-async-reactive-types]]
==== Async Requests with Reactive Types
==== Reactive return values
If using the reactive `WebClient` from `spring-webflux`, or another client, or
a data store with reactive support, you can return reactive types directly from
@ -2201,12 +2205,14 @@ processing and hence does not require a thread to absorb the effect of blocking.
[[mvc-ann-async-configuration]]
==== Configuring Asynchronous Request Processing
==== Configuration
For asynchronous requests there are minor requirements at the Servlet container
level and more controls in Spring MVC configuration.
[[mvc-ann-async-configuration-servlet3]]
===== Servlet Container Configuration
===== Servlet container config
For applications configured with a `web.xml` be sure to update to version 3.0:
[source,xml,indent=0]
@ -2269,7 +2275,7 @@ just like with `web.xml`. To simplify all this configuration, consider extending
set those options and make it very easy to register `Filter` instances.
[[mvc-ann-async-configuration-spring-mvc]]
===== Spring MVC Configuration
===== Spring MVC config
The MVC Java config and the MVC namespace provide options for configuring
asynchronous request processing. `WebMvcConfigurer` has the method
@ -2293,7 +2299,7 @@ the timeout value. The class constructor of `WebAsyncTask` also allows providing
[[mvc-ann-tests]]
=== Testing Controllers
=== Testing
The `spring-test` module offers first class support for testing annotated controllers.
See <<testing.adoc#spring-mvc-test-framework, Spring MVC Test Framework>>.
@ -2346,7 +2352,7 @@ The following example shows how to configure an interceptor:
[[mvc-handlermapping-interceptor]]
=== Intercepting requests with a HandlerInterceptor
=== HandlerInterceptor
Spring's handler mapping mechanism includes handler interceptors, which are useful when
you want to apply specific functionality to certain requests, for example, checking for
@ -2454,7 +2460,7 @@ directly on `RequestMappingHandlerAdapter`.
[[mvc-viewresolver]]
== Resolving views
== View resolution
All MVC frameworks for web applications provide a way to address views. Spring provides
view resolvers, which enable you to render models in a browser without tying you to a
specific view technology. Out of the box, Spring enables you to use JSPs, FreeMarker
@ -2469,7 +2475,7 @@ to one of the view technologies.
[[mvc-viewresolver-resolver]]
=== Resolving views with the ViewResolver interface
=== ViewResolver
As discussed in <<mvc-controller>>, all handler methods in the Spring Web MVC
controllers must resolve to a logical view name, either explicitly (e.g., by returning a
@ -2479,7 +2485,7 @@ Spring comes with quite a few view resolvers. This table lists most of them; a c
examples follow.
[[mvc-view-resolvers-tbl]]
.View resolvers
.ViewResolver implementations
|===
| ViewResolver| Description
@ -2568,7 +2574,7 @@ the `removeFromCache(String viewName, Locale loc)` method.
[[mvc-viewresolver-chaining]]
=== Chaining ViewResolvers
=== Resolver chain
Spring supports multiple view resolvers. Thus you can chain resolvers and, for example,
override specific views in certain circumstances. You chain view resolvers by adding
more than one resolver to your application context and, if necessary, by setting the
@ -2620,7 +2626,7 @@ the last results in the chain not being fully inspected, because the
[[mvc-redirecting]]
=== Redirecting to Views
=== Redirecting
As mentioned previously, a controller typically returns a logical view name, which a
view resolver resolves to a particular view technology. For view technologies such as
JSPs that are processed through the Servlet or JSP engine, this resolution is usually
@ -2662,7 +2668,7 @@ that it is not baked into the controller but configured in the context along wit
view names. The <<mvc-redirecting-redirect-prefix>> facilitates this decoupling.
[[mvc-redirecting-passing-data]]
===== Passing Data To the Redirect Target
===== Redirect with data
By default all model attributes are considered to be exposed as URI template variables in
the redirect URL. Of the remaining attributes those that are primitive types or
@ -2704,7 +2710,7 @@ other redirect attributes, flash attributes are saved in the HTTP session (and h
not appear in the URL). See <<mvc-flash-attributes>> for more information.
[[mvc-redirecting-redirect-prefix]]
==== The redirect: prefix
==== "redirect:" prefix
While the use of `RedirectView` works fine, if the controller itself creates the
`RedirectView`, there is no avoiding the fact that the controller is aware that a
@ -2728,7 +2734,7 @@ value takes precedence over the response status set by `RedirectView`.
[[mvc-redirecting-forward-prefix]]
==== The forward: prefix
==== "forward:" prefix
It is also possible to use a special `forward:` prefix for view names that are
ultimately resolved by `UrlBasedViewResolver` and subclasses. This creates an
@ -2746,7 +2752,7 @@ in terms of handling the response.
[[mvc-multiple-representations]]
=== ContentNegotiatingViewResolver
=== Content negotiation
The `ContentNegotiatingViewResolver` does not resolve views itself but rather delegates
to other view resolvers, selecting the view that resembles the representation requested
@ -2879,7 +2885,7 @@ application/atom+xml is shown below.
[[mvc-flash-attributes]]
== Using flash attributes
=== Flash attributes
Flash attributes provide a way for one request to store attributes intended for use in
another. This is most commonly needed when redirecting -- for example, the
__Post/Redirect/Get__ pattern. Flash attributes are saved temporarily before the
@ -2926,7 +2932,7 @@ Therefore the use of flash attributes is recommended mainly for redirect scenari
[[mvc-uri-building]]
== Building URIs
== URI links
Spring MVC provides a mechanism for building and encoding a URI using
`UriComponentsBuilder` and `UriComponents`.
@ -3001,7 +3007,7 @@ also have the literal part of the servlet mapping included:
----
[[mvc-links-to-controllers]]
=== Building URIs to Controllers and methods
=== Links to controllers
Spring MVC also provides a mechanism for building links to controller methods. For example, given:
@ -3075,7 +3081,7 @@ with a base URL and then use the instance-based "withXxx" methods. For example:
[[mvc-links-to-controllers-forwarded-headers]]
=== Working with "Forwarded" and "X-Forwarded-*" Headers
=== "Forwarded" Headers
As a request goes through proxies such as load balancers the host, port, and
scheme may change presenting a challenge for applications that need to create links
@ -3107,7 +3113,7 @@ configure the `ForwardedHeaderFilter` to remove and ignore such headers.
[[mvc-links-to-controllers-from-views]]
=== Building URIs to Controllers and methods from views
=== Links in views
You can also build links to annotated controllers from views such as JSP, Thymeleaf,
FreeMarker. This can be done using the `fromMappingName` method in `MvcUriComponentsBuilder`
@ -3160,7 +3166,7 @@ in order to use a specific instance of `MvcUriComponentsBuilder` with a custom b
[[mvc-localeresolver]]
== Using locales
== Locales
Most parts of Spring's architecture support internationalization, just as the Spring web
MVC framework does. `DispatcherServlet` enables you to automatically resolve messages
using the client's locale. This is done with `LocaleResolver` objects.
@ -3182,7 +3188,7 @@ Spring.
[[mvc-timezone]]
=== Obtaining Time Zone Information
=== TimeZone
In addition to obtaining the client's locale, it is often useful to know their time zone.
The `LocaleContextResolver` interface offers an extension to `LocaleResolver` that allows
resolvers to provide a richer `LocaleContext`, which may include time zone information.
@ -3195,7 +3201,7 @@ by Date/Time `Converter` and `Formatter` objects registered with Spring's
[[mvc-localeresolver-acceptheader]]
=== AcceptHeaderLocaleResolver
=== Header resolver
This locale resolver inspects the `accept-language` header in the request that was sent
by the client (e.g., a web browser). Usually this header field contains the locale of
the client's operating system. __Note that this resolver does not support time zone
@ -3204,7 +3210,7 @@ information.__
[[mvc-localeresolver-cookie]]
=== CookieLocaleResolver
=== Cookie resolver
This locale resolver inspects a `Cookie` that might exist on the client to see if a
`Locale` or `TimeZone` is specified. If so, it uses the specified details. Using the
@ -3249,7 +3255,7 @@ maximum age. Find below an example of defining a `CookieLocaleResolver`.
[[mvc-localeresolver-session]]
=== SessionLocaleResolver
=== Session resolver
The `SessionLocaleResolver` allows you to retrieve `Locale` and `TimeZone` from the
session that might be associated with the user's request. In contrast to
@ -3264,7 +3270,7 @@ modify corresponding `HttpSession` attributes against the current `HttpServletRe
[[mvc-localeresolver-interceptor]]
=== LocaleChangeInterceptor
=== Locale interceptor
You can enable changing of locales by adding the `LocaleChangeInterceptor` to one of the
handler mappings (see <<mvc-handlermapping>>). It will detect a parameter in the request
@ -3302,21 +3308,16 @@ change the site language to Dutch.
[[mvc-themeresolver]]
== Using themes
== Themes
[[mvc-themeresolver-introduction]]
=== Overview of themes
You can apply Spring Web MVC framework themes to set the overall look-and-feel of your
application, thereby enhancing user experience. A theme is a collection of static
resources, typically style sheets and images, that affect the visual style of the
application.
[[mvc-themeresolver-defining]]
=== Defining themes
=== Define a theme
To use themes in your web application, you must set up an implementation of the
`org.springframework.ui.context.ThemeSource` interface. The `WebApplicationContext`
interface extends `ThemeSource` but delegates its responsibilities to a dedicated
@ -3367,7 +3368,7 @@ background image with Dutch text on it.
[[mvc-themeresolver-resolving]]
=== Theme resolvers
=== Resolve themes
After you define themes, as in the preceding section, you decide which theme to use. The
`DispatcherServlet` will look for a bean named `themeResolver` to find out which
`ThemeResolver` implementation to use. A theme resolver works in much the same way as a
@ -3398,12 +3399,8 @@ request with a simple request parameter.
[[mvc-multipart]]
== Multipart (file upload) support
== Multipart, File Upload
[[mvc-multipart-introduction]]
=== Introduction
Spring's built-in multipart support handles file uploads in web applications. You enable
this multipart support with pluggable `MultipartResolver` objects, defined in the
`org.springframework.web.multipart` package. Spring provides one `MultipartResolver`
@ -3421,7 +3418,7 @@ like any other attribute.
[[mvc-multipart-resolver-commons]]
=== Using a MultipartResolver with __Commons FileUpload__
=== __Commons FileUpload__
The following example shows how to use the `CommonsMultipartResolver`:
@ -3451,7 +3448,7 @@ the multipart files themselves in your controllers.
[[mvc-multipart-resolver-standard]]
=== Using a MultipartResolver with __Servlet 3.0__
=== __Servlet 3.0__
In order to use Servlet 3.0 based multipart parsing, you need to mark the
`DispatcherServlet` with a `"multipart-config"` section in `web.xml`, or with a
@ -3475,7 +3472,7 @@ you can add the `StandardServletMultipartResolver` to your Spring configuration:
[[mvc-multipart-forms]]
=== Handling a file upload in a form
=== Browser upload
After the `MultipartResolver` completes its job, the request is processed like any
other. First, create a form with a file input that will allow the user to upload a form.
The encoding attribute ( `enctype="multipart/form-data"`) lets the browser know how to
@ -3554,7 +3551,7 @@ the method parameter:
[[mvc-multipart-forms-non-browsers]]
=== Handling a file upload request from programmatic clients
=== REST multipart
Multipart requests can also be submitted from non-browser clients in a RESTful service
scenario. All of the above examples and configuration apply here as well. However,
unlike browsers that typically submit files and simple form fields, a programmatic
@ -3614,12 +3611,10 @@ converted with the help of the `MappingJackson2HttpMessageConverter`.
[[mvc-exceptionhandlers]]
== Handling exceptions
== Exception handling
[[mvc-exceptionhandlers-resolver]]
=== HandlerExceptionResolver
[[mvc-exceptionhandlers-overview]]
=== Overview
Spring `HandlerExceptionResolver` implementations deal with unexpected exceptions that
occur during controller execution. A `HandlerExceptionResolver` somewhat resembles the
@ -3693,7 +3688,7 @@ value converted with message converters and written to the response stream.
[[mvc-ann-rest-spring-mvc-exceptions]]
=== Handling Standard Spring MVC Exceptions
=== Framework exceptions
Spring MVC may raise a number of exceptions while processing a request. The
`SimpleMappingExceptionResolver` can easily map any exception to a default error view as
needed. However, when working with clients that interpret responses in an automated way
@ -3770,7 +3765,7 @@ response and write error content with message converters. See the
[[mvc-ann-rest-exceptions]]
=== REST Controller Exception Handling
=== REST API exceptions
An `@RestController` may use `@ExceptionHandler` methods that return a
`ResponseEntity` to provide both a response status and error details in the body
@ -3793,7 +3788,7 @@ See `ResponseEntityExceptionHandler`.
[[mvc-ann-annotated-exceptions]]
=== Annotating Business Exceptions With @ResponseStatus
=== Annotated Exception
A business exception can be annotated with `@ResponseStatus`. When the exception is
raised, the `ResponseStatusExceptionResolver` handles it by setting the status of the
@ -3803,7 +3798,7 @@ response accordingly. By default the `DispatcherServlet` registers the
[[mvc-ann-customer-servlet-container-error-page]]
=== Customizing the Default Servlet Container Error Page
=== Container error page
When the status of the response is set to an error status code and the body of the
response is empty, Servlet containers commonly render an HTML formatted error page. To
customize the default error page of the container, you can declare an `<error-page>`
@ -4034,7 +4029,7 @@ semantics of name generation for collections clearer:
[[mvc-coc-r2vnt]]
=== The View - RequestToViewNameTranslator
=== Default view name
The `RequestToViewNameTranslator` interface determines a logical `View` name when no
such logical view name is explicitly supplied. It has just one implementation, the
@ -4116,7 +4111,7 @@ that can be configured.
[[mvc-caching]]
== HTTP caching support
== HTTP caching
A good HTTP caching strategy can significantly improve the performance of a web application
and the experience of its clients. The `'Cache-Control'` HTTP response header is mostly
@ -4137,7 +4132,7 @@ Spring Web MVC application.
[[mvc-caching-cachecontrol]]
=== Cache-Control HTTP header
=== Cache-Control
Spring Web MVC supports many use cases and ways to configure "Cache-Control" headers for
an application. While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234 Section 5.2.2]
@ -4175,7 +4170,7 @@ accepted as an argument in several Spring Web MVC APIs.
----
[[mvc-caching-static-resources]]
=== HTTP caching support for static resources
=== Static resources
Static resources should be served with appropriate `'Cache-Control'` and conditional
headers for optimal performance.
@ -4216,7 +4211,7 @@ And in XML:
[[mvc-caching-etag-lastmodified]]
=== Support for the Cache-Control, ETag and Last-Modified response headers in Controllers
=== @Controller caching
Controllers can support `'Cache-Control'`, `'ETag'`, and/or `'If-Modified-Since'` HTTP requests;
this is indeed recommended if a `'Cache-Control'` header is to be set on the response.
@ -4293,7 +4288,7 @@ will check that the resource has not been modified and if it has been, it will r
[[mvc-httpcaching-shallowetag]]
=== Shallow ETag support
=== Shallow ETag
Support for ETags is provided by the Servlet filter `ShallowEtagHeaderFilter`. It is a
plain Servlet Filter, and thus can be used in combination with any web framework. The
@ -4356,7 +4351,7 @@ See <<mvc-container-config>> for more details.
[[mvc-container-config]]
== Code-based Servlet container initialization
== WebApplicationInitializer
In a Servlet 3.0+ environment, you have the option of configuring the Servlet container
programmatically as an alternative or in combination with a `web.xml` file. Below is an
example of registering a `DispatcherServlet`:
@ -4473,10 +4468,10 @@ override the `createDispatcherServlet` method.
[[mvc-config]]
== MVC Java config, XML namespace
== MVC config
[.small]#<<web-reactive.adoc#webflux-config,Same in Spring WebFlux>>#
The MVC Java config and the MVC namespace provide default configuration suitable for most
The MVC Java config and the MVC XML namespace provide default configuration suitable for most
applications along with a configuration API to customize it.
For more advanced customizations, not available in the configuration API, see
@ -4488,7 +4483,7 @@ MVC namespace but if you want to learn more, see <<mvc-servlet-special-bean-type
[[mvc-config-enable]]
=== Enable the Configuration
=== Enable MVC Config
[.small]#<<web-reactive.adoc#webflux-config-enable,Same in Spring WebFlux>>#
In Java config use the `@EnableWebMvc` annotation:
@ -4529,7 +4524,7 @@ available on the classpath -- for JSON, XML, etc.
[[mvc-config-customize]]
=== Configuration Mechanism
=== MVC Config API
[.small]#<<web-reactive.adoc#webflux-config-customize,Same in Spring WebFlux>>#
In Java config implement `WebMvcConfigurer` interface:
@ -4553,7 +4548,7 @@ available.
[[mvc-config-conversion]]
=== Conversion and Formatting
=== Type conversion
[.small]#<<web-reactive.adoc#webflux-config-conversion,Same in Spring WebFlux>>#
By default formatters for `Number` and `Date` types are installed, including support for
@ -4738,7 +4733,7 @@ In XML, the same:
[[mvc-config-content-negotiation]]
=== Requested Content Types
=== Content Types
[.small]#<<web-reactive.adoc#webflux-config-content-negotiation,Same in Spring WebFlux>>#
You can configure how Spring MVC determines the requested media types from the request --
@ -5109,7 +5104,7 @@ match to incoming URLs without versions -- e.g. `"/jquery/jquery.min.js"` to
[[mvc-default-servlet-handler]]
=== "Default" Servlet Handler
=== Default Servlet
This allows for mapping the `DispatcherServlet` to "/" (thus overriding the mapping
of the container's default Servlet), while still allowing static resource requests to be
@ -5243,7 +5238,7 @@ In XML, the same:
[[mvc-config-advanced-java]]
=== Advanced Config Mode
=== Advanced Java Config
[.small]#<<web-reactive.adoc#webflux-config-advanced-java,Same in Spring WebFlux>>#
`@EnableWebMvc` imports `DelegatingWebMvcConfiguration` that (1) provides default Spring
@ -5271,7 +5266,7 @@ the classpath.
[[mvc-config-advanced-xml]]
=== Advanced MVC Namespace
=== Advanced XML Config
The MVC namespace does not have an advanced mode. If you need to customize a property on
a bean that you can't change otherwise, you can use the `BeanPostProcessor` lifecycle

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

@ -1,11 +1,10 @@
[[websocket]]
= Servlet-based WebSocket Support
= WebSockets
:doc-spring-security: {doc-root}/spring-security/site/docs/current/reference
This part of the reference documentation covers Spring Framework's support for
WebSocket-style messaging in web applications including use of STOMP as an
application level WebSocket sub-protocol.
This part of the reference documentation covers the Spring Framework support for Servlet stack
based WebSocket messaging including use of STOMP as a a WebSocket sub-protocol.
<<websocket-intro>> establishes a frame of mind in which to think about
WebSocket, covering adoption challenges, design considerations, and thoughts on
@ -183,7 +182,7 @@ As explained in the <<websocket-intro-sub-protocol,introduction>>, direct use of
WebSocket API is too low level for applications -- until assumptions are made about the
format of a message there is little a framework can do to interpret messages or route
them via annotations. This is why applications should consider using a sub-protocol
and Spring's <<websocket-stomp,STOMP over WebSocket>> support.
and Spring's <<websocket-stomp>> support.
When using a higher level protocol, the details of the WebSocket API become less
relevant, much like the details of TCP communication are not exposed to applications
@ -194,7 +193,7 @@ directly.
[[websocket-server-handler]]
=== Create and Configure a WebSocketHandler
=== WebSocketHandler
Creating a WebSocket server is as simple as implementing `WebSocketHandler` or more
likely extending either `TextWebSocketHandler` or `BinaryWebSocketHandler`:
@ -274,7 +273,7 @@ into other HTTP serving environments with the help of
[[websocket-server-handshake]]
=== Customizing the WebSocket Handshake
=== WebSocket Handshake
The easiest way to customize the initial HTTP WebSocket handshake request is through
a `HandshakeInterceptor`, which exposes "before" and "after" the handshake methods.
Such an interceptor can be used to preclude the handshake or to make any attributes
@ -333,20 +332,20 @@ Both the Java-config and XML namespace make it possible to configure a custom
`HandshakeHandler`.
[[websocket-server-decorators]]
=== WebSocketHandler Decoration
[TIP]
====
Spring provides a `WebSocketHandlerDecorator` base class that can be used to decorate
a `WebSocketHandler` with additional behavior. Logging and exception handling
implementations are provided and added by default when using the WebSocket Java-config
or XML namespace. The `ExceptionWebSocketHandlerDecorator` catches all uncaught
exceptions arising from any WebSocketHandler method and closes the WebSocket
session with status `1011` that indicates a server error.
====
[[websocket-server-deployment]]
=== Deployment Considerations
=== Deployment
The Spring WebSocket API is easy to integrate into a Spring MVC application where
the `DispatcherServlet` serves both HTTP WebSocket handshake as well as other
HTTP requests. It is also easy to integrate into other HTTP processing scenarios
@ -419,7 +418,7 @@ Java initialization API, if required:
----
[[websocket-server-runtime-configuration]]
=== Configuring the WebSocket Engine
=== Server config
Each underlying WebSocket engine exposes configuration properties that control
runtime characteristics such as the size of message buffer sizes, idle timeout,
@ -545,7 +544,7 @@ or WebSocket XML namespace:
----
[[websocket-server-allowed-origins]]
=== Configuring allowed origins
=== Allowed origins
As of Spring Framework 4.1.5, the default behavior for WebSocket and SockJS is to accept
only _same origin_ requests. It is also possible to allow _all_ or a specified list of origins.
@ -617,7 +616,7 @@ XML configuration equivalent:
[[websocket-fallback]]
== SockJS Fallback Options
== SockJS Fallback
As explained in the <<websocket-into-fallback-options,introduction>>, WebSocket is not
supported in all browsers yet and may be precluded by restrictive network proxies.
This is why Spring provides fallback options that emulate the WebSocket API as close
@ -625,7 +624,7 @@ as possible based on the https://github.com/sockjs/sockjs-protocol[SockJS protoc
(version 0.3.3).
[[websocket-fallback-sockjs-overview]]
=== Overview of SockJS
=== Overview
The goal of SockJS is to let applications use a WebSocket API but fall back to
non-WebSocket alternatives when necessary at runtime, i.e. without the need to
@ -748,7 +747,7 @@ transport types supported by browser. The client also provides several
configuration options, for example, to specify which transports to include.
[[websocket-fallback-xhr-vs-iframe]]
=== HTTP Streaming in IE 8, 9: Ajax/XHR vs IFrame
=== IE 8, 9
Internet Explorer 8 and 9 are and will remain common for some time. They are
a key reason for having SockJS. This section covers important
@ -829,7 +828,7 @@ https://github.com/sockjs/sockjs-client/[SockJS client] page.
====
[[websocket-fallback-sockjs-heartbeat]]
=== Heartbeat Messages
=== Heartbeats
The SockJS protocol requires servers to send heartbeat messages to preclude proxies
from concluding a connection is hung. The Spring SockJS configuration has a property
@ -850,7 +849,7 @@ with default settings based on the number of available processors. Applications
should consider customizing the settings according to their specific needs.
[[websocket-fallback-sockjs-servlet3-async]]
=== Servlet 3 Async Requests
=== Client disconnects
HTTP streaming and HTTP long polling SockJS transports require a connection to remain
open longer than usual. For an overview of these techniques see
@ -878,7 +877,7 @@ log category to TRACE.
====
[[websocket-fallback-cors]]
=== CORS Headers for SockJS
=== SockJS and CORS
If you allow cross-origin requests (see <<websocket-server-allowed-origins>>), the SockJS protocol
uses CORS for cross-domain support in the XHR streaming and polling transports. Therefore
@ -905,7 +904,7 @@ SockJS endpoint prefix thus letting Spring's `SockJsService` handle it.
[[websocket-fallback-sockjs-client]]
=== SockJS Client
=== SockJsClient
A SockJS Java client is provided in order to connect to remote SockJS endpoints without
using a browser. This can be especially useful when there is a need for bidirectional
@ -986,7 +985,7 @@ public class WebSocketConfig extends WebSocketMessageBrokerConfigurationSupport
[[websocket-stomp]]
== STOMP Over WebSocket Messaging Architecture
== STOMP Sub-protocol
The WebSocket protocol defines two types of messages, text and binary, but their
content is undefined. It's expected that the client and server may agree on using
a sub-protocol (i.e. a higher-level protocol) to define message semantics.
@ -997,7 +996,7 @@ messages.
[[websocket-stomp-overview]]
=== Overview of STOMP
=== Overview
http://stomp.github.io/stomp-specification-1.2.html#Abstract[STOMP] is a simple
text-oriented messaging protocol that was originally created for scripting languages
such as Ruby, Python, and Perl to connect to enterprise message brokers. It is
@ -1102,7 +1101,7 @@ Spring MVC provides a programming model based on HTTP.
[[websocket-stomp-enable]]
=== Enable STOMP over WebSocket
=== Enable STOMP
The Spring Framework provides support for using STOMP over WebSocket through
the +spring-messaging+ and +spring-websocket+ modules.
Here is an example of exposing a STOMP WebSocket/SockJS endpoint at the URL path
@ -1317,7 +1316,7 @@ kinds of arguments and return values supported.
[[websocket-stomp-handle-annotations]]
=== Annotation Message Handling
=== Handler methods
The `@MessageMapping` annotation is supported on methods of `@Controller` classes.
It can be used for mapping methods to message destinations and can also be combined
@ -1397,7 +1396,7 @@ change to `<tx:annotation-driven proxy-target-class="true" />`.
[[websocket-stomp-handle-send]]
=== Sending Messages
=== Send Messages
What if you want to send messages to connected clients from any part of the
application? Any application component can send messages to the `"brokerChannel"`.
@ -1449,7 +1448,7 @@ See <<websocket-stomp-destination-separator>>.
[[websocket-stomp-handle-broker-relay]]
=== Full-Featured Broker
=== External Broker
The simple broker is great for getting started but supports only a subset of
STOMP commands (e.g. no acks, receipts, etc.), relies on a simple message
@ -1531,7 +1530,7 @@ subscribed WebSocket clients.
In effect, the broker relay enables robust and scalable message broadcasting.
[[websocket-stomp-handle-broker-relay-configure]]
=== Connections To Full-Featured Broker
=== Connect to Broker
A STOMP broker relay maintains a single "system" TCP connection to the broker.
This connection is used for messages originating from the server-side application
@ -1576,7 +1575,7 @@ the TCP connection is established is different from the host providing the
cloud-based STOMP service.
[[websocket-stomp-destination-separator]]
=== Using Dot as Separator in @MessageMapping Destinations
=== Dot as Separator
Although slash-separated path patterns are familiar to web developers, in messaging
it is common to use a "." as the separator, for example in the names of topics, queues,
@ -1697,7 +1696,7 @@ that ensures the user HTTP session does not expire when the WebSocket session is
[[websocket-stomp-authentication-token-based]]
=== Token-based Authentication
=== Token Authentication
https://github.com/spring-projects/spring-security-oauth[Spring Security OAuth]
provides support for token based security including JSON Web Token (JWT).
@ -1903,7 +1902,7 @@ of the `message-broker` element in XML.
[[websocket-stomp-appplication-context-events]]
=== Listening To ApplicationContext Events and Intercepting Messages
=== Events and Interception
Several `ApplicationContext` events (listed below) are published and can be
received by implementing Spring's `ApplicationListener` interface.
@ -2162,7 +2161,7 @@ shown in the examples above.
[[websocket-stomp-configuration-performance]]
=== Configuration and Performance
=== Performance
There is no silver bullet when it comes to performance. Many factors may
affect it including the size of messages, the volume, whether application
@ -2325,7 +2324,7 @@ through any other application instances.
[[websocket-stomp-stats]]
=== Runtime Monitoring
=== Monitoring
When using `@EnableWebSocketMessageBroker` or `<websocket:message-broker>` key
infrastructure components automatically gather stats and counters that provide
@ -2382,7 +2381,7 @@ SockJS Task Scheduler:: stats from thread pool of the SockJS task scheduler whic
STOMP level the SockJS heartbeats are disabled.
[[websocket-stomp-testing]]
=== Testing Annotated Controller Methods
=== Testing
There are two main approaches to testing applications using Spring's STOMP over
WebSocket support. The first is to write server-side tests verifying the functionality