Skip to content

Commit c209b67

Browse files
rstoyanchevrstoyanchev
committed
Update reference docs on content negotiation config
1 parent 4badf25 commit c209b67

File tree

2 files changed

+57
-27
lines changed

2 files changed

+57
-27
lines changed

‎src/reference/docbook/mvc.xml

Lines changed: 50 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5023,17 +5023,27 @@ public class WebConfig extends WebMvcConfigurerAdapter {
50235023
<section xml:id="mvc-config-content-negotiation">
50245024
<title>Configuring Content Negotiation</title>
50255025

5026-
<para>You can configure how Spring MVC determines requested media types for content negotiation purposes.
5027-
The available strategies are to check the request path extension, a
5028-
request parameter, the "Accept" header, and also to use a default content type.</para>
5029-
5030-
<para>By default the path extension is checked first and the "Accept"
5031-
header is checked second. The path extension check recognizes ".json" if Jackson is available,
5032-
".xml" if JAXB2 is available, and ".atom" and ".rss" if the Rome library is available.
5033-
It also uses the <classname>ServletContext</classname> and the <emphasis>Java Activation Framework</emphasis>
5034-
to perform lookups as a fallback option.</para>
5035-
5036-
<para>An example of customizing content negotiation in Java:</para>
5026+
<para>Staring with Spring Framework 3.2, you can configure how Spring MVC
5027+
determines the requested media types from the client for request mapping
5028+
as well as for content negotiation purposes. The available options are
5029+
to check the file extension in the request URI, the "Accept" header,
5030+
a request parameter, as well as to fall back on a default content type.
5031+
By default, file extension in the request URI is checked first and
5032+
the "Accept" header is checked next.</para>
5033+
5034+
<para>For file extensions in the request URI, the MVC Java config and
5035+
the MVC namespace, automatically register extensions such as
5036+
<filename>.json</filename>, <filename>.xml</filename>,
5037+
<filename>.rss</filename>, and <filename>.atom</filename> if the
5038+
corresponding dependencies such as Jackson, JAXB2, or Rome
5039+
are present on the classpath. Additional extensions may be not need
5040+
to be registered explicitly if they can be discovered via
5041+
<classname>ServletContext.getMimeType(String)</classname> or the
5042+
<emphasis>Java Activation Framework</emphasis>
5043+
(see <classname>javax.activation.MimetypesFileTypeMap</classname>).</para>
5044+
5045+
<para>Below is an example of customizing content negotiation
5046+
options through the MVC Java config:</para>
50375047

50385048
<programlisting language="java">@Configuration
50395049
@EnableWebMvc
@@ -5045,10 +5055,12 @@ public class WebConfig extends WebMvcConfigurerAdapter {
50455055
}
50465056
}</programlisting>
50475057

5048-
<para>In XML you'll need to use the <code>content-negotiation-manager</code>
5049-
property of <code>annotation-driven</code>:</para>
5058+
<para>In the MVC namespace, the <code>&lt;mvc:annotation-driven&gt;</code> element
5059+
has a <code>content-negotiation-manager</code> attribute, which expects a
5060+
<classname>ContentNegotiationManager</classname> that in turn can be created
5061+
with a <classname>ContentNegotiationManagerFactoryBean</classname>:</para>
50505062

5051-
<programlisting language="xml">&lt;mvc:annotation-driven content-negotiation-manager="contentNegotiationManager" /&gt;
5063+
<programlisting language="xml">&lt;mvc:annotation-driven content-negotiation-manager="contentNegotiationManager" /&gt;
50525064

50535065
&lt;bean id="contentNegotiationManager" class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean"&gt;
50545066
&lt;property name="favorPathExtension" value="false" /&gt;
@@ -5061,6 +5073,30 @@ public class WebConfig extends WebMvcConfigurerAdapter {
50615073
&lt;/property&gt;
50625074
&lt;/bean&gt;</programlisting>
50635075

5076+
<para>If not using the MVC Java config or the MVC namespace, you'll need
5077+
to create an instance of <classname>ContentNegotiationManager</classname>
5078+
and use it to configure
5079+
<classname>RequestMappingHandlerMapping</classname> for request mapping
5080+
purposes, and <classname>RequestMappingHandlerAdapter</classname> and
5081+
<classname>ExceptionHandlerExceptionResolver</classname> for
5082+
content negotiation purposes.</para>
5083+
5084+
<para>Note that <classname>ContentNegotiatingViewResolver</classname>
5085+
now can also be configured with a <code>ContentNegotiatingViewResolver</code>,
5086+
so you can use one instance throughout Spring MVC.</para>
5087+
5088+
<para>In more advanced cases, it may be useful to configure
5089+
multiple <classname>ContentNegotiationManager</classname> instances
5090+
that in turn may contain custom
5091+
<classname>ContentNegotiationStrategy</classname> implementations.
5092+
For example you could configure
5093+
<classname>ExceptionHandlerExceptionResolver</classname> with
5094+
a <classname>ContentNegotiationManager</classname> that always
5095+
resolves the requested media type to <filename>"application/json"</filename>.
5096+
Or you may want to plug a custom strategy that has some logic to select
5097+
a default content type (e.g. either XML or JSON) if no content
5098+
types were requested.</para>
5099+
50645100
</section>
50655101

50665102
<section xml:id="mvc-config-view-controller">

‎src/reference/docbook/new-in-3.2.xml

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -56,26 +56,20 @@
5656

5757
<para>A <interfacename>ContentNeogtiationStrategy</interfacename> is now
5858
available for resolving the requested media types from an incoming
59-
request. The available implementations are based on path extension,
60-
request parameter, 'Accept' header, and a fixed default content type.
59+
request. The available implementations are based on the file extension,
60+
query parameter, the 'Accept' header, or a fixed content type.
6161
Equivalent options were previously available only in the
6262
ContentNegotiatingViewResolver but are now available throughout.</para>
6363

6464
<para><classname>ContentNegotiationManager</classname> is the central
65-
class to use when configuring content negotiation options. It accepts one
66-
or more ContentNeogtiationStrategy instances and delegates to them. It can
67-
be plugged into <classname>RequestMappingHandlerMapping</classname>,
68-
<classname>RequestMappingHandlerAdapter</classname>,
69-
<classname>ExceptionHandlerExceptionResolver</classname>, and
70-
<classname>ContentNegotiatingViewResolver</classname>. The MVC namespace
71-
and the MVC JavaConfig provide convenient options to configure all
72-
that.</para>
65+
class to use when configuring content negotiation options.
66+
For more details see <xref linkend="mvc-config-content-negotiation" />.</para>
7367

7468
<para>The introduction of <classname>ContentNegotiationManger</classname>
75-
also enables smart suffix pattern matching for incoming requests. See
69+
also enables selective suffix pattern matching for incoming requests.
70+
For more details, see the Javadoc of
7671
<link
77-
xl:href="https://github.com/SpringSource/spring-framework/commit/4fd7645">commit
78-
message.</link></para>
72+
xl:href="http://static.springsource.org/spring-framework/docs/3.2.0.BUILD-SNAPSHOT/api/org/springframework/web/servlet/mvc/method/annotation/RequestMappingHandlerMapping.html#setUseRegisteredSuffixPatternMatch(boolean)">RequestMappingHandlerMapping.setUseRegisteredSuffixPatternMatch</link>.</para>
7973
</section>
8074

8175
<section xml:id="new-in-3.2-webmvc-controller-advice">

0 commit comments

Comments
 (0)