Refine 'Allow operations to produce different output'

Refine the new `Producible` support so that it can also be used with
`@ReadOperation`, `@WriteOperation` and `@DeleteOperation` annotations.

This update allows the same enum to be used both as an argument and as
an indicator of the media-types that an operation may produce.

Closes gh-25738

Author: philwebb

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/InvocationContext.java

@@ -21,7 +21,6 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
-import java.util.function.Supplier;
 
 import org.springframework.boot.actuate.endpoint.http.ApiVersion;
 import org.springframework.boot.actuate.endpoint.invoke.OperationInvoker;
@@ -58,11 +57,11 @@ public InvocationContext(SecurityContext securityContext, Map<String, Object> ar
 	 * @param arguments the arguments available to the operation. Never {@code null}
 	 * @since 2.2.0
 	 * @deprecated since 2.5.0 in favor of
-	 * {@link #InvocationContext(SecurityContext, Map, List)}
+	 * {@link #InvocationContext(SecurityContext, Map, OperationArgumentResolver[])}
 	 */
 	@Deprecated
 	public InvocationContext(ApiVersion apiVersion, SecurityContext securityContext, Map<String, Object> arguments) {
-		this(securityContext, arguments, Arrays.asList(new FixedValueArgumentResolver<>(ApiVersion.class, apiVersion)));
+		this(securityContext, arguments, OperationArgumentResolver.of(ApiVersion.class, () -> apiVersion));
 	}
 
 	/**
@@ -74,17 +73,17 @@ public InvocationContext(ApiVersion apiVersion, SecurityContext securityContext,
 	 * the operation.
 	 */
 	public InvocationContext(SecurityContext securityContext, Map<String, Object> arguments,
-			List<OperationArgumentResolver> argumentResolvers) {
+			OperationArgumentResolver... argumentResolvers) {
 		Assert.notNull(securityContext, "SecurityContext must not be null");
 		Assert.notNull(arguments, "Arguments must not be null");
 		this.arguments = arguments;
 		this.argumentResolvers = new ArrayList<>();
 		if (argumentResolvers != null) {
-			this.argumentResolvers.addAll(argumentResolvers);
+			this.argumentResolvers.addAll(Arrays.asList(argumentResolvers));
 		}
-		this.argumentResolvers.add(new FixedValueArgumentResolver<>(SecurityContext.class, securityContext));
-		this.argumentResolvers.add(new SuppliedValueArgumentResolver<>(Principal.class, securityContext::getPrincipal));
-		this.argumentResolvers.add(new FixedValueArgumentResolver<>(ApiVersion.class, ApiVersion.LATEST));
+		this.argumentResolvers.add(OperationArgumentResolver.of(SecurityContext.class, () -> securityContext));
+		this.argumentResolvers.add(OperationArgumentResolver.of(Principal.class, securityContext::getPrincipal));
+		this.argumentResolvers.add(OperationArgumentResolver.of(ApiVersion.class, () -> ApiVersion.LATEST));
 	}
 
 	/**
@@ -154,52 +153,4 @@ public boolean canResolve(Class<?> type) {
 		return false;
 	}
 
-	private static final class FixedValueArgumentResolver<T> implements OperationArgumentResolver {
-
-		private final Class<T> argumentType;
-
-		private final T value;
-
-		private FixedValueArgumentResolver(Class<T> argumentType, T value) {
-			this.argumentType = argumentType;
-			this.value = value;
-		}
-
-		@SuppressWarnings("unchecked")
-		@Override
-		public <U> U resolve(Class<U> type) {
-			return (U) this.value;
-		}
-
-		@Override
-		public boolean canResolve(Class<?> type) {
-			return this.argumentType.equals(type);
-		}
-
-	}
-
-	private static final class SuppliedValueArgumentResolver<T> implements OperationArgumentResolver {
-
-		private final Class<T> argumentType;
-
-		private final Supplier<T> value;
-
-		private SuppliedValueArgumentResolver(Class<T> argumentType, Supplier<T> value) {
-			this.argumentType = argumentType;
-			this.value = value;
-		}
-
-		@SuppressWarnings("unchecked")
-		@Override
-		public <U> U resolve(Class<U> type) {
-			return (U) this.value.get();
-		}
-
-		@Override
-		public boolean canResolve(Class<?> type) {
-			return this.argumentType.equals(type);
-		}
-
-	}
-
 }

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/OperationArgumentResolver.java

@@ -16,6 +16,10 @@
 
 package org.springframework.boot.actuate.endpoint;
 
+import java.util.function.Supplier;
+
+import org.springframework.util.Assert;
+
 /**
  * Resolver for an argument of an {@link Operation}.
  *
@@ -24,6 +28,14 @@
  */
 public interface OperationArgumentResolver {
 
+	/**
+	 * Return whether an argument of the given {@code type} can be resolved.
+	 * @param type argument type
+	 * @return {@code true} if an argument of the required type can be resolved, otherwise
+	 * {@code false}
+	 */
+	boolean canResolve(Class<?> type);
+
 	/**
 	 * Resolves an argument of the given {@code type}.
 	 * @param <T> required type of the argument
@@ -33,11 +45,30 @@ public interface OperationArgumentResolver {
 	<T> T resolve(Class<T> type);
 
 	/**
-	 * Return whether an argument of the given {@code type} can be resolved.
-	 * @param type argument type
-	 * @return {@code true} if an argument of the required type can be resolved, otherwise
-	 * {@code false}
+	 * Factory method that creates an {@link OperationArgumentResolver} for a specific
+	 * type using a {@link Supplier}.
+	 * @param <T> the resolvable type
+	 * @param type the resolvable type
+	 * @param supplier the value supplier
+	 * @return an {@link OperationArgumentResolver} instance
 	 */
-	boolean canResolve(Class<?> type);
+	static <T> OperationArgumentResolver of(Class<T> type, Supplier<? extends T> supplier) {
+		Assert.notNull(type, "Type must not be null");
+		Assert.notNull(supplier, "Supplier must not be null");
+		return new OperationArgumentResolver() {
+
+			@Override
+			public boolean canResolve(Class<?> actualType) {
+				return actualType.equals(type);
+			}
+
+			@Override
+			@SuppressWarnings("unchecked")
+			public <R> R resolve(Class<R> argumentType) {
+				return (R) supplier.get();
+			}
+
+		};
+	}
 
 }

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/annotation/DeleteOperation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2021 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.
@@ -40,4 +40,11 @@
 	 */
 	String[] produces() default {};
 
+	/**
+	 * The media types of the result of the operation.
+	 * @return the media types
+	 */
+	@SuppressWarnings("rawtypes")
+	Class<? extends Producible> producesFrom() default Producible.class;
+
 }

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/annotation/DiscoveredOperationMethod.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2021 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.
@@ -17,6 +17,7 @@
 package org.springframework.boot.actuate.endpoint.annotation;
 
 import java.lang.reflect.Method;
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
@@ -40,8 +41,32 @@ public DiscoveredOperationMethod(Method method, OperationType operationType,
 			AnnotationAttributes annotationAttributes) {
 		super(method, operationType);
 		Assert.notNull(annotationAttributes, "AnnotationAttributes must not be null");
-		String[] produces = annotationAttributes.getStringArray("produces");
-		this.producesMediaTypes = Collections.unmodifiableList(Arrays.asList(produces));
+		List<String> producesMediaTypes = new ArrayList<>();
+		producesMediaTypes.addAll(Arrays.asList(annotationAttributes.getStringArray("produces")));
+		producesMediaTypes.addAll(getProducesFromProducable(annotationAttributes));
+		this.producesMediaTypes = Collections.unmodifiableList(producesMediaTypes);
+	}
+
+	private <E extends Enum<E> & Producible<E>> List<String> getProducesFromProducable(
+			AnnotationAttributes annotationAttributes) {
+		Class<?> type = getProducesFrom(annotationAttributes);
+		if (type == Producible.class) {
+			return Collections.emptyList();
+		}
+		List<String> produces = new ArrayList<>();
+		for (Object value : type.getEnumConstants()) {
+			produces.add(((Producible<?>) value).getProducedMimeType().toString());
+		}
+		return produces;
+	}
+
+	private Class<?> getProducesFrom(AnnotationAttributes annotationAttributes) {
+		try {
+			return annotationAttributes.getClass("producesFrom");
+		}
+		catch (IllegalArgumentException ex) {
+			return Producible.class;
+		}
 	}
 
 	public List<String> getProducesMediaTypes() {

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/http/Producible.java renamed to spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/annotation/Producible.java

@@ -14,15 +14,23 @@
  * limitations under the License.
  */
 
-package org.springframework.boot.actuate.endpoint.http;
+package org.springframework.boot.actuate.endpoint.annotation;
 
 import org.springframework.util.MimeType;
 
 /**
- * Interface to be implemented by an {@link Enum} that can be injected into an operation
- * on a web endpoint. The value of the {@code Producible} enum is resolved using the
- * {@code Accept} header of the request. When multiple values are equally acceptable, the
- * value with the highest {@link Enum#ordinal() ordinal} is used.
+ * Interface that can be implemented by any {@link Enum} that represents a finite set of
+ * producible mime-types.
+ * <p>
+ * Can be used with {@link ReadOperation @ReadOperation},
+ * {@link WriteOperation @ReadOperation} and {@link DeleteOperation @ReadOperation}
+ * annotations to quickly define a list of {@code produces} values.
+ * <p>
+ * {@link Producible} types can also be injected into operations when the underlying
+ * technology supports content negotiation. For example, with web based endpoints, the
+ * value of the {@code Producible} enum is resolved using the {@code Accept} header of the
+ * request. When multiple values are equally acceptable, the value with the highest
+ * {@link Enum#ordinal() ordinal} is used.
  *
  * @param <E> enum type that implements this interface
  * @author Andy Wilkinson
@@ -34,6 +42,6 @@ public interface Producible<E extends Enum<E> & Producible<E>> {
 	 * Mime type that can be produced.
 	 * @return the producible mime type
 	 */
-	MimeType getMimeType();
+	MimeType getProducedMimeType();
 
 }

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/annotation/ReadOperation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2021 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.
@@ -39,4 +39,11 @@
 	 */
 	String[] produces() default {};
 
+	/**
+	 * The media types of the result of the operation.
+	 * @return the media types
+	 */
+	@SuppressWarnings("rawtypes")
+	Class<? extends Producible> producesFrom() default Producible.class;
+
 }

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/annotation/WriteOperation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2021 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.
@@ -39,4 +39,11 @@
 	 */
 	String[] produces() default {};
 
+	/**
+	 * The media types of the result of the operation.
+	 * @return the media types
+	 */
+	@SuppressWarnings("rawtypes")
+	Class<? extends Producible> producesFrom() default Producible.class;
+
 }

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/http/ApiVersion.java

@@ -19,6 +19,7 @@
 import java.util.List;
 import java.util.Map;
 
+import org.springframework.boot.actuate.endpoint.annotation.Producible;
 import org.springframework.util.CollectionUtils;
 import org.springframework.util.MimeType;
 import org.springframework.util.MimeTypeUtils;
@@ -49,12 +50,26 @@ public enum ApiVersion implements Producible<ApiVersion> {
 	 */
 	public static final ApiVersion LATEST = ApiVersion.V3;
 
+	private final MimeType mimeType;
+
+	ApiVersion(String mimeType) {
+		this.mimeType = MimeTypeUtils.parseMimeType(mimeType);
+	}
+
+	@Override
+	public MimeType getProducedMimeType() {
+		return this.mimeType;
+	}
+
 	/**
 	 * Return the {@link ApiVersion} to use based on the HTTP request headers. The version
 	 * will be deduced based on the {@code Accept} header.
 	 * @param headers the HTTP headers
 	 * @return the API version to use
+	 * @deprecated since 2.5.0 in favor of direct injection with resolution via the
+	 * {@link ProducibleOperationArgumentResolver}.
 	 */
+	@Deprecated
 	public static ApiVersion fromHttpHeaders(Map<String, List<String>> headers) {
 		ApiVersion version = null;
 		List<String> accepts = headers.get("Accept");
@@ -88,15 +103,4 @@ private static ApiVersion mostRecent(ApiVersion existing, ApiVersion candidate)
 		return (candidateOrdinal > existingOrdinal) ? candidate : existing;
 	}
 
-	private final MimeType mimeType;
-
-	ApiVersion(String mimeType) {
-		this.mimeType = MimeTypeUtils.parseMimeType(mimeType);
-	}
-
-	@Override
-	public MimeType getMimeType() {
-		return this.mimeType;
-	}
-
 }