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 early portions of the course will be on synchronous communications patterns. The synchronous paradigm is simpler and there are a lot 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 in order to make sense of the software and available documentation. For example, the client-side of Spring MVC (i.e., RestTemplate) has been put in "maintenance mode" (minor changes and bug fixes only) and its duties fulfilled by Spring WebFlux (i.e., WebClient). Therefore, I will be demonstrating synchronous client concepts using both libraries to help bridge the transition.

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 have 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, chose 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 reason, 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 using the synchronous RestTemplate from the Spring MVC library.

Spring Template 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

Note that a successful return from getForObject() will only occur if the response from the server is a 2xx/successful response. Otherwise an exception of one of the following types will be thrown:

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

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.

The methods for WebClient 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

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 or WebClient.

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

The two 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 is designed to always throw an exception when there is a non-successful status code. Although we can tweak the specific exceptions thrown with filters, we are eventually forced to throw something if we cannot return an object of the requested type or a ResponseEntity<T> carrying the requested type.

All default RestTemplate exceptions thrown extend HttpClientErrorException — which is a RuntimeException, so handling the exception is not mandated by the Java language. The example below is catching a specific BadRequest exception (if thrown) and then handling the exception in a generic way.

WebClient has 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 or a ResponseEntity<T> carrying the type requested.

All default WebClient exceptions thrown extend WebClientResponseException — which is also a RuntimeException, so it has that in common with the exception handling of RestTemplate. The example below is catching a specific BadRequest exception and then handling the exception in a generic way.

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.

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 the 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 substantial step at simplifying the controller method by making sure the exception thrown is fully descriptive and moving the exception handling to either a separate, annotated method of the controller or globally to be used by all controllers (shown later).

The following example uses @ExceptionHandler annotation to register a handler for when controller methods happen to throw the IllegalArgumentException. The handler has the ability to 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.