Spring MVC

The student will learn to:

At the conclusion of this lecture and related exercises, the student will be able to:

The focus of this lecture, module, and most portions of the course will be on synchronous communications patterns. The synchronous paradigm is simpler, and there are a ton of API concepts to cover before worrying about managing the asynchronous streams of the reactive programming model. In addition to reactive concepts, Spring WebFlux brings in a heavy dose of Java 8 lambdas and functional programming that should only be applied once we master more of the API concepts.

However, we need to know the two approaches exist to make sense of the software and available documentation. For example, the long-time legacy client-side of Spring MVC (i.e., RestTemplate) was put in "maintenance mode" (minor changes and bug fixes only) towards the end of Spring 5, with its duties fulfilled by Spring WebFlux (i.e., WebClient ). Spring 6 introduced a middle ground with RestClient that addresses the synchronous communication simplicity of RestTemplate with the fluent API concepts of WebClient.

It is certain that you will encounter use of RestTemplate in legacy Spring applications and there is no strong reason to replace. There is a good chance you may have the desire to work with a fluent or reactive API. Therefore, I will be demonstrating synchronous client concepts using each library to help cover all bases.

Spring MVC was originally implemented for writing Servlet-based applications. The term "MVC" stands for "Model, View, and Controller" — which is a standard framework pattern that separates concerns between:

The separation of concern provides a means to logically divide web application code along architecture boundaries. Built-in support for HTTP-based APIs has matured over time, and with the shift of UI web applications to JavaScript frameworks running in the browser, the focus has likely shifted towards the API development.

Spring WebFlux is built using a stream-based, reactive design as a part of Spring 5/Spring Boot 2. The reactive programming model was adopted into the java.util.concurrent package in Java 9, to go along with other asynchronous programming constructs — like Future<T>.

Some of the core concepts — like annotated @RestController and method associated annotations — still exist. The most visible changes added include the optional functional controller and the new, mandatory data input and return publisher types:

To go a little further in contrasting the two approaches, the diagram below depicts a contrast between a call to two separate services using the synchronous versus asynchronous processing paradigms.

There are different types of asynchronous processing. Spring has long supported threads with @Async methods. However, that style simply launches one or more additional threads that potentially also contain synchronous logic that will likely block at some point. The reactive model is strictly non-blocking — relying on the backpressure of available data and the resources being available to consume it. With the reactive programming paradigm comes strict rules of the road.

There is a certain amount of mixture of approaches allowed with Spring MVC and Spring WebFlux. A pure reactive design without a trace of Spring MVC can operate on the Reactor Netty engine — optimized for reactive processing. Any use of Web MVC will cause the application to be considered a Web MVC application, choose between Tomcat or Jetty for the web server, and operate any use of reactive endpoints in a compatibility mode. ^[1]

With that said — functionally, we can mix Spring Web MVC and Spring WebFlux together in an application using what is considered to be the Web MVC container.

However, we cannot have the callback of a reactive flow make synchronous requests that can indeterminately block — or it itself will become synchronous and tie up a critical reactor thread.

Independent synchronous and reactive flows can be formed on a case-by-case basis and optimized if implemented on separate instances. ^[1] We can choose our ultimate solution(s) based on some of the recommendations below.

For many of the above reasons, we will start out our HTTP-based API coverage in this course using the synchronous approach.

Class-level mappings can be used to establish a base definition to be applied to all methods and extended by method-level annotation mappings. Knowing this, we can define the base URI path using a @RequestMapping annotation on the controller class and all methods of this class will either inherit or extend that URI path.

In this particular case, our class-level annotation is defining a base URL path of /rpc/greeting.

There are two initial aspects to map to our method in our first simple example: URI and HTTP method.

A few of the prominent response mappings can be determined automatically by the container in simplistic cases:

Once we start our application and enter the following in the browser, we get the expected string "hi" returned.

If you have access to curl or another HTTP test tool, you will likely see the following additional detail.

We start our example by creating an integration unit test. That means we will be using the Spring context and will do so using @SpringBootTest annotation with two key properties:

Next, we will form the full URL for the target endpoint. We can take the parts we know and merge that with the injected server port number to get a full URL.

With a URL in hand, we are ready to make the call. We will do that first using the synchronous RestTemplate from the Spring MVC library.

Spring’s RestTemplate is a thread safe class that can be constructed with a default constructor for the simple case — or through a builder in more complex cases and injected to take advantage of separation of concerns.

There are dozens of potential calls we can make with RestTemplate. We will learn many more, but in this case we are

At this point, we have made our request and have received our reply and can evaluate the reply against what was expected.

RestClient is an interface and must be constructed through a builder. A default builder can be obtained through a static method of the RestClient interface. RestClient is also thread safe, is capable of being configured in a number of ways, and its builder can be injected to create individualized instances.

If you are already invested in a detailed RestTemplate setup of configured defaults and want the fluent API, RestClient can be constructed from an existing RestTemplate instance.

The methods for RestClient are arranged in a builder type pattern where each layer of call returns a type with a constrained set of methods that are appropriate for where we are in the call tree.

The example below shows an example of:

WebClient is an interface and must be constructed through a builder. A default builder can be obtained through a static method of the WebClient interface. WebClient is also thread safe, is capable of being configured in a number of ways, and its builder can be injected to create individualized instances.

One cannot use a RestTemplate or RestClient instance to create a WebClient. They are totally different threading models under the hood.

The fluent API methods for WebClient are much the same as RestClient except for when it comes to obtaining the payload body.

The example below shows an example of:

The block() call is the synchronous part that we would look to avoid in a truly reactive thread. It is a type of subscriber that triggers the defined flow to begin producing data. This block() is blocking the current (synchronous) thread — just like RestTemplate. The portions of the call ahead of block() are performed in a reactive set of threads.

Parameters derived from the URI path require that the path be expressed with {placeholder} names within the string. That placeholder name will be mapped to a specific method input parameter using the @PathVariable annotation. In the following example, we are mapping whatever is in the position held by the {greeting} placeholder — to the greeting input variable.

Specific query parameters are mapped by their name in the URL to a specific method input parameter using the @RequestParam annotation. In the following example, we are mapping whatever is in the value position of name= to the name input variable.

As mentioned above, the path and query parameters are expressed in the URL — which is not impacted whether we use RestTemplate, RestClient, or WebClient.

A way to build a URL through type-safe convenience methods is with the UriComponentsBuilder class. In the following example:

We can address parameters in Spring HTTP Interface using the same @PathVariable and RequestParam declarations that were used on the server-side. The following example shows making each of the parameters required. Notice also that we can have the call return the ResponseEntity wrapper versus just the value.

With the method defined, we can call it like a normal Java method and inspect the response.

The client libraries offer additional calls to obtain the ResponseEntity.

The ResponseEntity<T> can provide us with more detail than just the response object from the body. As you can see from the following evaluation block, the client also has access to the status code and headers.

RestTemplate and RestClient will throw an exception, by default for error responses.

RestClient has two primary paths to invoke a request: retrieve() and exchange().

WebClient has the same two primary paths to invoke a request: retrieve() and exchange(). retrieve() works very similar to RestTemplate.<method>ForEntity() — where it returns what you ask or throws an exception. exchange() permits some analysis of the response — but ultimately places you in a position that you need to throw an exception if you cannot return the type requested. Overriding the exception handling design of these clients is not something I would recommend, and overriding the async API of the WebClient can be daunting. Therefore, I am just going to show the exception handling option.

The example below is catching a specific BadRequest exception and then handling the exception in a generic way.

All default WebClient exceptions extend WebClientResponseException — which is also a RuntimeException, so it has that in common with the exception handling of RestTemplate.

The Spring HTTP Interface API exceptions will be identical to RestTemplate and RestClient. Any special handling of error responses can be done in the client error handling stack (e.g., RestClient.defaultStatusHandler). That will provide a means to translate the HTTP error response into a business exception if desired.

Once the code calling one of the two clients has the client-specific exception object, they have access to three key response values:

The following is an example of handling an exception thrown by RestTemplate and RestClient.

The following is an example of handling an exception thrown by WebClient.

The following service example performs some trivial error checking and:

The service provides control over the entire response by returning a ResponseEntity containing the complete HTTP result versus just returning the result value for the body. The ResponseEntity can express status code, headers, and the returned entity.

In response, we see the explicitly assigned status code and Content-Location header.

For the error condition, we see the explicit status code and error payload assigned.

We can make a small but significant step at simplifying the controller method by making sure the exception thrown is fully descriptive and moving the exception handling to either:

The following example uses @ExceptionHandler annotation to register a handler for when controller methods happen to throw the IllegalArgumentException. The handler can return an explicit ResponseEntity with the error details.

With all exceptions addressed by ExceptionHandlers, we can free our controller methods of tedious, repetitive conditional error reporting logic and still return an explicit HTTP response.

Note the new method endpoint with the exception handler returns the same, explicit HTTP response as the earlier example.