Allow operations to produce different output

Update the actuator @Enpoint` infrastructure code so that operations
may inject enums that indicate the type of output to produce. A new
`Producible` interface can be implemented by any enum that indicates
the mime-type that an enum value produces.

The new `OperationArgumentResolver` provides a general strategy for
resolving operation arguments with `ProducibleOperationArgumentResolver`
providing support for `Producible` enums. Existing injection support has
been refactored to use the new resolver.

See gh-25738

Author: wilkinsona

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/endpoint/InvocationContext.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.
@@ -16,7 +16,12 @@
 
 package org.springframework.boot.actuate.endpoint;
 
+import java.security.Principal;
+import java.util.ArrayList;
+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;
@@ -31,11 +36,9 @@
  */
 public class InvocationContext {
 
-	private final SecurityContext securityContext;
-
 	private final Map<String, Object> arguments;
 
-	private final ApiVersion apiVersion;
+	private final List<OperationArgumentResolver> argumentResolvers;
 
 	/**
 	 * Creates a new context for an operation being invoked by the given
@@ -54,13 +57,34 @@ public InvocationContext(SecurityContext securityContext, Map<String, Object> ar
 	 * @param securityContext the current security context. Never {@code null}
 	 * @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)}
 	 */
+	@Deprecated
 	public InvocationContext(ApiVersion apiVersion, SecurityContext securityContext, Map<String, Object> arguments) {
+		this(securityContext, arguments, Arrays.asList(new FixedValueArgumentResolver<>(ApiVersion.class, apiVersion)));
+	}
+
+	/**
+	 * Creates a new context for an operation being invoked by the given
+	 * {@code securityContext} with the given available {@code arguments}.
+	 * @param securityContext the current security context. Never {@code null}
+	 * @param arguments the arguments available to the operation. Never {@code null}
+	 * @param argumentResolvers resolvers for additional arguments should be available to
+	 * the operation.
+	 */
+	public InvocationContext(SecurityContext securityContext, Map<String, Object> arguments,
+			List<OperationArgumentResolver> argumentResolvers) {
 		Assert.notNull(securityContext, "SecurityContext must not be null");
 		Assert.notNull(arguments, "Arguments must not be null");
-		this.apiVersion = (apiVersion != null) ? apiVersion : ApiVersion.LATEST;
-		this.securityContext = securityContext;
 		this.arguments = arguments;
+		this.argumentResolvers = new ArrayList<>();
+		if (argumentResolvers != null) {
+			this.argumentResolvers.addAll(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));
 	}
 
 	/**
@@ -69,15 +93,17 @@ public InvocationContext(ApiVersion apiVersion, SecurityContext securityContext,
 	 * @since 2.2.0
 	 */
 	public ApiVersion getApiVersion() {
-		return this.apiVersion;
+		return resolveArgument(ApiVersion.class);
 	}
 
 	/**
 	 * Return the security context to use for the invocation.
 	 * @return the security context
+	 * @deprecated since 2.5.0 in favor of {@link #resolveArgument(Class)}
 	 */
+	@Deprecated
 	public SecurityContext getSecurityContext() {
-		return this.securityContext;
+		return resolveArgument(SecurityContext.class);
 	}
 
 	/**
@@ -88,4 +114,92 @@ public Map<String, Object> getArguments() {
 		return this.arguments;
 	}
 
+	/**
+	 * Resolves an argument with the given {@code argumentType}.
+	 * @param <T> type of the argument
+	 * @param argumentType type of the argument
+	 * @return resolved argument of the required type or {@code null}
+	 * @since 2.5.0
+	 * @see #canResolve(Class)
+	 */
+	public <T> T resolveArgument(Class<T> argumentType) {
+		for (OperationArgumentResolver argumentResolver : this.argumentResolvers) {
+			if (argumentResolver.canResolve(argumentType)) {
+				T result = argumentResolver.resolve(argumentType);
+				if (result != null) {
+					return result;
+				}
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Returns whether or not the context is capable of resolving an argument of the given
+	 * {@code type}. Note that, even when {@code true} is returned,
+	 * {@link #resolveArgument argument resolution} will return {@code null} if no
+	 * argument of the required type is available.
+	 * @param type argument type
+	 * @return {@code true} if resolution of arguments of the given type is possible,
+	 * otherwise {@code false}.
+	 * @since 2.5.0
+	 * @see #resolveArgument(Class)
+	 */
+	public boolean canResolve(Class<?> type) {
+		for (OperationArgumentResolver argumentResolver : this.argumentResolvers) {
+			if (argumentResolver.canResolve(type)) {
+				return true;
+			}
+		}
+		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

@@ -0,0 +1,43 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://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.boot.actuate.endpoint;
+
+/**
+ * Resolver for an argument of an {@link Operation}.
+ *
+ * @author Andy Wilkinson
+ * @since 2.5.0
+ */
+public interface OperationArgumentResolver {
+
+	/**
+	 * Resolves an argument of the given {@code type}.
+	 * @param <T> required type of the argument
+	 * @param type argument type
+	 * @return an argument of the required type, or {@code null}
+	 */
+	<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}
+	 */
+	boolean canResolve(Class<?> type);
+
+}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 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.
@@ -20,6 +20,7 @@
 import java.util.Map;
 
 import org.springframework.util.CollectionUtils;
+import org.springframework.util.MimeType;
 import org.springframework.util.MimeTypeUtils;
 
 /**
@@ -29,17 +30,17 @@
  * @author Phillip Webb
  * @since 2.2.0
  */
-public enum ApiVersion {
+public enum ApiVersion implements Producible<ApiVersion> {
 
 	/**
 	 * Version 2 (supported by Spring Boot 2.0+).
 	 */
-	V2,
+	V2(ActuatorMediaType.V2_JSON),
 
 	/**
 	 * Version 3 (supported by Spring Boot 2.2+).
 	 */
-	V3;
+	V3(ActuatorMediaType.V3_JSON);
 
 	private static final String MEDIA_TYPE_PREFIX = "application/vnd.spring-boot.actuator.";
 
@@ -87,4 +88,15 @@ 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;
+	}
+
 }

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

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://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.boot.actuate.endpoint.http;
+
+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.
+ *
+ * @param <E> enum type that implements this interface
+ * @author Andy Wilkinson
+ * @since 2.5.0
+ */
+public interface Producible<E extends Enum<E> & Producible<E>> {
+
+	/**
+	 * Mime type that can be produced.
+	 * @return the producible mime type
+	 */
+	MimeType getMimeType();
+
+}