Spring Boot 2.0 went GA recently, so I decided to write my first post about Spring for quite a while. Since the release I have been seeing more and more mentions of Spring WebFlux along with tutorials on how to use it. But after reading through them and trying to get it working myself, I found it a bit hard to make the jump from the code included in the posts and tutorials I read to writing code that actually does something a tiny bit more interesting than returning a string from the back-end. Now, I\u2019m hoping I\u2019m not shooting myself in the foot by saying that as you could probably make the same criticism of the code I use in this post, but here is my attempt to give a tutorial of Spring WebFlux that actually resembles something that you might use in the wild.<\/p>\n
Before I continue, and after all this mentioning of WebFlux, what actually is it? Spring WebFlux is a fully non-blocking reactive alternative to Spring MVC. It allows better vertical scaling without increasing your hardware resources. Being reactive it now makes use of Reactive Streams to allow asynchronous processing of data returned from calls to the server. This means we are going to see a lot less I used Spring Boot to write the code in this tutorial as usual.<\/p>\n Below are the dependencies that I used in this post.<\/p>\n Although I didn\u2019t include it in the dependency snippet above, the WebFlux introduces a different way to handle requests instead of using the To me this looks very familiar and from a quick glance it doesn\u2019t really look any different from your standard Spring MVC controller, but after reading through the methods we can see the different return types from what we would normally expect. In this example The annotation method is not what I want to focus on in this post though. It\u2019s not cool and hip enough for us. There isn\u2019t enough use of lambdas to satisfy our thirst for writing Java in a more functional way. But Spring WebFlux has our backs. It provides an alternative method to route and handle requests to our servers that lightly uses lambdas to write router functions. Let\u2019s take a look at an example.<\/p>\n These are all the routes to methods in the The method shows that it takes in a The The next parameter is a Finally the output is a If we take another look back at the Before we continue I want to go over the Now that we know how to setup the routes, lets look at writing the handler methods that deal with the incoming requests. Below is the code that handles all the requests from the routes that were defined in the earlier example.<\/p>\n One thing that is quite noticeable, is the lack of annotations. Bar the I have tried to keep most of the repository logic out of this class and have hidden any references to the entity objects by going via the Ok, back to the code at hand. Let\u2019s take a closer look at the This method is for retrieving a single record from the database that backs this example application. Due to Cassandra being the database of choice I have decided to use an Remember that a path variable was included in the path for this Once we have the ID, we can query the database for the existence of a matching record. A Using the returned If the record does not exist, then the flow will move into the Now onto the Even just from the first line we can see that it is already different to how the We will return a So, that\u2019s about it when it comes to the handlers. Obviously there other methods that we didn\u2019t go through. They all work differently but all follow the same concept of returning a We have now written all the code we need to get a basic Spring WebFlux back-end up a running. All that is left is to tie all the configuration together, which is easy with Spring Boot.<\/p>\n Rather than ending the post here we should probably look into how to actually make use of the code.<\/p>\n Spring provides the Below is some code that calls the handlers that were defined in the Don\u2019t forget to instantiate the First we create the Once created we can start doing stuff with it, hence the Let\u2019s break down the I wrote this one down slightly differently so you can see that a Using the Note that the Media Type of Using the Let\u2019s look at one of the other requests.<\/p>\n This is our typical For a slightly different perspective, we could use cURL to make requests and see what the response looks like.<\/p>\n The response will look something like this, obviously it will differ depending on the data you have stored.<\/p>\n Note the response headers.<\/p>\n The I think that this should be a good place to stop. We have covered quite a lot of material here which has hopefully helped you understand Spring WebFlux better. There are a few other topics I want to cover about WebFlux but I will do those in separate posts as I think this one is long enough as it is.<\/p>\n In conclusion, in this post we very briefly discussed why you would want to use Spring WebFlux over a typical Spring MVC back-end. We then looked at how to setup routes and handlers to process the incoming requests. The handlers implemented methods that could deal with most of the REST verbs and returned the correct data and status codes in their responses. Finally we looked at two ways to make requests to the back-end, one using a If you are interested in looking at the rest of the code I used to create the example application for this post, it can be found on my GitHub<\/a>.<\/p>\n As always if you found this post helpful, please share it and if you want to keep up with my latest posts then you can follow me on Twitter at @LankyDanDev<\/a>.<\/p>\nList<\/code>s, Collection<\/code>s or even single objects and instead their reactive equivalents such as Flux<\/code> and Mono<\/code> (from Reactor). I\u2019m not going to go to in depth on what Reactive Streams are, as honestly I need to look into it even more myself before I try to explain it to anyone. Instead lets get back to focusing on WebFlux.<\/p>\n<dependencies>\r\n\r\n <dependency>\r\n <groupId>org.springframework.boot<\/groupId>\r\n <artifactId>spring-boot-starter-webflux<\/artifactId>\r\n <\/dependency>\r\n\r\n <dependency>\r\n <groupId>org.springframework.boot<\/groupId>\r\n <artifactId>spring-boot-starter-data-cassandra-reactive<\/artifactId>\r\n <version>2.0.0.RELEASE<\/version>\r\n <\/dependency>\r\n\r\n<\/dependencies><\/pre>\n
spring-boot-starter-parent<\/code> is used, which can finally be upped to version 2.0.0.RELEASE<\/code>. Being this tutorial is about WebFlux, including the spring-boot-starter-webflux<\/code> is obviously a good idea. spring-boot-starter-data-cassandra-reactive<\/code> has also been included as we will be using this as the database for the example application as it is one of the few databases that have reactive support (at the time of writing). By using these dependencies together our application can be fully reactive from front to back.<\/p>\n@Controller<\/code> or @RestController<\/code> programming model that is used in Spring MVC. But, it does not replace it. Instead it has been updated to allow reactive types to be used. This allows you to keep the same format that you are used to writing with Spring but with a few changes to the return types so Flux<\/code>s or Mono<\/code>s are returned instead. Below is a very contrived example.<\/p>\n@RestController\r\npublic class PersonController {\r\n\r\n private final PersonRepository personRepository;\r\n\r\n public PersonController(PersonRepository personRepository) {\r\n this.personRepository = personRepository;\r\n }\r\n\r\n @GetMapping(\"\/people\")\r\n public Flux<Person> all() {\r\n return personRepository.findAll();\r\n }\r\n\r\n @GetMapping(\"\/people\/{id}\")\r\n\tMono<Person> findById(@PathVariable String id) {\r\n\t\treturn personRepository.findOne(id);\r\n\t}\r\n}<\/pre>\nPersonRepository<\/code> must be a reactive repository as we have been able to directly return the results of their search queries, for reference, reactive repositories will return a Flux<\/code> for collections and a Mono<\/code> for singular entities.<\/p>\n@Configuration\r\npublic class PersonRouter {\r\n\r\n @Bean\r\n public RouterFunction<ServerResponse> route(PersonHandler personHandler) {\r\n return RouterFunctions.route(GET(\"\/people\/{id}\").and(accept(APPLICATION_JSON)), personHandler::get)\r\n .andRoute(GET(\"\/people\").and(accept(APPLICATION_JSON)), personHandler::all)\r\n .andRoute(POST(\"\/people\").and(accept(APPLICATION_JSON)).and(contentType(APPLICATION_JSON)), personHandler::post)\r\n .andRoute(PUT(\"\/people\/{id}\").and(accept(APPLICATION_JSON)).and(contentType(APPLICATION_JSON)), personHandler::put)\r\n .andRoute(DELETE(\"\/people\/{id}\"), personHandler::delete)\r\n .andRoute(GET(\"\/people\/country\/{country}\").and(accept(APPLICATION_JSON)), personHandler::getByCountry);\r\n }\r\n}<\/pre>\nPersonHandler<\/code> which we will look at later on. We have created a bean that will handle our routing. To setup the routing functions we use the well named RouterFunctions<\/code> class providing us with a load of static methods, but for now we are only interested with it\u2019s route<\/code> method. Below is the signature of the route<\/code> method.<\/p>\npublic static <T extends ServerResponse> RouterFunction<T> route(\r\n RequestPredicate predicate, HandlerFunction<T> handlerFunction) {\r\n \/\/ stuff\r\n}<\/pre>\nRequestPredicate<\/code> along with a HandlerFunction<\/code> and outputs a RouterFunction<\/code>.<\/p>\nRequestPredicate<\/code> is what we use to specify behavior of the route, such as the path to our handler function, what type of request it is and the type of input it can accept. Due to my use of static imports to make everything read a bit clearer, some important information has been hidden from you. To create a RequestPredicate<\/code> we should use the RequestPredicates<\/code> (plural), a static helper class providing us with all the methods we need. Personally I do recommend statically importing RequestPredicates<\/code> otherwise you code will be a mess due to the amount of times you might need to make use of RequestPredicates<\/code> static methods. In the above example, GET<\/code>, POST<\/code>, PUT<\/code>, DELETE<\/code>, accept<\/code> and contentType<\/code> are all static RequestPredicates<\/code> methods.<\/p>\nHandlerFunction<\/code>, which is a Functional Interface. There are three pieces of important information here, it has a generic type of <T extends ServerResponse><\/code>, it\u2019s handle<\/code> method returns a Mono<T><\/code> and it takes in a ServerRequest<\/code>. Using these we can determine that we need to pass in a function that returns a Mono<ServerResponse><\/code> (or one of it\u2019s subtypes). This obviously places a heavy constraint onto what is returned from our handler functions as they must meet this requirement or they will not be suitable for use in this format.<\/p>\nRouterFunction<\/code>. This can then be returned and will be used to route to whatever function we specified. But normally we would want to route lots of different requests to various handlers at once, which WebFlux caters for. Due to route<\/code> returning a RouterFunction<\/code> and the fact that RouterFunction<\/code> also has its own routing method available, andRoute<\/code>, we can chain the calls together and keep adding all the extra routes that we require.<\/p>\nPersonRouter<\/code> example above, we can see that the methods are named after the REST verbs such as GET<\/code> and POST<\/code> that define the path and type of requests that a handler will take. If we take the first GET<\/code> request for example, it is routing to \/people<\/code> with a path variable name id<\/code> (path variable denoted by {id}<\/code>) and the type of the returned content, specifically APPLICATION_JSON<\/code> (static field from MediaType<\/code>) is defined using the accept<\/code> method. If a different path is used, it will not be handled. If the path is correct but the Accept header is not one of the accepted types, then the request will fail.accept<\/code> and contentType<\/code> methods. Both of these set request headers, accept<\/code> matches to the Accept header and contentType<\/code> to Content-Type. The Accept header defines what Media Types are acceptable for the response, as we were returning JSON representations of the Person<\/code> object setting it to APPLICATION_JSON<\/code> (application\/json<\/code> in the actual header) makes sense. The Content-Type has the same idea but instead describes what Media Type is inside the body of the sent request. That is why only the POST<\/code> and PUT<\/code> verbs have contentType<\/code> included as the others do not have anything contained in their bodies. DELETE<\/code> does not include accept<\/code> and contentType<\/code> so we can conclude that it is neither expecting anything to be returned nor including anything in its request body.<\/p>\n@Component\r\npublic class PersonHandler {\r\n\r\n private final PersonManager personManager;\r\n\r\n public PersonHandler(PersonManager personManager) {\r\n this.personManager = personManager;\r\n }\r\n\r\n public Mono<ServerResponse> get(ServerRequest request) {\r\n final UUID id = UUID.fromString(request.pathVariable(\"id\"));\r\n final Mono<Person> person = personManager.findById(id);\r\n return person\r\n .flatMap(p -> ok().contentType(APPLICATION_JSON).body(fromPublisher(person, Person.class)))\r\n .switchIfEmpty(notFound().build());\r\n }\r\n\r\n public Mono<ServerResponse> all(ServerRequest request) {\r\n return ok().contentType(APPLICATION_JSON)\r\n .body(fromPublisher(personManager.findAll(), Person.class));\r\n }\r\n\r\n public Mono<ServerResponse> put(ServerRequest request) {\r\n final UUID id = UUID.fromString(request.pathVariable(\"id\"));\r\n final Mono<Person> person = request.bodyToMono(Person.class);\r\n return personManager\r\n .findById(id)\r\n .flatMap(\r\n old ->\r\n ok().contentType(APPLICATION_JSON)\r\n .body(\r\n fromPublisher(\r\n person\r\n .map(p -> new Person(p, id))\r\n .flatMap(p -> personManager.update(old, p)),\r\n Person.class)))\r\n .switchIfEmpty(notFound().build());\r\n }\r\n\r\n public Mono<ServerResponse> post(ServerRequest request) {\r\n final Mono<Person> person = request.bodyToMono(Person.class);\r\n final UUID id = UUID.randomUUID();\r\n return created(UriComponentsBuilder.fromPath(\"people\/\" + id).build().toUri())\r\n .contentType(APPLICATION_JSON)\r\n .body(\r\n fromPublisher(\r\n person.map(p -> new Person(p, id)).flatMap(personManager::save), Person.class));\r\n }\r\n\r\n public Mono<ServerResponse> delete(ServerRequest request) {\r\n final UUID id = UUID.fromString(request.pathVariable(\"id\"));\r\n return personManager\r\n .findById(id)\r\n .flatMap(p -> noContent().build(personManager.delete(p)))\r\n .switchIfEmpty(notFound().build());\r\n }\r\n\r\n public Mono<ServerResponse> getByCountry(ServerRequest serverRequest) {\r\n final String country = serverRequest.pathVariable(\"country\");\r\n return ok().contentType(APPLICATION_JSON)\r\n .body(fromPublisher(personManager.findAllByCountry(country), Person.class));\r\n }\r\n}<\/pre>\n@Component<\/code> annotation to auto create a PersonHandler<\/code> bean there are no other Spring annotations.<\/p>\nPersonManager<\/code> that delegates to the PersonRepository<\/code> it contains. If you are interested in the code within PersonManager<\/code> then it can be seen here on my GitHub<\/a>, further explanations about it will be excluded for this post so we can focus on WebFlux itself.<\/p>\nget<\/code> and post<\/code> methods to figure out what is going on.<\/p>\npublic Mono<ServerResponse> get(ServerRequest request) {\r\n final UUID id = UUID.fromString(request.pathVariable(\"id\"));\r\n final Mono<Person> person = personManager.findById(id);\r\n return person\r\n .flatMap(p -> ok().contentType(APPLICATION_JSON).body(fromPublisher(person, Person.class)))\r\n .switchIfEmpty(notFound().build());\r\n}<\/pre>\nUUID<\/code> for the primary key of each record, this has the unfortunate effect of making testing the example more annoying but nothing that some copy and pasting can\u2019t solve.<\/p>\nGET<\/code> request. Using the pathVariable<\/code> method on the ServerRequest<\/code> passed into the method we are able to extract it\u2019s value by providing the name of the variable, in this case id<\/code>. The ID is then converted into a UUID<\/code>, which will throw an exception if the string is not in the correct format, I decided to ignore this problem so the example code doesn\u2019t get messier.<\/p>\nMono<Person><\/code> is returned which either contains the existing record mapped to a Person<\/code> or it left as an empty Mono<\/code>.<\/p>\nMono<\/code> we can output different responses depending on it\u2019s existence. This means we can return useful status codes to the client to go along with the contents of the body. If the record exists then flatMap<\/code> returns a ServerResponse<\/code> with the OK<\/code> status. Along with this status we want to output the record, to do this we specify the content type of the body, in this case APPLICATION_JSON<\/code>, and add the record into it. fromPublisher<\/code> takes our Mono<Person><\/code> (which is a Publisher<\/code>) along with the Person<\/code> class so it knows what it is mapping into the body. fromPublisher<\/code> is a static method from the BodyInserters<\/code> class.<\/p>\nswitchIfEmpty<\/code> block and return a NOT FOUND<\/code> status. As nothing is found, the body can be left empty so we just create the ServerResponse<\/code> there are then.<\/p>\npost<\/code> handler.<\/p>\npublic Mono<ServerResponse> post(ServerRequest request) {\r\n final Mono<Person> person = request.bodyToMono(Person.class);\r\n final UUID id = UUID.randomUUID();\r\n return created(UriComponentsBuilder.fromPath(\"people\/\" + id).build().toUri())\r\n .contentType(APPLICATION_JSON)\r\n .body(\r\n fromPublisher(\r\n person.map(p -> new Person(p, id)).flatMap(personManager::save), Person.class));\r\n}<\/pre>\nget<\/code> method was working. As this is a POST<\/code> request it needs to accept the object that we want to persist from the body of the request. As we are trying to insert a single record we will use the request\u2019s bodyToMono<\/code> method to retrieve the Person<\/code> from the body. If you were dealing with multiple records you would probably want to use bodyToFlux<\/code> instead.<\/p>\nCREATED<\/code> status using the created<\/code> method that takes in a URI<\/code> to determine the path to the inserted record. It then follows a similar setup as the get<\/code> method by using the fromPublisher<\/code> method to add the new record to the body of the response. The code that forms the Publisher<\/code> is slightly different but the output is still a Mono<Person><\/code> which is what matters. Just for further explanation about how the inserting is done, the Person<\/code> passed in from the request is mapped to a new Person<\/code> using the UUID<\/code> we generated and is then passed to save<\/code> by calling flatMap<\/code>. By creating a new Person<\/code> we only insert values into Cassandra that we allow, in this case we do not want the UUID<\/code> passed in from the request body.<\/p>\nServerResponse<\/code> that contains a suitable status code and record(s) in the body if required.<\/p>\n@SpringBootApplication\r\npublic class Application {\r\n public static void main(String args[]) {\r\n SpringApplication.run(Application.class);\r\n }\r\n}<\/pre>\nWebClient<\/code> class to handle requests without blocking. We can make use of this now as a way to test the application, although there is also a WebTestClient<\/code> which we could use here instead. The WebClient<\/code> is what you would use instead of the blocking RestTemplate<\/code> when creating a reactive application.<\/p>\nPersonHandler<\/code>.<\/p>\npublic class Client {\r\n\r\n private WebClient client = WebClient.create(\"http:\/\/localhost:8080\");\r\n\r\n public void doStuff() {\r\n\r\n \/\/ POST\r\n final Person record = new Person(UUID.randomUUID(), \"John\", \"Doe\", \"UK\", 50);\r\n final Mono<ClientResponse> postResponse =\r\n client\r\n .post()\r\n .uri(\"\/people\")\r\n .body(Mono.just(record), Person.class)\r\n .accept(APPLICATION_JSON)\r\n .exchange();\r\n postResponse\r\n .map(ClientResponse::statusCode)\r\n .subscribe(status -> System.out.println(\"POST: \" + status.getReasonPhrase()));\r\n\r\n \/\/ GET\r\n client\r\n .get()\r\n .uri(\"\/people\/{id}\", \"a4f66fe5-7c1b-4bcf-89b4-93d8fcbc52a4\")\r\n .accept(APPLICATION_JSON)\r\n .exchange()\r\n .flatMap(response -> response.bodyToMono(Person.class))\r\n .subscribe(person -> System.out.println(\"GET: \" + person));\r\n\r\n \/\/ ALL\r\n client\r\n .get()\r\n .uri(\"\/people\")\r\n .accept(APPLICATION_JSON)\r\n .exchange()\r\n .flatMapMany(response -> response.bodyToFlux(Person.class))\r\n .subscribe(person -> System.out.println(\"ALL: \" + person));\r\n\r\n \/\/ PUT\r\n final Person updated = new Person(UUID.randomUUID(), \"Peter\", \"Parker\", \"US\", 18);\r\n client\r\n .put()\r\n .uri(\"\/people\/{id}\", \"ec2212fc-669e-42ff-9c51-69782679c9fc\")\r\n .body(Mono.just(updated), Person.class)\r\n .accept(APPLICATION_JSON)\r\n .exchange()\r\n .map(ClientResponse::statusCode)\r\n .subscribe(response -> System.out.println(\"PUT: \" + response.getReasonPhrase()));\r\n\r\n \/\/ DELETE\r\n client\r\n .delete()\r\n .uri(\"\/people\/{id}\", \"ec2212fc-669e-42ff-9c51-69782679c9fc\")\r\n .exchange()\r\n .map(ClientResponse::statusCode)\r\n .subscribe(status -> System.out.println(\"DELETE: \" + status));\r\n }\r\n}<\/pre>\nClient<\/code> somewhere, below is a nice lazy way to do it!<\/p>\n@SpringBootApplication\r\npublic class Application {\r\n public static void main(String args[]) {\r\n SpringApplication.run(Application.class);\r\n Client client = new Client();\r\n client.doStuff();\r\n }\r\n}<\/pre>\nWebClient<\/code>.<\/p>\nprivate final WebClient client = WebClient.create(\"http:\/\/localhost:8080\");<\/pre>\n
doStuff<\/code> method.<\/p>\nPOST<\/code> request that is being send to the back-end.<\/p>\nfinal Mono<ClientResponse> postResponse =\r\n client\r\n .post()\r\n .uri(\"\/people\")\r\n .body(Mono.just(record), Person.class)\r\n .accept(APPLICATION_JSON)\r\n .exchange();\r\npostResponse\r\n .map(ClientResponse::statusCode)\r\n .subscribe(status -> System.out.println(\"POST: \" + status.getReasonPhrase()));<\/pre>\n
Mono<ClientResponse><\/code> is returned from sending a request. The exchange<\/code> method fires the HTTP request over to the server. The response will then be dealt with whenever the response arrives, if it ever does.<\/p>\nWebClient<\/code> we specify that we want to send a POST<\/code> request using the post<\/code> method of course. The URI<\/code> is then added with the uri<\/code> method (overloaded method, this one takes in a String<\/code> but another accepts a URI<\/code>). Im tired of saying this method does what the method is called so, the contents of the body are then added along with the Accept header. Finally we send the request by calling exchange<\/code>.<\/p>\nAPPLICATION_JSON<\/code> matches up with the type defined in the POST<\/code> router function. If we were to send a different type, say TEXT_PLAIN<\/code> we would get a 404<\/code> error as no handler exists that matches to what the request is expecting to be returned.<\/p>\nMono<ClientResponse><\/code> returned by calling exchange<\/code> we can map it\u2019s contents to our desired output. In the case of the example above, the status code is printed to the console. If we think back to the post<\/code> method in PersonHandler<\/code>, remember that it can only return the \u201cCreated\u201d status, but if the sent request does not match up correctly then \u201cNot Found\u201d will be printed out.<\/p>\nclient\r\n .get()\r\n .uri(\"\/people\/{id}\", \"a4f66fe5-7c1b-4bcf-89b4-93d8fcbc52a4\")\r\n .accept(APPLICATION_JSON)\r\n .exchange()\r\n .flatMap(response -> response.bodyToMono(Person.class))\r\n .subscribe(person -> System.out.println(\"GET: \" + person));<\/pre>\nGET<\/code> request. It looks pretty similar to the POST<\/code> request we just went through. The main differences are that uri<\/code> takes in both the path of the request and the UUID<\/code> (as a String<\/code> in this case) as a parameter to that will replace the path variable {id}<\/code> and that the body is left empty. How the response is handled is also different. In this example it extracts the body of the response and maps it to a Mono<Person><\/code> and prints it out. This could have been done with the previous POST<\/code> example but the status code of the response was more useful for it\u2019s scenario.<\/p>\nCURL -H \"Accept:application\/json\" -i localhost:8080\/people<\/pre>\n
HTTP\/1.1 200 OK\r\ntransfer-encoding: chunked\r\nContent-Type: application\/json\r\n\r\n[\r\n {\r\n \"id\": \"13c403a2-6770-4174-8b76-7ba7b75ef73d\",\r\n \"firstName\": \"John\",\r\n \"lastName\": \"Doe\",\r\n \"country\": \"UK\",\r\n \"age\": 50\r\n },\r\n {\r\n \"id\": \"fbd53e55-7313-4759-ad74-6fc1c5df0986\",\r\n \"firstName\": \"Peter\",\r\n \"lastName\": \"Parker\",\r\n \"country\": \"US\",\r\n \"age\": 50\r\n }\r\n]<\/pre>\ntransfer-encoding: chunked\r\nContent-Type: application\/json<\/pre>\n
transfer-encoding<\/code> here represents data that is transferred in chunks that can be used to stream data. This is what we need so the client can act reactively to the data that is returned to it.<\/p>\nWebClient<\/code> to process the output directly on the client side and another via cURL to see what the returned JSON looks like.<\/p>\n