From 9998c63ee4d4a3987d50c1d4ad8afade6a8b6646 Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Fri, 6 Oct 2017 13:11:15 -0400 Subject: [PATCH] Compact headings in Web Servlet section Optimized for viewing in left TOC. --- src/docs/asciidoc/web/integration.adoc | 10 +- src/docs/asciidoc/web/webflux.adoc | 6 +- src/docs/asciidoc/web/webmvc-cors.adoc | 12 +- src/docs/asciidoc/web/webmvc-view.adoc | 63 ++++--- src/docs/asciidoc/web/webmvc.adoc | 239 ++++++++++++------------- src/docs/asciidoc/web/websocket.adoc | 65 ++++--- 6 files changed, 193 insertions(+), 202 deletions(-) diff --git a/src/docs/asciidoc/web/integration.adoc b/src/docs/asciidoc/web/integration.adoc index f49d2a5009..4c3a241bb1 100644 --- a/src/docs/asciidoc/web/integration.adoc +++ b/src/docs/asciidoc/web/integration.adoc @@ -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. diff --git a/src/docs/asciidoc/web/webflux.adoc b/src/docs/asciidoc/web/webflux.adoc index 76708c1c18..d5911efc5c 100644 --- a/src/docs/asciidoc/web/webflux.adoc +++ b/src/docs/asciidoc/web/webflux.adoc @@ -435,7 +435,7 @@ of defaults along with the ability to override or replace those defaults. [[webflux-dispatcher-handler]] -== The DispatcherHandler +== DispatcherHandler [.small]#<># 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]#<># 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]#<># In your Java config implement the `WebFluxConfigurer` interface: diff --git a/src/docs/asciidoc/web/webmvc-cors.adoc b/src/docs/asciidoc/web/webmvc-cors.adoc index e684aae26f..c59df9a9a1 100644 --- a/src/docs/asciidoc/web/webmvc-cors.adoc +++ b/src/docs/asciidoc/web/webmvc-cors.adoc @@ -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 diff --git a/src/docs/asciidoc/web/webmvc-view.adoc b/src/docs/asciidoc/web/webmvc-view.adoc index 77aacec53c..ae09244e54 100644 --- a/src/docs/asciidoc/web/webmvc-view.adoc +++ b/src/docs/asciidoc/web/webmvc-view.adoc @@ -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 `` 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 <> 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 diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index 0e7c526658..40a14cff23 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -19,7 +19,7 @@ covers Spring WebFlux. [[mvc-servlet]] -== The DispatcherServlet +== DispatcherServlet [.small]#<># 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 <>). +(see example under <>). ==== 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]#<># 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]#<># 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]#<># 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]#<># 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 ``. [[mvc-ann-requestmapping-uri-templates]] -==== URI Path Patterns +==== URI patterns [.small]#<># @@ -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]#<># @@ -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]#<># 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]#<># 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]#<># @@ -849,7 +849,7 @@ instead. [[mvc-ann-requestmapping-head-options]] -==== HTTP HEAD and OPTIONS +==== HTTP HEAD, OPTIONS [.small]#<># `@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]#<># `@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]#<># 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]#<># 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 <>. [[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 <> 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>`. [[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 <>) or by registering `Formatters` the `FormattingConversionService` (see <>). -[[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 <> 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 <>. @@ -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 <>, 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 <> 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 <> 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 <>). 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 `` @@ -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 <> 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]#<># -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 <># 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]#<># In Java config implement `WebMvcConfigurer` interface: @@ -4553,7 +4548,7 @@ available. [[mvc-config-conversion]] -=== Conversion and Formatting +=== Type conversion [.small]#<># 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]#<># 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]#<># `@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 diff --git a/src/docs/asciidoc/web/websocket.adoc b/src/docs/asciidoc/web/websocket.adoc index ecd6afa5cd..d737f864d5 100644 --- a/src/docs/asciidoc/web/websocket.adoc +++ b/src/docs/asciidoc/web/websocket.adoc @@ -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. <> 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 <>, 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 <> support. +and Spring's <> 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 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 <>), 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 ``. [[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-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 `` 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