From ba02b5761e75ec1f6f9b421aa15bb9918c71aa75 Mon Sep 17 00:00:00 2001 From: Sebastien Deleuze Date: Wed, 23 Aug 2017 16:00:26 +0200 Subject: [PATCH] Provide distinct Web and Reactive Web sections This change allows much more usable TOC for the reactive stack and will make WebFlux documentation easier to contribute thanks to a clearer split between both stacks. Issue: SPR-15149 --- src/docs/asciidoc/index.adoc | 6 +- src/docs/asciidoc/integration.adoc | 1 + src/docs/asciidoc/reactive-web.adoc | 58 ++++++++ src/docs/asciidoc/web.adoc | 27 ++-- ...{web-integration.adoc => integration.adoc} | 0 ...unctional.adoc => webflux-functional.adoc} | 0 .../web/{web-flux.adoc => webflux.adoc} | 78 ++--------- .../web/{web-cors.adoc => webmvc-cors.adoc} | 4 +- .../web/{web-view.adoc => webmvc-view.adoc} | 132 +++++++++--------- .../web/{web-mvc.adoc => webmvc.adoc} | 2 +- .../{web-websocket.adoc => websocket.adoc} | 2 +- 11 files changed, 158 insertions(+), 152 deletions(-) create mode 100644 src/docs/asciidoc/reactive-web.adoc rename src/docs/asciidoc/web/{web-integration.adoc => integration.adoc} (100%) rename src/docs/asciidoc/web/{web-flux-functional.adoc => webflux-functional.adoc} (100%) rename src/docs/asciidoc/web/{web-flux.adoc => webflux.adoc} (83%) rename src/docs/asciidoc/web/{web-cors.adoc => webmvc-cors.adoc} (99%) rename src/docs/asciidoc/web/{web-view.adoc => webmvc-view.adoc} (97%) rename src/docs/asciidoc/web/{web-mvc.adoc => webmvc.adoc} (99%) rename src/docs/asciidoc/web/{web-websocket.adoc => websocket.adoc} (99%) diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index e4545909dc7..9a5dbcbc6ff 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -13,7 +13,7 @@ IoC container, with any web framework on top, but you can also use only the transaction management, remote access to your logic through RMI or web services, and various options for persisting your data. It offers full-featured web frameworks such as <> -and <>; and it enables you to +and <>; and it enables you to integrate <> transparently into your software. This document is a reference guide to Spring Framework features. Questions on the @@ -29,7 +29,9 @@ This reference document provides the following sections: * <> -* <> +* The Web with 2 flavors: + ** <> + ** <> * <> diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index d68e6b7e895..2710b74e9f1 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -9120,3 +9120,4 @@ policies and different topologies which other solutions do not (take for example because there would no backing support. Such functionality should be controlled directly through the backing cache, when configuring it or through its native API. +include::web/integration.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/reactive-web.adoc b/src/docs/asciidoc/reactive-web.adoc new file mode 100644 index 00000000000..0c8c278c089 --- /dev/null +++ b/src/docs/asciidoc/reactive-web.adoc @@ -0,0 +1,58 @@ +[[spring-reactive-web]] += Reactive Web +:doc-root: https://docs.spring.io +:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework +:toc: left +:toclevels: 3 + +This part of the documentation covers support for web applications designed to run on a +reactive web stack (Reactive Streams API + non-blocking runtime) using <>, +including its <>. + +[[spring-reactive-web-intro]] +== Introduction + + +[[spring-reactive-web-intro-reactive-programming]] +=== What is Reactive Programming? + +In plain terms reactive programming is about non-blocking applications that are asynchronous +and event-driven and require a small number of threads to scale vertically (i.e. within the +JVM) rather than horizontally (i.e. through clustering). + +A key aspect of reactive applications is the concept of backpressure which is +a mechanism to ensure producers don't overwhelm consumers. For example in a pipeline +of reactive components extending from the database to the HTTP response when the +HTTP connection is too slow the data repository can also slow down or stop completely +until network capacity frees up. + +Reactive programming also leads to a major shift from imperative to declarative async +composition of logic. It is comparable to writing blocking code vs using the +`CompletableFuture` from Java 8 to compose follow-up actions via lambda expressions. + +For a longer introduction check the blog series +https://spring.io/blog/2016/06/07/notes-on-reactive-programming-part-i-the-reactive-landscape["Notes on Reactive Programming"] +by Dave Syer. + + +[[spring-reactive-web-intro-reactive-api]] +=== Reactive API and Building Blocks + +Spring Framework 5 embraces +https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams[Reactive Streams] +as the contract for communicating backpressure across async components and +libraries. Reactive Streams is a specification created through industry collaboration that +has also been adopted in Java 9 as `java.util.concurrent.Flow`. + +The Spring Framework uses https://projectreactor.io/[Reactor] internally for its own +reactive support. Reactor is a Reactive Streams implementation that further extends the +basic Reactive Streams `Publisher` contract with the `Flux` and `Mono` composable API +types to provide declarative operations on data sequences of `0..N` and `0..1`. + +The Spring Framework exposes `Flux` and `Mono` in many of its own reactive APIs. +At the application level however, as always, Spring provides choice and fully supports +the use of RxJava. For more on reactive types check the post +https://spring.io/blog/2016/04/19/understanding-reactive-types["Understanding Reactive Types"] +by Sebastien Deleuze. + +include::web/webflux.adoc[leveloffset=+1] \ No newline at end of file diff --git a/src/docs/asciidoc/web.adoc b/src/docs/asciidoc/web.adoc index 679d6195ff3..e093cc1794f 100644 --- a/src/docs/asciidoc/web.adoc +++ b/src/docs/asciidoc/web.adoc @@ -1,26 +1,25 @@ [[spring-web]] -= The Web += Web :doc-root: https://docs.spring.io :api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework :toc: left :toclevels: 2 -This part of the documentation covers support for web applications. As of Spring Framework 5.0 -web applications can run on a traditional Servlet stack (Servlet API + Servlet container) -or on a reactive stack (Reactive Streams API + non-blocking runtime). -The first few chapters cover the Servlet-based <> web framework -including <>, <>, and <> support. -Subsequent chapters cover the <> reactive web framework -including its <>. +This part of the documentation covers support for web applications designed to run on a +traditional Servlet stack (Servlet API + Servlet container). -include::web/web-mvc.adoc[leveloffset=+1] +Chapters cover the Servlet-based <> web framework including <>, +<>, and <> support. -include::web/web-view.adoc[leveloffset=+1] +Note that as of Spring Framework 5.0 web applications can also run on a +<> (Reactive Streams API + non-blocking runtime). -include::web/web-cors.adoc[leveloffset=+1] +include::web/webmvc.adoc[leveloffset=+1] -include::web/web-websocket.adoc[leveloffset=+1] +include::web/webmvc-view.adoc[leveloffset=+1] + +include::web/webmvc-cors.adoc[leveloffset=+1] + +include::web/websocket.adoc[leveloffset=+1] -include::web/web-flux.adoc[leveloffset=+1] -include::web/web-integration.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/web/web-integration.adoc b/src/docs/asciidoc/web/integration.adoc similarity index 100% rename from src/docs/asciidoc/web/web-integration.adoc rename to src/docs/asciidoc/web/integration.adoc diff --git a/src/docs/asciidoc/web/web-flux-functional.adoc b/src/docs/asciidoc/web/webflux-functional.adoc similarity index 100% rename from src/docs/asciidoc/web/web-flux-functional.adoc rename to src/docs/asciidoc/web/webflux-functional.adoc diff --git a/src/docs/asciidoc/web/web-flux.adoc b/src/docs/asciidoc/web/webflux.adoc similarity index 83% rename from src/docs/asciidoc/web/web-flux.adoc rename to src/docs/asciidoc/web/webflux.adoc index aeee32a80da..3cd5ac25ae7 100644 --- a/src/docs/asciidoc/web/web-flux.adoc +++ b/src/docs/asciidoc/web/webflux.adoc @@ -1,66 +1,12 @@ [[webflux]] -= Spring WebFlux framework - -This section provides basic information on the reactive programming -support for Web applications in Spring Framework 5. - - -[[webflux-intro]] -== Introduction - - -[[webflux-intro-reactive-programming]] -=== What is Reactive Programming? - -In plain terms reactive programming is about non-blocking applications that are asynchronous -and event-driven and require a small number of threads to scale vertically (i.e. within the -JVM) rather than horizontally (i.e. through clustering). - -A key aspect of reactive applications is the concept of backpressure which is -a mechanism to ensure producers don't overwhelm consumers. For example in a pipeline -of reactive components extending from the database to the HTTP response when the -HTTP connection is too slow the data repository can also slow down or stop completely -until network capacity frees up. - -Reactive programming also leads to a major shift from imperative to declarative async -composition of logic. It is comparable to writing blocking code vs using the -`CompletableFuture` from Java 8 to compose follow-up actions via lambda expressions. - -For a longer introduction check the blog series -https://spring.io/blog/2016/06/07/notes-on-reactive-programming-part-i-the-reactive-landscape["Notes on Reactive Programming"] -by Dave Syer. - - -[[webflux-intro-reactive-api]] -=== Reactive API and Building Blocks - -Spring Framework 5 embraces -https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams[Reactive Streams] -as the contract for communicating backpressure across async components and -libraries. Reactive Streams is a specification created through industry collaboration that -has also been adopted in Java 9 as `java.util.concurrent.Flow`. - -The Spring Framework uses https://projectreactor.io/[Reactor] internally for its own -reactive support. Reactor is a Reactive Streams implementation that further extends the -basic Reactive Streams `Publisher` contract with the `Flux` and `Mono` composable API -types to provide declarative operations on data sequences of `0..N` and `0..1`. - -The Spring Framework exposes `Flux` and `Mono` in many of its own reactive APIs. -At the application level however, as always, Spring provides choice and fully supports -the use of RxJava. For more on reactive types check the post -https://spring.io/blog/2016/04/19/understanding-reactive-types["Understanding Reactive Types"] -by Sebastien Deleuze. - - -[[webflux-feature-overview]] -== Spring WebFlux Module += Spring WebFlux Spring Framework 5 includes a new `spring-webflux` module. The module contains support for reactive HTTP and WebSocket clients as well as for reactive server web applications including REST, HTML browser, and WebSocket style interactions. [[webflux-server]] -=== Server Side +== Server Side On the server-side WebFlux supports 2 distinct programming models: @@ -85,7 +31,7 @@ REST-style JSON and XML serialization and deserialization is supported on top as a `Flux`, and so is HTML view rendering and Server-Sent Events. [[webflux-server-annotation]] -==== Annotation-based Programming Model +=== Annotation-based Programming Model The same `@Controller` programming model and the same annotations used in Spring MVC are also supported in WebFlux. The main difference is that the underlying core, @@ -123,11 +69,11 @@ public class PersonController { } ---- -include::web-flux-functional.adoc[leveloffset=+3] +include::webflux-functional.adoc[leveloffset=+2] [[webflux-client]] -=== Client Side +== Client Side WebFlux includes a functional, reactive `WebClient` that offers a fully non-blocking and reactive alternative to the `RestTemplate`. It exposes network @@ -161,7 +107,7 @@ still based and relies on `InputStream` and `OutputStream`. [[webflux-http-body]] -=== Request and Response Body Conversion +== Request and Response Body Conversion The `spring-core` module provides reactive `Encoder` and `Decoder` contracts that enable the serialization of a `Flux` of bytes to and from typed objects. @@ -216,7 +162,7 @@ default as following: [[webflux-websocket-support]] -=== Reactive WebSocket Support +== Reactive WebSocket Support WebFlux includes reactive WebSocket client and server support. Both client and server are supported on the Java WebSocket API @@ -257,7 +203,7 @@ client.execute("ws://localhost:8080/echo"), session -> {... }).blockMillis(5000) ---- [[webflux-tests]] -=== Testing +== Testing The `spring-test` module includes a `WebTestClient` that can be used to test WebFlux server endpoints with or without a running server. @@ -274,11 +220,11 @@ in the framework. [[webflux-getting-started]] -== Getting Started += Getting Started [[webflux-getting-started-boot]] -=== Spring Boot Starter +== Spring Boot Starter The Spring Boot WebFlux starter available via http://start.spring.io is the fastest way to get started. @@ -290,7 +236,7 @@ with Spring Boot to switch to a different runtime. See the Spring Boot reference documentation page for more details and instruction. [[webflux-getting-started-manual]] -=== Manual Bootstrapping +== Manual Bootstrapping This section outlines the steps to get up and running manually. @@ -365,7 +311,7 @@ Spring configuration. ==== [[webflux-getting-started-examples]] -=== Examples +== Examples You will find code examples useful to build reactive Web application in the following projects: diff --git a/src/docs/asciidoc/web/web-cors.adoc b/src/docs/asciidoc/web/webmvc-cors.adoc similarity index 99% rename from src/docs/asciidoc/web/web-cors.adoc rename to src/docs/asciidoc/web/webmvc-cors.adoc index 8dab5092864..e684aae26fa 100644 --- a/src/docs/asciidoc/web/web-cors.adoc +++ b/src/docs/asciidoc/web/webmvc-cors.adoc @@ -1,5 +1,5 @@ -[[cors]] -= Spring MVC CORS Support +[[mvc-cors]] += CORS Support == Introduction diff --git a/src/docs/asciidoc/web/web-view.adoc b/src/docs/asciidoc/web/webmvc-view.adoc similarity index 97% rename from src/docs/asciidoc/web/web-view.adoc rename to src/docs/asciidoc/web/webmvc-view.adoc index d7c24893d5d..741adc9866e 100644 --- a/src/docs/asciidoc/web/web-view.adoc +++ b/src/docs/asciidoc/web/webmvc-view.adoc @@ -1,8 +1,8 @@ -[[view]] -= Spring MVC View Technologies +[[mvc-view]] += View Technologies -[[view-introduction]] +[[mvc-view-introduction]] == Introduction One of the areas in which Spring excels is in the separation of view technologies from the rest of the MVC framework. For example, deciding to use Groovy Markup Templates @@ -13,7 +13,7 @@ briefly on how to add new ones. This chapter assumes you are already familiar wi to the MVC framework. -[[view-thymeleaf]] +[[mvc-view-thymeleaf]] == Thymeleaf http://www.thymeleaf.org/[Thymeleaf] is a good example of a view technology fitting @@ -26,7 +26,7 @@ Please refer to the http://www.thymeleaf.org/documentation.html[Thymeleaf+Spring documentation section for more details. -[[view-groovymarkup]] +[[mvc-view-groovymarkup]] == Groovy Markup Templates The http://groovy-lang.org/templating.html#_the_markuptemplateengine[Groovy Markup Template Engine] @@ -37,7 +37,7 @@ text based content. This requires Groovy 2.3.1+ on the classpath. -[[view-groovymarkup-configuration]] +[[mvc-view-groovymarkup-configuration]] === Configuration Configuring the Groovy Markup Template Engine is quite easy: @@ -78,7 +78,7 @@ The XML counterpart using the MVC namespace is: ---- -[[view-groovymarkup-example]] +[[mvc-view-groovymarkup-example]] === Example Unlike traditional template engines, this one relies on a DSL that uses the builder syntax. @@ -100,14 +100,14 @@ Here is a sample template for an HTML page: ---- -[[view-freemarker]] +[[mvc-view-freemarker]] == FreeMarker http://www.freemarker.org[FreeMarker] is a templating language that can be used as a view technology within Spring MVC applications. For details on the template language, see the http://www.freemarker.org[FreeMarker] web site. -[[view-freemarker-dependencies]] +[[mvc-view-freemarker-dependencies]] === Dependencies Your web application will need to include `freemarker-2.x.jar` in order to work with FreeMarker. Typically this is included in the `WEB-INF/lib` folder where the jars are @@ -116,7 +116,7 @@ application. It is of course assumed that you already have the `spring-webmvc.ja your `'WEB-INF/lib'` directory too! -[[view-freemarker-contextconfig]] +[[mvc-view-freemarker-contextconfig]] === Context configuration A suitable configuration is initialized by adding the relevant configurer bean definition to your `'{asterisk}-servlet.xml'` as shown below: @@ -147,7 +147,7 @@ definition file. ==== -[[view-freemarker-createtemplates]] +[[mvc-view-freemarker-createtemplates]] === Creating templates Your templates need to be stored in the directory specified by the `FreeMarkerConfigurer` shown above. If you use the view resolvers highlighted, then the logical view names @@ -156,7 +156,7 @@ for JSP's. So if your controller returns a ModelAndView object containing a view "welcome" then the resolver will look for the `/WEB-INF/freemarker/welcome.ftl` template. -[[views-freemarker]] +[[mvc-views-freemarker]] === Advanced FreeMarker configuration FreeMarker 'Settings' and 'SharedVariables' can be passed directly to the FreeMarker `Configuration` object managed by Spring by setting the appropriate bean properties on @@ -184,7 +184,7 @@ the `Configuration` object. -[[view-freemarker-forms]] +[[mvc-view-freemarker-forms]] === Bind support and 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 @@ -193,7 +193,7 @@ web or business tier. Spring also has support for the same functionality in Free with additional convenience macros for generating form input elements themselves. -[[view-bind-macros]] +[[mvc-view-bind-macros]] ==== The bind macros A standard set of macros are maintained within the `spring-webmvc.jar` file for both languages, so they are always available to a suitably configured application. @@ -206,7 +206,7 @@ directly, the file is called `spring.ftl` in the package `org.springframework.web.servlet.view.freemarker`. -[[view-simple-binding]] +[[mvc-view-simple-binding]] ==== Simple binding In your HTML forms (vm / ftl templates) which act as a form view for a Spring MVC controller, you can use code similar to the following to bind to field values and @@ -250,7 +250,7 @@ simplify the use of HTML escaping and these macros should be used wherever possi They are explained in the next section. -[[views-form-macros]] +[[mvc-views-form-macros]] ==== Form input generation macros Additional convenience macros for both languages simplify both binding and form generation (including validation error display). It is never necessary to use these @@ -340,7 +340,7 @@ The parameters to any of the above macros have consistent meanings: Examples of the macros are outlined below some in FTL and some in VTL. Where usage differences exist between the two languages, they are explained in the notes. -[[views-form-macros-input]] +[[mvc-views-form-macros-input]] ===== Input Fields The formInput macro takes the path parameter (command.name) and an additional attributes parameter which is empty in the example above. The macro, along with all other form @@ -381,7 +381,7 @@ The formTextarea macro works the same way as the formInput macro and accepts the parameter list. Commonly, the second parameter (attributes) will be used to pass style information or rows and cols attributes for the textarea. -[[views-form-macros-select]] +[[mvc-views-form-macros-select]] ===== Selection Fields Four selection field macros can be used to generate common UI value selection inputs in your HTML forms. @@ -455,7 +455,7 @@ user still sees the more user friendly city names. ---- -[[views-form-macros-html-escaping]] +[[mvc-views-form-macros-html-escaping]] ==== HTML escaping and XHTML compliance 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 @@ -496,7 +496,7 @@ In similar fashion, HTML escaping can be specified per field: -[[view-jsp]] +[[mvc-view-jsp]] == JSP & JSTL Spring provides a couple of out-of-the-box solutions for JSP and JSTL views. Using JSP or JSTL is done using a normal view resolver defined in the `WebApplicationContext`. @@ -516,7 +516,7 @@ somewhat. -[[view-jsp-resolver]] +[[mvc-view-jsp-resolver]] === View resolvers Just as with any other view technology you're integrating with Spring, for JSPs you'll need a view resolver that will resolve your views. The most commonly used view resolvers @@ -559,7 +559,7 @@ under the `'WEB-INF'` directory, so there can be no direct access by clients. -[[view-jsp-jstl]] +[[mvc-view-jsp-jstl]] === 'Plain-old' 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 @@ -567,7 +567,7 @@ work. -[[view-jsp-tags]] +[[mvc-view-jsp-tags]] === Additional tags facilitating development 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 @@ -580,7 +580,7 @@ information about the individual tags can be found in the appendix entitled -[[view-jsp-formtaglib]] +[[mvc-view-jsp-formtaglib]] === Using Spring's form tag library 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 @@ -596,7 +596,7 @@ Let's go through the form tags and look at an example of how each tag is used. W included generated HTML snippets where certain tags require further commentary. -[[view-jsp-formtaglib-configuration]] +[[mvc-view-jsp-formtaglib-configuration]] ==== Configuration The form tag library comes bundled in `spring-webmvc.jar`. The library descriptor is called `spring-form.tld`. @@ -613,7 +613,7 @@ page: where `form` is the tag name prefix you want to use for the tags from this library. -[[view-jsp-formtaglib-formtag]] +[[mvc-view-jsp-formtaglib-formtag]] ==== The form tag This tag renders an HTML 'form' tag and exposes a binding path to inner tags for @@ -703,16 +703,16 @@ The preceding JSP assumes that the variable name of the form backing object is ---- -[[view-jsp-formtaglib-inputtag]] +[[mvc-view-jsp-formtaglib-inputtag]] ==== The input tag This tag renders an HTML 'input' tag using the bound value and type='text' by default. -For an example of this tag, see <>. Starting with Spring +For an example of this tag, see <>. Starting with Spring 3.1 you can use other types such HTML5-specific types like 'email', 'tel', 'date', and others. -[[view-jsp-formtaglib-checkboxtag]] +[[mvc-view-jsp-formtaglib-checkboxtag]] ==== The checkbox tag This tag renders an HTML 'input' tag with type 'checkbox'. @@ -829,7 +829,7 @@ telling Spring that "__the checkbox was visible in the form and I want my object which the form data will be bound to reflect the state of the checkbox no matter what__". -[[view-jsp-formtaglib-checkboxestag]] +[[mvc-view-jsp-formtaglib-checkboxestag]] ==== The checkboxes tag This tag renders multiple HTML 'input' tags with type 'checkbox'. @@ -865,7 +865,7 @@ the label to be displayed. You can also use a custom object where you can provid property names for the value using "itemValue" and the label using "itemLabel". -[[view-jsp-formtaglib-radiobuttontag]] +[[mvc-view-jsp-formtaglib-radiobuttontag]] ==== The radiobutton tag This tag renders an HTML 'input' tag with type 'radio'. @@ -886,7 +886,7 @@ but with different values. ---- -[[view-jsp-formtaglib-radiobuttonstag]] +[[mvc-view-jsp-formtaglib-radiobuttonstag]] ==== The radiobuttons tag This tag renders multiple HTML 'input' tags with type 'radio'. @@ -909,7 +909,7 @@ label using "itemLabel". ---- -[[view-jsp-formtaglib-passwordtag]] +[[mvc-view-jsp-formtaglib-passwordtag]] ==== The password tag This tag renders an HTML 'input' tag with type 'password' using the bound value. @@ -941,7 +941,7 @@ true, like so. ---- -[[view-jsp-formtaglib-selecttag]] +[[mvc-view-jsp-formtaglib-selecttag]] ==== The select tag This tag renders an HTML 'select' element. It supports data binding to the selected @@ -977,7 +977,7 @@ like: ---- -[[view-jsp-formtaglib-optiontag]] +[[mvc-view-jsp-formtaglib-optiontag]] ==== The option tag This tag renders an HTML 'option'. It sets 'selected' as appropriate based on the bound @@ -1019,7 +1019,7 @@ like: ---- -[[view-jsp-formtaglib-optionstag]] +[[mvc-view-jsp-formtaglib-optionstag]] ==== The options tag This tag renders a list of HTML 'option' tags. It sets the 'selected' attribute as @@ -1071,7 +1071,7 @@ happen to be specified as well, the item value property will apply to the map ke the item label property will apply to the map value. -[[view-jsp-formtaglib-textareatag]] +[[mvc-view-jsp-formtaglib-textareatag]] ==== The textarea tag This tag renders an HTML 'textarea'. @@ -1087,7 +1087,7 @@ This tag renders an HTML 'textarea'. ---- -[[view-jsp-formtaglib-hiddeninputtag]] +[[mvc-view-jsp-formtaglib-hiddeninputtag]] ==== The hidden tag This tag renders an HTML 'input' tag with type 'hidden' using the bound value. To submit @@ -1110,7 +1110,7 @@ If we choose to submit the 'house' value as a hidden one, the HTML would look li ---- -[[view-jsp-formtaglib-errorstag]] +[[mvc-view-jsp-formtaglib-errorstag]] ==== The errors tag This tag renders field errors in an HTML 'span' tag. It provides access to the errors @@ -1260,7 +1260,7 @@ The HTML would look like: ---- -[[rest-method-conversion]] +[[mvc-rest-method-conversion]] ==== HTTP Method Conversion A key principle of REST is the use of the Uniform Interface. This means that all resources (URLs) can be manipulated using the same four HTTP methods: GET, PUT, POST, @@ -1320,7 +1320,7 @@ The corresponding `@Controller` method is shown below: ---- -[[view-jsp-formtaglib-html5]] +[[mvc-view-jsp-formtaglib-html5]] ==== HTML5 Tags Starting with Spring 3, the Spring form tag library allows entering dynamic attributes, which means you can enter any HTML5 specific attributes. @@ -1332,7 +1332,7 @@ is the default type. -[[view-script]] +[[mvc-view-script]] == Script templates It is possible to integrate any templating library running on top of a JSR-223 @@ -1349,7 +1349,7 @@ It has been tested with: * http://www.stuartellis.eu/articles/erb/[ERB] running on http://jruby.org[JRuby] * https://docs.python.org/2/library/string.html#template-strings[String templates] running on http://www.jython.org/[Jython] -[[view-script-dependencies]] +[[mvc-view-script-dependencies]] === Dependencies To be able to use script templates integration, you need to have available in your classpath @@ -1369,7 +1369,7 @@ for Javascript you can use http://www.webjars.org/[WebJars] to add Maven/Gradle in order to make your javascript libraries available in the classpath. -[[view-script-integrate]] +[[mvc-view-script-integrate]] === How to integrate script based templating To be able to use script templates, you have to configure it in order to specify various parameters @@ -1529,7 +1529,7 @@ for more configuration examples. -[[view-xml-marshalling]] +[[mvc-view-xml-marshalling]] == XML Marshalling View 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 @@ -1543,7 +1543,7 @@ Mappers>>. -[[view-tiles]] +[[mvc-view-tiles]] == Tiles It is possible to integrate Tiles - just as any other view technology - in web applications using Spring. The following describes in a broad way how to do this. @@ -1556,14 +1556,14 @@ This section focuses on Spring's support for Tiles v3 in the ==== -[[view-tiles-dependencies]] +[[mvc-view-tiles-dependencies]] === Dependencies To be able to use Tiles, you have to add a dependency on Tiles version 3.0.1 or higher and http://tiles.apache.org/framework/dependency-management.html[its transitive dependencies] to your project. -[[view-tiles-integrate]] +[[mvc-view-tiles-integrate]] === How to integrate Tiles 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 @@ -1620,7 +1620,7 @@ them otherwise in the file names for Tiles definitions. ==== -[[view-tiles-url]] +[[mvc-view-tiles-url]] ==== UrlBasedViewResolver The `UrlBasedViewResolver` instantiates the given `viewClass` for each view it has to @@ -1635,7 +1635,7 @@ resolve. ---- -[[view-tiles-resource]] +[[mvc-view-tiles-resource]] ==== ResourceBundleViewResolver The `ResourceBundleViewResolver` has to be provided with a property file containing @@ -1671,7 +1671,7 @@ Note that the `TilesView` class supports JSTL (the JSP Standard Tag Library) out box. -[[view-tiles-preparer]] +[[mvc-view-tiles-preparer]] ==== SimpleSpringPreparerFactory and SpringBeanPreparerFactory As an advanced feature, Spring also supports two special Tiles `PreparerFactory` @@ -1715,7 +1715,7 @@ per preparer name (as used in your Tiles definitions). -[[view-xslt]] +[[mvc-view-xslt]] == XSLT XSLT is a transformation language for XML and is popular as a view technology within web applications. XSLT can be a good choice as a view technology if your application @@ -1725,7 +1725,7 @@ XSLT in a Spring Web MVC application. -[[view-xslt-firstwords]] +[[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 @@ -1734,7 +1734,7 @@ name of our XSLT view. See <> for details of Spring Web MVC's document ready for transformation. -[[view-xslt-beandefs]] +[[mvc-view-xslt-beandefs]] ==== Bean definitions Configuration is standard for a simple Spring application. The MVC configuration has to define a `XsltViewResolver` bean and @@ -1762,7 +1762,7 @@ public class WebConfig implements WebMvcConfigurer { And we need a Controller that encapsulates our word generation logic. -[[view-xslt-controllercode]] +[[mvc-view-xslt-controllercode]] ==== Standard MVC controller code The controller logic is encapsulated in a `@Controller` class, with the @@ -1808,7 +1808,7 @@ Next, `XsltViewResolver` will resolve the "home" XSLT template file and merge th DOM document into it to generate our view. -[[view-xslt-transforming]] +[[mvc-view-xslt-transforming]] ==== Document transformation Finally, the `XsltViewResolver` will resolve the "home" XSLT template file and merge the @@ -1865,12 +1865,12 @@ This is rendered as: ---- -[[view-document]] +[[mvc-view-document]] == Document views (PDF/Excel) -[[view-document-intro]] +[[mvc-view-document-intro]] === Introduction Returning an HTML page isn't always the best way for the user to view the model output, and Spring makes it simple to generate a PDF document or an Excel spreadsheet @@ -1883,7 +1883,7 @@ for PDF generation, the iText library. -[[view-document-config]] +[[mvc-view-document-config]] === Configuration and setup 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 @@ -1891,7 +1891,7 @@ used in the XSLT example is invoked to render the same model as both a PDF docum an Excel spreadsheet (which can also be viewed or manipulated in Open Office). -[[view-document-configviews]] +[[mvc-view-document-configviews]] ==== Document view definitions 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 @@ -1913,7 +1913,7 @@ __If you want to start with a template spreadsheet or a fillable PDF form to add model data to, specify the location as the 'url' property in the view definition__ -[[view-document-configcontroller]] +[[mvc-view-document-configcontroller]] ==== Controller code 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 @@ -1921,7 +1921,7 @@ have this selected based on a URL parameter or some other logic - proof that Spr really is very good at decoupling the views from the controllers! -[[view-document-configsubclasses]] +[[mvc-view-document-configsubclasses]] ==== Subclassing for 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 @@ -2005,7 +2005,7 @@ that the Excel spreadsheet is created and downloaded automatically when you requ same page as before. -[[view-document-configsubclasspdf]] +[[mvc-view-document-configsubclasspdf]] ==== Subclassing for 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 @@ -2038,7 +2038,7 @@ document should appear listing each of the words in the model map. -[[view-feeds]] +[[mvc-view-feeds]] == Feed Views Both `AbstractAtomFeedView` and `AbstractRssFeedView` inherit from the base class `AbstractFeedView` and are used to provide Atom and RSS Feed views respectfully. They @@ -2102,7 +2102,7 @@ https://spring.io/blog/2009/03/16/adding-an-atom-view-to-an-application-using-sp -[[view-json-mapping]] +[[mvc-view-json-mapping]] == JSON Mapping View 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 @@ -2124,7 +2124,7 @@ name(s) could be customized through the `jsonpParameterNames` property. -[[view-xml-mapping]] +[[mvc-view-xml-mapping]] == XML Mapping View The `MappingJackson2XmlView` uses the https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML extension]'s `XmlMapper` diff --git a/src/docs/asciidoc/web/web-mvc.adoc b/src/docs/asciidoc/web/webmvc.adoc similarity index 99% rename from src/docs/asciidoc/web/web-mvc.adoc rename to src/docs/asciidoc/web/webmvc.adoc index 668b85300e4..0e80de8d14d 100644 --- a/src/docs/asciidoc/web/web-mvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -2689,7 +2689,7 @@ directly on `RequestMappingHandlerAdapter`. 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 -templates and XSLT views, for example. See <> for a discussion of how to integrate +templates and XSLT views, for example. See <> for a discussion of how to integrate and use a number of disparate view technologies. The two interfaces that are important to the way Spring handles views are `ViewResolver` diff --git a/src/docs/asciidoc/web/web-websocket.adoc b/src/docs/asciidoc/web/websocket.adoc similarity index 99% rename from src/docs/asciidoc/web/web-websocket.adoc rename to src/docs/asciidoc/web/websocket.adoc index c7419147e9e..ecd6afa5cdc 100644 --- a/src/docs/asciidoc/web/web-websocket.adoc +++ b/src/docs/asciidoc/web/websocket.adoc @@ -1,5 +1,5 @@ [[websocket]] -= Servlet Stack WebSocket Support += Servlet-based WebSocket Support :doc-spring-security: {doc-root}/spring-security/site/docs/current/reference