Polishing.

Add since and author tags. Reorder fields.

Introduce empty VaultTokenRequest and refactor interface methods to default methods for delegation on the interface level.

See gh-690
Original pull request: gh-803

Author: mp911de

spring-vault-core/src/main/java/org/springframework/vault/core/VaultTokenOperations.java

@@ -24,6 +24,7 @@
  * Interface that specifies token-related operations.
  *
  * @author Mark Paluch
+ * @author Nanne Baars
  * @see <a href="https://www.vaultproject.io/docs/auth/token.html">Auth Backend: Token</a>
  */
 public interface VaultTokenOperations {
@@ -34,7 +35,9 @@ public interface VaultTokenOperations {
 	 * @see <a href="https://www.vaultproject.io/docs/auth/token.html">POST
 	 * /auth/token/create</a>
 	 */
-	VaultTokenResponse create() throws VaultException;
+	default VaultTokenResponse create() throws VaultException {
+		return create(VaultTokenRequest.empty());
+	}
 
 	/**
 	 * Create a new token for the given {@link VaultTokenRequest}.
@@ -51,16 +54,20 @@ public interface VaultTokenOperations {
 	 * @return a {@link VaultTokenResponse}
 	 * @see <a href="https://www.vaultproject.io/docs/auth/token.html">POST
 	 * /auth/token/create/:role</a>
+	 * @since 3.1
 	 */
-	VaultTokenResponse create(String role) throws VaultException;
+	default VaultTokenResponse create(String role) throws VaultException {
+		return create(role, VaultTokenRequest.empty());
+	}
 
 	/**
 	 * Create a new token for the given {@code role} and {@link VaultTokenRequest}.
-	 * @param role must not be {@literal null}.
+	 * @param role must not be {@literal null} or empty.
 	 * @param request must not be {@literal null}.
 	 * @return a {@link VaultTokenResponse}
 	 * @see <a href="https://www.vaultproject.io/docs/auth/token.html">POST
 	 * /auth/token/create/:role</a>
+	 * @since 3.1
 	 */
 	VaultTokenResponse create(String role, VaultTokenRequest request) throws VaultException;
 
@@ -70,7 +77,9 @@ public interface VaultTokenOperations {
 	 * @see <a href="https://www.vaultproject.io/docs/auth/token.html">POST
 	 * /auth/token/create-orphan</a>
 	 */
-	VaultTokenResponse createOrphan();
+	default VaultTokenResponse createOrphan() {
+		return createOrphan(VaultTokenRequest.empty());
+	}
 
 	/**
 	 * Create a new orphan token for the given {@link VaultTokenRequest}.

spring-vault-core/src/main/java/org/springframework/vault/core/VaultTokenTemplate.java

@@ -34,6 +34,7 @@
  * Default implementation of {@link VaultTokenOperations}.
  *
  * @author Mark Paluch
+ * @author Nanne Baars
  */
 public class VaultTokenTemplate implements VaultTokenOperations {
 
@@ -50,11 +51,6 @@ public VaultTokenTemplate(VaultOperations vaultOperations) {
 		this.vaultOperations = vaultOperations;
 	}
 
-	@Override
-	public VaultTokenResponse create() {
-		return create(VaultTokenRequest.builder().build());
-	}
-
 	@Override
 	public VaultTokenResponse create(VaultTokenRequest request) {
 
@@ -63,24 +59,13 @@ public VaultTokenResponse create(VaultTokenRequest request) {
 		return writeAndReturn("auth/token/create", request, VaultTokenResponse.class);
 	}
 
-	@Override
-	public VaultTokenResponse create(String role) throws VaultException {
-
-		return create(role, VaultTokenRequest.builder().build());
-	}
-
 	@Override
 	public VaultTokenResponse create(String role, VaultTokenRequest request) throws VaultException {
 
-		Assert.notNull(role, "role must not be null");
+		Assert.hasText(role, "Role must not be null or empty");
 		Assert.notNull(request, "VaultTokenRequest must not be null");
 
-		return writeAndReturn("auth/token/create/%s".formatted(role), request, VaultTokenResponse.class);
-	}
-
-	@Override
-	public VaultTokenResponse createOrphan() {
-		return createOrphan(VaultTokenRequest.builder().build());
+		return writeAndReturn(String.format("auth/token/create/%s", role), request, VaultTokenResponse.class);
 	}
 
 	@Override

spring-vault-core/src/main/java/org/springframework/vault/support/VaultTokenRequest.java

@@ -22,20 +22,23 @@
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
+import java.util.stream.StreamSupport;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 
-import java.util.stream.StreamSupport;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
  * Value object to bind Vault HTTP Token API requests.
  *
  * @author Mark Paluch
+ * @author Nanne Baars
  */
 public class VaultTokenRequest {
 
+	private static final VaultTokenRequest EMPTY = VaultTokenRequest.builder().build();
+
 	@Nullable
 	private final String id;
 
@@ -61,15 +64,15 @@ public class VaultTokenRequest {
 	@JsonProperty("display_name")
 	private final String displayName;
 
-	@JsonProperty("num_uses")
-	private final int numUses;
-
 	@JsonProperty("entity_alias")
 	private final String entityAlias;
 
+	@JsonProperty("num_uses")
+	private final int numUses;
+
 	VaultTokenRequest(@Nullable String id, List<String> policies, Map<String, String> meta, boolean noParent,
 			boolean noDefaultPolicy, boolean renewable, @Nullable String ttl, @Nullable String explicitMaxTtl,
-			String displayName, int numUses, String entityAlias) {
+			String displayName, String entityAlias, int numUses) {
 
 		this.id = id;
 		this.policies = policies;
@@ -91,6 +94,14 @@ public static VaultTokenRequestBuilder builder() {
 		return new VaultTokenRequestBuilder();
 	}
 
+	/**
+	 * @return an empty token request.
+	 * @since 3.1
+	 */
+	public static VaultTokenRequest empty() {
+		return EMPTY;
+	}
+
 	/**
 	 * @return Id of the client token.
 	 */
@@ -159,19 +170,19 @@ public String getDisplayName() {
 	}
 
 	/**
-	 * @return the number of allowed token uses.
+	 * @return then name of the entity alias to associate with during token creation. Only
+	 * works in combination with role name.
+	 * @since 3.1
 	 */
-	public int getNumUses() {
-		return this.numUses;
+	public String getEntityAlias() {
+		return this.entityAlias;
 	}
 
 	/**
-	 * @return then name of the entity alias to associate with during token creation. Only
-	 * works in combination with role_name argument and used entity alias must be listed
-	 * in allowed_entity_aliases
+	 * @return the number of allowed token uses.
 	 */
-	public String getEntityAlias() {
-		return this.entityAlias;
+	public int getNumUses() {
+		return this.numUses;
 	}
 
 	/**
@@ -200,17 +211,18 @@ public static class VaultTokenRequestBuilder {
 
 		private String displayName = "";
 
-		private int numUses;
-
+		@Nullable
 		private String entityAlias;
 
+		private int numUses;
+
 		VaultTokenRequestBuilder() {
 		}
 
 		/**
-		 * Configure a the Id of the client token. Can only be specified by a root token.
-		 * Otherwise, the token Id is a randomly generated UUID.
-		 * @param id the token Id.
+		 * Configure the token identifier. Can only be specified by a root token.
+		 * Otherwise, the token identifier is a randomly generated UUID.
+		 * @param id the token identifier.
 		 * @return {@code this} {@link VaultTokenRequestBuilder}.
 		 */
 		public VaultTokenRequestBuilder id(String id) {
@@ -386,21 +398,6 @@ public VaultTokenRequestBuilder explicitMaxTtl(Duration explicitMaxTtl) {
 			return this;
 		}
 
-		/**
-		 * Configure the maximum uses for the token. This can be used to create a
-		 * one-time-token or limited use token. Defaults to {@literal 0}, which has no
-		 * limit to the number of uses.
-		 * @param numUses number of uses, must not be negative.
-		 * @return {@code this} {@link VaultTokenRequestBuilder}.
-		 */
-		public VaultTokenRequestBuilder numUses(int numUses) {
-
-			Assert.isTrue(numUses >= 0, "Number of uses must not be negative");
-
-			this.numUses = numUses;
-			return this;
-		}
-
 		/**
 		 * Configure a display name for the token, defaults to "token".
 		 * @param displayName must not be empty or {@literal null}.
@@ -418,6 +415,7 @@ public VaultTokenRequestBuilder displayName(String displayName) {
 		 * Configure the entity alias for the token.
 		 * @param entityAlias must not be empty or {@literal null}.
 		 * @return {@code this} {@link VaultTokenRequestBuilder}.
+		 * @since 3.1
 		 */
 		public VaultTokenRequestBuilder entityAlias(String entityAlias) {
 
@@ -428,9 +426,20 @@ public VaultTokenRequestBuilder entityAlias(String entityAlias) {
 		}
 
 		/**
-		 * Build a new {@link VaultTokenRequest} instance.
-		 * @return a new {@link VaultCertificateRequest}.
+		 * Configure the maximum uses for the token. This can be used to create a
+		 * one-time-token or limited use token. Defaults to {@literal 0}, which has no
+		 * limit to the number of uses.
+		 * @param numUses number of uses, must not be negative.
+		 * @return {@code this} {@link VaultTokenRequestBuilder}.
 		 */
+		public VaultTokenRequestBuilder numUses(int numUses) {
+
+			Assert.isTrue(numUses >= 0, "Number of uses must not be negative");
+
+			this.numUses = numUses;
+			return this;
+		}
+
 		/**
 		 * Build a new {@link VaultTokenRequest} instance.
 		 * @return a new {@link VaultCertificateRequest}.
@@ -442,13 +451,12 @@ public VaultTokenRequest build() {
 				case 1 -> List.of(this.policies.get(0));
 				default -> List.copyOf(this.policies);
 			};
-			Map<String, String> meta = switch (this.meta.size()) {
-				case 0 -> Map.of();
-				default -> Collections.unmodifiableMap(new LinkedHashMap<>(this.meta));
-			};
+
+			Map<String, String> meta = this.meta.isEmpty() ? Map.of()
+					: Collections.unmodifiableMap(new LinkedHashMap<>(this.meta));
 
 			return new VaultTokenRequest(this.id, policies, meta, this.noParent, this.noDefaultPolicy, this.renewable,
-					this.ttl, this.explicitMaxTtl, this.displayName, this.numUses, this.entityAlias);
+					this.ttl, this.explicitMaxTtl, this.displayName, this.entityAlias, this.numUses);
 		}
 
 		private static <E> List<E> toList(Iterable<E> iter) {

spring-vault-core/src/test/java/org/springframework/vault/core/VaultTokenTemplateIntegrationTests.java

@@ -47,6 +47,7 @@
  * Integration tests for {@link VaultTokenTemplate} through {@link VaultTokenOperations}.
  *
  * @author Mark Paluch
+ * @author Nanne Baars
  */
 @ExtendWith(SpringExtension.class)
 @ContextConfiguration(classes = VaultIntegrationTestConfiguration.class)
@@ -100,8 +101,7 @@ void createTokenWithRoleShouldCreateAToken() {
 
 	@Test
 	void noTokenWhenRoleDoesNotExists() {
-
-		assertThatThrownBy(() -> this.tokenOperations.create("unknown-role")).isInstanceOf(VaultException.class);
+		assertThatExceptionOfType(VaultException.class).isThrownBy(() -> this.tokenOperations.create("unknown-role"));
 	}
 
 	@Test