What is Spring MVC: @Controllers & @RestControllers

Spring MVC is Spring’s web framework. It lets you build web sites or RESTful services (think: JSON/XML) and is nicely integrated into the Spring ecosystem, e.g. it powers the @Controllers and @RestControllers of your Spring Boot applications.

That doesn’t really help, does it?

Luckily, there’s also a long answer: The remainder of this document.

(If you are unsure of what Spring or Spring Boot is, you might want to read What Is Spring Framework?, first.)

Let’s have a look at a super simple HttpServlet that returns a very simple, static, HTML page.

Let’s break this down.

Your servlet extends Java’s HttpServlet class.

To handle (any) GET request, you need to override the doGet() method from the superclass. For POST requests you would override doPost(). Similarly, for all other HTTP methods.

Your servlet needs to make sure that the URL that comes in is a request that it knows how to handle. For now, the servlet only handles "/", i.e.: it handles www.marcobehler.com, but NOT www.marcobehler.com/hello.

You need to set the proper Content-Type on the ServletResponse to let the browser know what content you are sending. In this case, it’s HTML.

Remember: web sites are just HTML strings! So you need to generate an HTML string, any way you want, and send that back with the ServletResponse. One way of doing that is with the response’s writer.

After writing your servlet, you would register it with a servlet container, like Tomcat or Jetty. If you are using an embedded version of either servlet container, all the code needed to run your servlet would look like this:

Let’s break this down.

You configure a new Tomcat server which will start on port 8080.

This is how you register your Servlet with Tomcat. This is the first part, where you simply tell Tomcat about your servlet.

The second part is letting Tomcat know for what requests the servlet is responsible, i.e. the mapping. A mapping of /* means it’s responsible for any incoming request (/users, /register, /checkout).

That’s it. You run your main() method now, go to port 8080 in your favorite web browser (http://localhost:8080/), and you’ll see a nice HTML page.

So, essentially, as long as you keep extending your doGet() and doPost() methods, your whole web application could consist of just one servlet. Let’s try that out.

Imagine that apart from your (pretty empty) HTML index page, you now also want to offer a REST API for your soon-to-be-developed front end. So your React or AngularJS front end would call a URL like this:

/api/users/{userId}

That endpoint should return data in JSON format for the user with the given userId. How could we enhance our MyServlet to do this, again, no frameworks allowed?

Let’s break this down.

We add another if to our doGet method, to handle the /api/users/ calls.

We do some extremely fragile URL parsing. The last part of the URL is the userID, e.g. 5 for /api/users/5. We just assume here that the user always passes in a valid int, which you would actually need to validate!

Writing JSON to the browser means setting the correct content-type.

Again, JSON is just text, so we can write that directly to the HTTPServletResponse. you would probably use a JSON library to convert our User Java object to this string, but for the sake of simplicity, I won’t show that here.

While our servlet above works, there are quite a few problems on the horizon:

Quite a lot of different responsibilities, eh? Wouldn’t it be nicer if you didn’t have to care about all that plumbing? No more request URI and parameter parsing, no more JSON conversions, no more servlet responses?

That’s exactly where Spring MVC comes in.

Imagine a "register user workflow", where a user fills out a form and submits it to the server to get a nice little success HTML page back.

In that case, your DispatcherServlet needs to do the following things:

The whole process looks like this, with a fair number of intermediary classes neglected because DispatcherServlet doesn’t do all the work itself.

What’s a ModelAndView in the above graphic? How exactly does the DispatcherServlet convert the data?

It is easiest to understand by looking at a real-life example. For example: How do you write HTML websites with Spring MVC? Let’s find out in the next section.

For our user registration workflow from above (POST /register?name=john&age33), you would write the following class.

Let’s break this down.

A controller class in Spring is simply annotated with the @Controller annotation, it does not need to implement a specific interface or extend from another class.

This line tells our DispatcherServlet that whenever a POST request comes in for the path /register, including any request parameters (e.g. ?username=), it should dispatch the request to this very controller method.

Note The naming of our method (registerUser) does not really matter, it could be called anything.

We do however specify that each request should include two request parameters, which could either be part of the URL (?age=10&name=Joe) or be in the POST request body. Furthermore, only the name parameter is required (the age parameter is optional)

And the age parameter, if the user supplies it, is automatically converted to an Integer (an exception is thrown if the supplied value is not a valid Integer)

Last, but not least, Spring MVC automatically injects a model parameter into our controller method. That model is a simple map where you need to put all the data that you want to show in your final HTML page, but more on that in a second.

You do whatever you need to do with the incoming request data. Create a user, save it to a database, send out an email. This is your business logic.

You add your user to the model, under key "user". Which means, you’ll be able to reference it in your HTML template later on, like "${user.name}". More on that in a second.

Your method returns a simple string, with the value registration-success. This is not just any string, it is a reference to your view, i.e. the HTML template that you want Spring to render.

Let’s ignore for now how (or rather where) Spring MVC will try and find that view, i.e. your template; instead, let’s see what your registration-success.html template should look like.

It’s just a simple HTML page, which contains one template-y line. It prints out the name of the user that has just registered.

The question is, what is this th:text= syntax? Is that Spring-specific? Is it something else?

And the answer is that Spring MVC doesn’t really know anything about HTML templates. It needs a 3rd-party templating library to do all HTML templating work and doesn’t necessarily care what library you choose.

In the above case, you are looking at a Thymeleaf template, which is a very popular choice when working on Spring MVC projects.

There are several different templating libraries that integrate well with Spring MVC that you can choose from: Thymeleaf, Velocity, Freemarker, Mustache and even JSP (even though that is not a templating library).

In fact, you must explicitly choose a templating library, because if you do not have such a templating library added to your project and configured correctly, then your @Controller method would not render your HTML page - because it wouldn’t know how to do it.

It also means that you have to learn and understand the syntax of the particular templating library depending on the project you’re, in because they’re all slightly different from each other. Fun, right?

For a second, let’s think about where Spring will actually try and find your HTML templates that your @Controller returns.

The class that tries to find your template is called a ViewResolver. So whenever a request comes into your Controller, Spring will have a look at the configured ViewResolvers and ask them, in order, to find a template with the given name. If you don’t have any ViewResolvers configured, this won’t work.

Imagine you want to integrate with Thymeleaf. Hence you would need a ThymeleafViewResolver.

Let’s break this down.

In the end, a ThymeleafViewResolver simply implements Spring’s ViewResolver interface. Given a template name (remember: registration-success), ViewResolvers can find the actual template.

The ThymeleafViewResolver needs a couple of other Thymeleaf-specific classes to work properly. One of these classes is the SpringResourceTemplateResolver. It does the actual work of finding your template.

You are basically saying (with help of the Spring Resources syntax): "All my templates are on the classpath, in the /templates folder". And, by default, they all end with .html. This means:

Whenever our @Controller returns a String like registration-success, the ThymeleafViewResolver will look for a template: classpath:/templates/registration-success.html.

You might be thinking: Marco, I’ve never had to configure such a ViewResolver in my entire life working on Spring Boot projects. And that is correct. Because Spring Boot automatically configures one for you, whenever you add a dependency such as spring-boot-starter-thymeleaf to your project.

It also configures the ViewResolver to have a look at your src/main/resources/template directory, by default.

So, Spring Boot really just pre-configures Spring MVC for you. Keep that in mind.

Having seen a complete @Controller & ViewResolver example makes it much easier to talk about Spring’s Model-View-Controller concept.

It is all about separation of concerns.

While a bit annotation-heavy at first sight, our Spring @Controller class reads a lot better, with a lot less HTTP plumbing involved than our uber-servlet from the beginning.

We already saw a bit of the convenience that Spring MVC gives us when handling HTTP inputs.

Let’s have a look at the most common annotations that help you process incoming HTTP requests.

In short, when writing HTML pages with Spring MVC you’ll have to do just a few things:

That’s it.

The first thing you need to do to output XML/JSON is to write a @RestController instead of a @Controller. (Although @RestController IS a @Controller, see FAQ for what the exact difference is).

If we were to write a REST Controller for a bank, that returns a user’s transaction list, it could look something like this:

Let’s break it down.

You annotated the BankController class with the @RestController annotation, which signals Spring that you do not want to write HTML pages through the usual ModelAndView process.

Instead, you want to write XML/JSON (or some other format) directly into the HTTP response body.

Your controller does not return a String (view) anymore. Instead, it returns a List<Transaction>, that you want Spring to convert to an appropriate JSON or XML structure. You basically want your Transaction Java objects to become this (someone was hungry for fast food very early in the morning):

But how would Spring MVC know that your transaction list should get converted to JSON? Why not XML? Or YAML? How does your @RestController method know what the supposed response format should be?

For that, Spring has the concept of Content Negotiation.

In short, content negotiation means that the client needs to tell your server what response format it wants to get back from your @RestController.

How? By specifying the Accept header with the HTTP request.

Spring MVC will have a look at that Accept header and know: The client wants JSON (application/json) back, so I need to convert my List<Transaction> to JSON. (Quick note: there are other ways to do content negotiation, but the Accept header is the default way.)

Let’s call this response content negotiation, because it is about the data format of the HTTP response that you are sending back to your client.

But content negotiation also works for incoming requests. Let’s see how.

When building RESTful APIs, there’s an extremely high chance that you also want your clients to be able to send in JSON, or XML. Let’s pick up the example from the beginning of the chapter again, where you offer a REST endpoint to register new users:

How would Spring know that the request body above contains JSON and not XML or YAML?

You might have guessed right, you’ll need to add another header, this time it’s the Content-Type header.

What would the corresponding @RestController method for that request look like?

Let’s break it down.

Similar to @RequestParam or @Pathvariable, you’ll need another annotation, called @RequestBody.

@RequestBody in combination with the correct Content-Type will signal Spring that it needs to have a look at the HTTP request body and convert it to whatever Content-Type the user specified: JSON in our case.

Your method then doesn’t have to care about the raw JSON string anymore, it can simply work with the TransactionDTO, save it to the database, convert it to a Transaction object, anything you want.

That is the power of Spring MVC.

There’s only one small problem: Spring knows about the Accept and Content-Type headers, but it does not know how to convert between Java Objects and JSON. Or XML. Or YAML.

It needs an appropriate 3rd-party library to do the dirty work (also called marshalling/unmarshalling or serialization/deserialization.)

And the classes that integrate between Spring MVC and these 3rd-party libaries are called HttpMessageConverters.

An HttpMessageConverter is an interface with four methods (note, I simplified the interface a bit for an easier explanation, as it looks a bit more advanced in real life).

In short, a MessageConverter needs to know what MediaTypes it supports (think: application/json) and then needs to implement two methods to do the actual reading/writing in that data format.

Luckily, you don’t need to write these message converters yourself. Spring MVC comes with a class that automatically registers a couple of default HTTPMessageConverters for you - if you have the appropriate 3rd-party libraries on the classpath.

If you don’t know about this, it’ll sound like magic. In any case, have a look at Spring’s AllEncompassingFormHttpMessageConverter (I love the name).

Let’s break this down.

Spring MVC checks if the class javax.xml.bind.Binder is present and if so, assumes you have added a needed library to your project to do JAXB conversions.

Spring MVC checks if two classes ..jackson..ObjectMapper and ..jackson..JsonGenerator are present and if so assumes that you have added Jackson to your project in order to do the JSON conversions.

Spring MVC checks if the class ..jackson..XmlMapper is present and if so assumes that you have added Jackson’s XML support to your project in order to do the XML conversions.

And so on. And a couple of lines later, Spring simply adds an HttpMessageConverter for each library it 'detected'.

When building Spring Boot projects, you’ll automatically use Spring MVC under the hood. But Spring Boot also pulls in Jackson by default.

That is the reason why you can immediately write JSON endpoints with Spring Boot, because the correct HttpMessageConverts will be added automatically for you.

Compared with the HTML flow, the JSON/XML flow is a bit simpler, as you bypass all that Model and View rendering.

Instead, your @Controllers directly return Java objects, which Spring MVC will conveniently serialize to JSON/XML or any other format that the user requested with the help of HttpMessageConverters.

You need to make sure of two things, however:

If you have read this guide, you should understand by now that Spring Web MVC is part of Spring framework.

On a very high-level it allows you to turn your Spring application into a web application with the help of a DispatcherServlet that routes to @Controller classes.

These can be RestControllers (where you send XML or JSON to the client) or good old HTML Controllers where you generate HTML with frameworks like Thymeleaf, Velocity or Freemarker.

The question should really be: What is the difference between Spring Web MVC & Struts?

The short, historical answer is: Spring Web MVC started out as a competitor of Struts, which was, allegedly, perceived as poorly designed by Spring developers (see wikipedia).

The modern answer is, that while Struts 2 is certainly still being used in the odd legacy project, Spring Web MVC is the basis for everything web-related in the Spring universe. From Spring Webflow to Spring Boot’s RestControllers.

You can find the working source code for most of this article in the following GitHub repository: https://github.com/marcobehler/spring-mvc-article

Simply clone the project and run the SpringMvcArticleApplication class to start up the web application.

In short: There is no difference, Spring Boot uses and builds on top of Spring MVC.

For a more thorough explanation, you’ll need to read my What is Spring Framework? article first.

Unless you want to use Spring MVC without it (quite rare, nowadays), the quickest way will be to create a new Spring Boot project.

This will let you build web/RESTful applications with Spring MVC.

Spring MVC understands basically everything that HTTP offers - with the help of third-party libraries.

That means you can throw JSON, XML, or HTTP (Multipart) Fileuploads request bodies at it, and Spring will conveniently convert that input to Java objects.

Spring MVC can write anything that you want into an HttpServletResponse - with the help of 3rd-party libraries.

Be that HTML, JSON, XML or even WebSocket response bodies. Even better, it takes your Java objects and generates those response bodies for you.

Over the years I have personally worked with almost all templating libraries and while there is a certain push to use Thymeleaf in Spring projects, I have no strong preference. So, either go with Thymeleaf (if you don’t have experience with any other framework) or choose the one you are most comfortable with.

A relatively common mistake is to have a @Controller returning objects that you want to get converted to JSON or XML, but you are missing the @ResponseBody annotation.

Spring will return a rather meaningless 404 Not Found exception in that case.

Fix: Add @ResponseBody or turn your @Controller into a @RestController.

If the two methods have different HTTP methods, it won’t be a problem.

If, however, you map the same HTTP methods to the same path, you will get a problem.

On application startup, this will lead to an IllegalStateException, hinting to your ambiguous mapping.

Yes, because Spring automatically URL decodes them. A common error:

Imagine your application sends out confirmation emails whenever a new user signs up and a user signs up with a "+" sign in his email address, like marco+wantsnospam@marcobehler.com.

If you forgot to properly URL encode the + sign in your confirmation mail and send the string as is to your @Controller, which value will the email @RequestParam contain?

It will be "marco[space]wantsnospam@marcobehler.com", as Spring will replace the + with a space, which is proper RFC3986 handling.

Fix: Make sure that the URLs you feed to your application are properly encoded: marco%2Bwantsnospam@marcobehler.com, as Spring will decode them automatically.

In your Spring MVC @Controller or @RestController, you can simply specify the HttpSession as a method argument, and Spring will automatically inject it (creating one if it doesn’t yet exist)

You cannot do that with random @Components or @Services, but you are still able to @Autowire the HttpSession into them.

In your Spring MVC @Controller or @RestController, you can simply specify the HttpServletRequest as a method argument and Spring will automatically inject it (creating one if it doesn’t yet exist)

You cannot do that with random @Components or @Services, but you are still able to @Autowire the HttpServletRequest into them.

There’s a variety of ways to access the request headers, depending on whether you want just a single one or a map with all of them. In either case you need to annotate them with @RequestHeader.

Whatever version you pick, try to be consistent with your choice.

For reading cookies you can use the @CookieValue annotation in your controllers. You’ll have to write cookies directly to the HttpServletResponse.

This is a trick question. There is a method, called httpServletRequest.getRemoteAddr(), which, however, only returns you the IP of the user or the last proxy that sent the request, which 99,99% of the case is your Nginx or Apache.

Hence, you’ll need to parse the X-Forwarded-For header for the correct IP address. But what happens if your application, in addition, runs behind a CDN, like CloudFront? Then your X-Forwarded-For would look like this:

X-Forwarded-For: maybeSomeSpoofedIp, realIp, cloudFrontIp

The problem is, you cannot read the header from left to right, as users could provide and therefore spoof their own X-Forwarded-For header. You always have to go from right to left, and exclude all known IP addresses. In the case of CloudFront, this means you’ll need to know the CloudFront IP ranges and remove them from the header. Yup!

This leads to quite elaborate IP-resolving code. Guess how many projects get that wrong!

Given that you have the proper HTML file upload form, which reads something like this:

You simply need a @Controller with a corresponding @PostMapping and a MultiPartFile parameter, which contains your upload data and convenient methods to store the file on your disk.

There’s a variety of ways to get this working, from writing directly to the HttpServletResponse or returning a byte[] as a result.

However, the most Spring-y and flexible version is by returning `ResponseEntity<Resource>`s. Depending on where you stored the file, you would use a different resource.

All that’s left to do then, is set the appropriate response HTTP headers (filename, content-type, etc).

There’s literally a gazillion ways of handling exceptions with Spring MVC, if you don’t want to handle them directly in your @Controller methods, but rather in one central place.

Create a @ControllerAdvice or @RestControllerAdvice class, in combination with the @ResponseStatus and @ExceptionHandler annotations. A couple of notes:

Throw a ResponseStatusException, with the appropriate status code and possibly a reason.

An alternative would be returning a ResponseEntity object, but the exception is nicer in most cases.

The official Spring MVC’s documentation literally contains hundreds of pages describing how the web framework works.

So, in case you want to know more about Models, Views, ViewHandlers, InitBinders, RootContexts, Filters, Caching, etc., I invite you to check it out. It is simply not in the scope of this guide to cover everything.