Content Negotiation Using Spring MVC

originally written by paul chapman

there are two ways to generate output using spring mvc:

• you can use the restful @responsebody approach and http message converters, typically to return data-formats like json or xml. programmatic clients, mobile apps and ajax enabled browsers are the usual clients.
• alternatively you may use view resolution . although views are perfectly capable of generating json and xml if you wish (more on that in my next post), views are normally used to generate presentation formats like html for a traditional web-application.
• actually there is a third possibility – some applications require both, and spring mvc supports such combinations easily. we will come back to that right at the end.

in either case you'll need to deal with multiple representations (or views) of the same data returned by the controller. working out which data format to return is called content negotiation .

there are three situations where we need to know what type of data-format to send in the http response:

• httpmessageconverters: determine the right converter to use.
• request mappings: map an incoming http request to different methods that return different formats.
• view resolution: pick the right view to use.

determining what format the user has requested relies on a contentnegotationstrategy . there are default implementations available out of the box, but you can also implement your own if you wish.

in this post i want to discuss how to configure and use content negotiation with spring, mostly in terms of restful controllers using http message converters. in a later post i will show how to setup content negotiation specifically for use with views using spring's contentnegotiatingviewresolver .

how does content negotiation work?

getting the right content

when making a request via http it is possible to specify what type of response you would like by setting the accept header property. web browsers have this preset to request html (among other things). in fact, if you look, you will see that browsers actually send very confusing accept headers, which makes relying on them impractical. see http://www.gethifi.com/blog/browser-rest-http-accept-headers for a nice discussion of this problem. bottom-line: accept headers are messed up and you can't normally change them either (unless you use javascript and ajax).

so, for those situations where the accept header property is not desirable, spring offers some conventions to use instead. (this was one of the nice changes in spring 3.2 making a flexible content selection strategy available across all of spring mvc not just when using views). you can configure a content negotiation strategy centrally once and it will apply wherever different formats (media types) need to be determined.

enabling content negotiation in spring mvc

spring supports a couple of conventions for selecting the format required: url suffixes and/or a url parameter. these work alongside the use of accept headers. as a result, the content-type can be requested in any of three ways. by default they are checked in this order:

• add a path extension (suffix) in the url. so, if the incoming url is something like http://myserver/myapp/accounts/list.html then html is required. for a spreadsheet the url should be http://myserver/myapp/accounts/list.xls . the suffix to media-type mapping is automatically defined via the javabeans activation framework or jaf (so activation.jar must be on the class path).
• a url parameter like this: http://myserver/myapp/accounts/list?format=xls . the name of the parameter is format by default, but this may be changed. using a parameter is disabled by default, but when enabled, it is checked second.
• finally the accept http header property is checked. this is how http is actually defined to work, but, as previously mentioned, it can be problematic to use.

the java configuration to set this up, looks like this. simply customize the predefined content negotiation manager via its configurer. note the mediatype helper class has predefined constants for most well-known media-types.

@configuration
@enablewebmvc
public class webconfig extends webmvcconfigureradapter {
 
  /**
    * setup a simple strategy: use all the defaults and return xml by default when not sure.
    */
  @override
  public void configurecontentnegotiation(contentnegotiationconfigurer configurer) {
    configurer.defaultcontenttype(mediatype.application_xml);
  }
}

when using xml configuration, the content negotiation strategy is most easily setup via the contentnegotiationmanagerfactorybean :

<!--
       setup a simple strategy:
          1. take all the defaults.
          2. return xml by default when not sure.
      -->
 <bean id="contentnegotiationmanager"
            class="org.springframework.web.accept.contentnegotiationmanagerfactorybean">
      <property name="defaultcontenttype" value="application/xml" />
 </bean>
 
<!-- make this available across all of spring mvc -->
<mvc:annotation-driven content-negotiation-manager="contentnegotiationmanager" />

the contentnegotiationmanager created by either setup is an implementation of contentnegotationstrategy that implements the ppa strategy (path extension, then parameter, then accept header) described above.

additional configuration options

in java configuration, the strategy can be fully customized using methods on the configurer:

@configuration
@enablewebmvc
public class webconfig extends webmvcconfigureradapter {
 
  /**
    *  total customization - see below for explanation.
    */
  @override
  public void configurecontentnegotiation(contentnegotiationconfigurer configurer) {
    configurer.favorpathextension(false).
            favorparameter(true).
            parametername("mediatype").
            ignoreacceptheader(true).
            usejaf(false).
            defaultcontenttype(mediatype.application_json).
            mediatype("xml", mediatype.application_xml).
            mediatype("json", mediatype.application_json);
  }
}

in xml, the strategy can be configured using methods on the factory bean:

  <!-- total customization - see below for explanation. -->
  <bean id="contentnegotiationmanager"
             class="org.springframework.web.accept.contentnegotiationmanagerfactorybean">
    <property name="favorpathextension" value="false" />
    <property name="favorparameter" value="true" />
    <property name="parametername" value="mediatype" />
    <property name="ignoreacceptheader" value="true"/>
    <property name="usejaf" value="false"/>
    <property name="defaultcontenttype" value="application/json" />
 
    <property name="mediatypes">
        <map>
            <entry key="json" value="application/json" />
            <entry key="xml" value="application/xml" />
       </map>
    </property>
</bean>

what we did, in both cases:

• disabled path extension. note that favor does not mean use one approach in preference to another, it just enables or disables it. the order of checking is always path extension, parameter, accept header.
• enable the use of the url parameter but instead of using the default parameter, format , we will use mediatype instead.
• ignore the accept header completely. this is often the best approach if most of your clients are actually web-browsers (typically making rest calls via ajax).
• don't use the jaf, instead specify the media type mappings manually – we only wish to support json and xml.

listing user accounts example

to demonstrate, i have put together a simple account listing application as our worked example – the screenshot shows a typical list of accounts in html. the complete code can be found at github: https://github.com/paulc4/mvc-content-neg .

to return a list of accounts in json or xml, i need a controller like this. we will ignore the html generating methods for now.

@controller
class accountcontroller {
    @requestmapping(value="/accounts", method=requestmethod.get)
    @responsestatus(httpstatus.ok)
    public @responsebody list<account> list(model model, principal principal) {
        return accountmanager.getaccounts(principal) );
    }
 
    // other methods ...
}

here is the content-negotiation strategy setup:

<!-- simple strategy: only path extension is taken into account -->
<bean id="cnmanager"
    class="org.springframework.web.accept.contentnegotiationmanagerfactorybean">
    <property name="favorpathextension" value="true"/>
    <property name="ignoreacceptheader" value="true" />
    <property name="defaultcontenttype" value="text/html" />
    <property name="usejaf" value="false"/>
 
    <property name="mediatypes">
        <map>
            <entry key="html" value="text/html" />
            <entry key="json" value="application/json" />
            <entry key="xml" value="application/xml" />
        </map>
    </property>
</bean>

or, using java configuration, the code looks like this:

@override
public void configurecontentnegotiation(
        contentnegotiationconfigurer configurer) {
    // simple strategy: only path extension is taken into account
    configurer.favorpathextension(true).
        ignoreacceptheader(true).
        usejaf(false).
        defaultcontenttype(mediatype.text_html).
        mediatype("html", mediatype.text_html).
        mediatype("xml", mediatype.application_xml).
        mediatype("json", mediatype.application_json);
}

provided i have jaxb2 and jackson on my classpath, spring mvc will automatically setup the necessary httpmessageconverters . my domain classes must also be marked up with jaxb2 and jackson annotations to enable conversion (otherwise the message converters don't know what to do). in response to comments (below), the annotated account class is shown below .

here is the json output from our accounts application (note path-extension in url).

how does the system know whether to convert to xml or json? because of content negotiation – any one of the three ( ppa strategy ) options discussed above will be used depending on how the contentnegotiationmanager is configured. in this case the url ends in accounts.json because the path-extension is the only strategy enabled.

in the sample code you can switch between xml or java configuration of mvc by setting an active profile in the web.xml . the profiles are "xml" and "javaconfig" respectively.

combining data and presentation formats

spring mvc's rest support builds on the existing mvc controller framework. so it is possible to have the same web-applications return information both as raw data (like json) and using a presentation format (like html).

both techniques can easily be used side by side in the same controller, like this:

@controller
class accountcontroller {
    // restful method
    @requestmapping(value="/accounts", produces={"application/xml", "application/json"})
    @responsestatus(httpstatus.ok)
    public @responsebody list<account> listwithmarshalling(principal principal) {
        return accountmanager.getaccounts(principal);
    }
 
    // view-based method
    @requestmapping("/accounts")
    public string listwithview(model model, principal principal) {
        // call restful method to avoid repeating account lookup logic
        model.addattribute( listwithmarshalling(principal) );
 
        // return the view to use for rendering the response
        return ¨accounts/list¨;
    }
}

there is a simple pattern here: the @responsebody method handles all data access and integration with the underlying service layer (the accountmanager ). the second method calls the first and sets up the response in the model for use by a view. this avoids duplicated logic.

to determine which of the two @requestmapping methods to pick, we are again using our ppa content negotiation strategy. it allows the produces option to work. urls ending with accounts.xml or accounts.json map to the first method, any other urls ending in accounts.anything map to the second.

another approach

alternatively we could do the whole thing with just one method if we used views to generate all possible content-types. this is where the contentnegotiatingviewresolver comes in and that will be the subject of my next post .

acknoweldgements

i would like to thank rossen stoyanchev for his help in writing this post. any errors are my own.

addendum: the annotated account class

added 2 june 2013 .

since there were some questions on how to annotate a class for jaxb, here is part of the account class. for brevity i have omitted the data-members, and all methods except the annotated getters. i could annotate the data-members directly if preferred (just like jpa annotations in fact). remember that jackson can marshal objects to json using these same annotations.

/**
 * represents an account for a member of a financial institution. an account has
 * zero or more {@link transaction}s and belongs to a {@link customer}. an aggregate entity.
 */
@entity
@table(name = "t_account")
@xmlrootelement
public class account {

	// data-members omitted ...

	public account(customer owner, string number, string type) {
		this.owner = owner;
		this.number = number;
		this.type = type;
	}

	/**
	 * returns the number used to uniquely identify this account.
	 */
	@xmlattribute
	public string getnumber() {
		return number;
	}

	/**
	 * get the account type.
	 *
	 * @return one of "credit", "savings", "check".
	 */
	@xmlattribute
	public string gettype() {
		return type;
	}

	/**
	 * get the credit-card, if any, associated with this account.
	 *
	 * @return the credit-card number or null if there isn't one.
	 */
	@xmlattribute
	public string getcreditcardnumber() {
		return stringutils.hastext(creditcardnumber) ? creditcardnumber : null;
	}

	/**
	 * get the balance of this account in local currency.
	 *
	 * @return current account balance.
	 */
	@xmlattribute
	public monetaryamount getbalance() {
		return balance;
	}

	/**
	 * returns a single account transaction. callers should not attempt to hold
	 * on or modify the returned object. this method should only be used
	 * transitively; for example, called to facilitate reporting or testing.
	 *
	 * @param name
	 *            the name of the transaction account e.g "fred smith"
	 * @return the beneficiary object
	 */
	@xmlelement   // make these a nested <transactions> element
	public set<transaction> gettransactions() {
		return transactions;
	}

    // setters and other methods ...

}