#859 - Fix RepresentationModelProcessor to smoothly register with Spring MVC.

Some more polishing on internal of Processor and Invoker machinery regarding resource -> model, etc.

Author: gregturn

src/docs/java/org/springframework/hateoas/PaymentProcessingApp.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * @author Greg Turnquist
+ */
+// tag::code[]
+@Configuration
+public class PaymentProcessingApp {
+
+	@Bean
+	PaymentProcessor paymentProcessor() {
+		return new PaymentProcessor();
+	}
+}
+// end::code[]

src/docs/java/org/springframework/hateoas/PaymentProcessor.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas;
+
+import org.springframework.hateoas.server.RepresentationModelProcessor;
+import org.springframework.hateoas.support.Order;
+
+/**
+ * @author Greg Turnquist
+ */
+// tag::code[]
+public class PaymentProcessor implements RepresentationModelProcessor<EntityModel<Order>> { // <1>
+
+	@Override
+	public EntityModel<Order> process(EntityModel<Order> model) {
+
+		model.add( // <2>
+				new Link("/payments/{orderId}").withRel(LinkRelation.of("payments")) //
+						.expand(model.getContent().getOrderId()));
+
+		return model; // <3>
+	}
+}
+// end::code[]

src/docs/java/org/springframework/hateoas/support/Customer.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.support;
+
+import lombok.RequiredArgsConstructor;
+import lombok.Value;
+
+/**
+ * @author Greg Turnquist
+ */
+@Value
+@RequiredArgsConstructor
+public class Customer {
+	private final long customerId;
+}

src/docs/java/org/springframework/hateoas/support/Order.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.support;
+
+import lombok.RequiredArgsConstructor;
+import lombok.Value;
+
+/**
+ * @author Greg Turnquist
+ */
+@Value
+@RequiredArgsConstructor
+public class Order {
+	private final long orderId;
+	private final String state;
+}
+

src/docs/java/org/springframework/hateoas/support/Payment.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.support;
+
+import lombok.RequiredArgsConstructor;
+import lombok.Value;
+
+/**
+ * @author Greg Turnquist
+ */
+@Value
+@RequiredArgsConstructor
+public class Payment {
+	private final Order order;
+	private final double amount;
+}

src/docs/java/org/springframework/hateoas/support/PaymentController.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.support;
+
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * @author Greg Turnquist
+ */
+@RestController
+public class PaymentController {
+
+}

src/docs/resources/org/springframework/hateoas/docs/order-plain.json

@@ -0,0 +1,9 @@
+{
+  "orderId" : "42",
+  "state" : "AWAITING_PAYMENT",
+  "_links" : {
+    "self" : {
+      "href" : "http://localhost/orders/999"
+    }
+  }
+}

src/docs/resources/org/springframework/hateoas/docs/order-with-payment-link.json

@@ -0,0 +1,12 @@
+{
+  "orderId" : "42",
+  "state" : "AWAITING_PAYMENT",
+  "_links" : {
+    "self" : {
+      "href" : "http://localhost/orders/999"
+    },
+    "payments" : { // <1>
+      "href" : "/payments/42" // <2>
+    }
+  }
+}

src/main/asciidoc/server.adoc

@@ -1,5 +1,7 @@
 [[server]]
 = Server-side support
+:code-dir: ../../../src/docs/java/org/springframework/hateoas
+:resource-dir: ../../../src/docs/resources/org/springframework/hateoas
 
 [[server.link-builder]]
 == [[fundamentals.obtaining-links]] [[fundamentals.obtaining-links.builder]] Building links
@@ -223,6 +225,66 @@ CollectionModel<PersonModel> model = assembler.toCollectionModel(people);
 ----
 ====
 
+[[server.processors]]
+== Representation Model Processors
+
+Sometimes you need to tweak and adjust hypermedia representations after they have been <<server.representation-model-assembler,assembled>>.
+
+A perfect example is when you have a controller that deals with order fulfillment, but you need to add links related to making payments.
+
+Imagine having your ordering system producing this type of hypermedia:
+
+====
+[source, json, tabsize=2]
+----
+include::{resource-dir}/docs/order-plain.json[]
+----
+====
+
+You wish to add a link so the client can make payment, but don't want to mix details about your `PaymentController` into
+the `OrderController`.
+
+Instead of polluting the details of your ordering system, you can write a `RepresentationModelProcessor` like this:
+
+====
+[source, java, tabsize=2]
+----
+include::{code-dir}/PaymentProcessor.java[tag=code]
+----
+<1> This processor will only be applied to `EntityModel<Order>` objects.
+<2> Manipulate the existing `EntityModel` object by adding an unconditional link.
+<3> Return the `EntityModel` so it can be serialized into the requested media type.
+====
+
+Register the processor with your application:
+
+====
+[source, java, tabsize=2]
+----
+include::{code-dir}/PaymentProcessingApp.java[tag=code]
+----
+====
+
+Now when you issue a hypermedia respresentation of an `Order`, the client receives this:
+
+====
+[source, java, tabsize=2]
+----
+include::{resource-dir}/docs/order-with-payment-link.json[]
+----
+<1> You see the `LinkRelation.of("payments")` plugged in as this link's relation.
+<2> The URI was provided by the processor.
+====
+
+This example is quite simple, but you can easily:
+
+* Use `WebMvcLinkBuilder` or `WebFluxLinkBuilder` to construct a dynamic link to your `PaymentController`.
+* Inject any services needed to conditionally add other links (e.g. `cancel`, `amend`) that are driven by state.
+* Leverage cross cutting services like Spring Security to add, remove, or revise links based upon the current user's context.
+
+Also, in this example, the `PaymentProcessor` alters the provided `EntityModel<Order>`. You also have the power to
+_replace_ it with another object. Just be advised the API requires the return type to equal the input type.
+
 [[server.rel-provider]]
 == [[spis.rel-provider]] Using the `RelProvider` API
 

src/main/java/org/springframework/hateoas/config/WebFluxHateoasConfiguration.java

@@ -17,7 +17,9 @@
 
 import lombok.RequiredArgsConstructor;
 
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.List;
 
 import org.springframework.beans.BeansException;
 import org.springframework.beans.factory.ObjectProvider;
@@ -27,14 +29,20 @@
 import org.springframework.context.annotation.Lazy;
 import org.springframework.core.codec.CharSequenceEncoder;
 import org.springframework.core.codec.StringDecoder;
+import org.springframework.hateoas.server.RepresentationModelProcessor;
+import org.springframework.hateoas.server.mvc.RepresentationModelProcessorHandlerMethodReturnValueHandler;
+import org.springframework.hateoas.server.mvc.RepresentationModelProcessorInvoker;
 import org.springframework.hateoas.server.reactive.HypermediaWebFilter;
 import org.springframework.http.codec.CodecConfigurer;
 import org.springframework.http.codec.ServerCodecConfigurer;
 import org.springframework.http.codec.json.Jackson2JsonDecoder;
 import org.springframework.http.codec.json.Jackson2JsonEncoder;
 import org.springframework.util.MimeType;
+import org.springframework.web.method.support.HandlerMethodReturnValueHandler;
+import org.springframework.web.method.support.HandlerMethodReturnValueHandlerComposite;
 import org.springframework.web.reactive.config.WebFluxConfigurer;
 import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.reactive.result.method.annotation.RequestMappingHandlerAdapter;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 

src/main/java/org/springframework/hateoas/config/WebMvcHateoasConfiguration.java

@@ -18,6 +18,7 @@
 import lombok.RequiredArgsConstructor;
 
 import java.util.Collection;
+import java.util.Collections;
 import java.util.List;
 import java.util.stream.Collectors;
 
@@ -27,12 +28,17 @@
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.hateoas.RepresentationModel;
+import org.springframework.hateoas.server.RepresentationModelProcessor;
+import org.springframework.hateoas.server.mvc.RepresentationModelProcessorHandlerMethodReturnValueHandler;
+import org.springframework.hateoas.server.mvc.RepresentationModelProcessorInvoker;
 import org.springframework.hateoas.server.mvc.TypeConstrainedMappingJackson2HttpMessageConverter;
 import org.springframework.hateoas.server.mvc.UriComponentsContributor;
 import org.springframework.hateoas.server.mvc.WebMvcLinkBuilderFactory;
 import org.springframework.http.converter.HttpMessageConverter;
 import org.springframework.web.client.RestTemplate;
+import org.springframework.web.method.support.HandlerMethodReturnValueHandlerComposite;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
@@ -51,6 +57,13 @@ HypermediaWebMvcConfigurer hypermediaWebMvcConfigurer(ObjectProvider<ObjectMappe
 		return new HypermediaWebMvcConfigurer(mapper.getIfAvailable(ObjectMapper::new), hypermediaTypes);
 	}
 
+	@Bean
+	HypermediaRepresentationModelBeanProcessorPostProcessor hypermediaRepresentionModelProcessorConfigurator(
+			List<RepresentationModelProcessor<?>> processors) {
+
+		return new HypermediaRepresentationModelBeanProcessorPostProcessor(processors);
+	}
+
 	@Bean
 	static HypermediaRestTemplateBeanPostProcessor restTemplateBeanPostProcessor(
 			ObjectProvider<HypermediaWebMvcConfigurer> configurer) {
@@ -91,6 +104,34 @@ public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
 		}
 	}
 
+	/**
+	 * @author Greg Turnquist
+	 */
+	@RequiredArgsConstructor
+	static class HypermediaRepresentationModelBeanProcessorPostProcessor implements BeanPostProcessor {
+
+		private final List<RepresentationModelProcessor<?>> processors;
+
+		@Override
+		public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
+
+			if (RequestMappingHandlerAdapter.class.isInstance(bean)) {
+
+				RequestMappingHandlerAdapter adapter = (RequestMappingHandlerAdapter) bean;
+
+				HandlerMethodReturnValueHandlerComposite delegate = new HandlerMethodReturnValueHandlerComposite();
+				delegate.addHandlers(adapter.getReturnValueHandlers());
+
+				RepresentationModelProcessorHandlerMethodReturnValueHandler handler = new RepresentationModelProcessorHandlerMethodReturnValueHandler(
+						delegate, new RepresentationModelProcessorInvoker(processors));
+
+				adapter.setReturnValueHandlers(Collections.singletonList(handler));
+			}
+
+			return bean;
+		}
+	}
+
 	/**
 	 * {@link BeanPostProcessor} to register hypermedia support with {@link RestTemplate} instances found in the
 	 * application context.