Clean up API

Signed-off-by: Matt Sicker <boards@gmail.com>

docs/consumer.adoc

@@ -488,14 +488,7 @@ Plugins acting on a build can do the following:
 
 [source,java]
 ----
-CredentialsParametersAction action = run.getAction(CredentialsParametersAction.class);
-if (action == null) {
-  action = new CredentialsParametersAction();
-}
-action.add(userId, parameterValue); // <1>
-action.addFromParameterValues(userId, parameterValues); // <2>
-run.replaceAction(action); // <3>
+BuildCredentialsResolver resolver = BuildCredentialsResolver.forRun(build);
+resolver.bindCredentialsParameter(userId, parameterValue); // <1>
 ----
 <1> The `userId` is only required if the parameter value references user credentials.
-<2> Convenience method to add `CredentialsParameterValue`s from some collection of `ParameterValue`s:
-<3> Add or update the action.

src/main/java/com/cloudbees/plugins/credentials/CredentialsProvider.java

@@ -23,6 +23,8 @@
  */
 package com.cloudbees.plugins.credentials;
 
+import com.cloudbees.plugins.credentials.builds.CredentialsParameterBinding;
+import com.cloudbees.plugins.credentials.builds.CredentialsParameterBinder;
 import com.cloudbees.plugins.credentials.common.IdCredentials;
 import com.cloudbees.plugins.credentials.domains.DomainRequirement;
 import com.cloudbees.plugins.credentials.fingerprints.ItemCredentialsFingerprintFacet;
@@ -878,20 +880,18 @@ public static <C extends IdCredentials> C findCredentialById(@NonNull String id,
         boolean isParameter = false;
         boolean isDefaultValue = false;
         String inputUserId = null;
-        final CredentialsParametersAction action = CredentialsParametersAction.forRun(run);
-        if (action != null) {
-            final CredentialsParametersAction.AuthenticatedCredentials credentials = id.startsWith("${") && id.endsWith("}") ?
-                    // denotes explicitly that this is a parameterized credential
-                    action.findCredentialsByParameterName(id.substring(2, id.length() - 1)) :
-                    // otherwise, we can check to see if there is a matching credential parameter name that shadows an
-                    // existing global credential id
-                    action.findCredentialsByParameterName(id);
-            if (credentials != null) {
-                isParameter = true;
-                inputUserId = credentials.getUserId();
-                isDefaultValue = credentials.getParameterValue().isDefaultValue();
-                id = Util.fixNull(credentials.getParameterValue().getValue());
-            }
+        final CredentialsParameterBinder binder = CredentialsParameterBinder.getOrCreate(run);
+        final CredentialsParameterBinding binding = id.startsWith("${") && id.endsWith("}") ?
+                // denotes explicitly that this is a parameterized credential
+                binder.forParameterName(id.substring(2, id.length() - 1)) :
+                // otherwise, we can check to see if there is a matching credential parameter name that shadows an
+                // existing global credential id
+                binder.forParameterName(id);
+        if (binding != null) {
+            isParameter = true;
+            inputUserId = binding.getUserId();
+            isDefaultValue = binding.isDefaultValue();
+            id = Util.fixNull(binding.getCredentialsId());
         }
         // non parameters or default parameter values can only come from the job's context
         if (!isParameter || isDefaultValue) {

src/main/java/com/cloudbees/plugins/credentials/builds/CredentialsParameterBinder.java

@@ -0,0 +1,101 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2019 CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.cloudbees.plugins.credentials.builds;
+
+import com.cloudbees.plugins.credentials.CredentialsParameterValue;
+import hudson.model.Cause;
+import hudson.model.InvisibleAction;
+import hudson.model.ParameterValue;
+import hudson.model.ParametersAction;
+import hudson.model.Run;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.NoExternalUse;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Tracks credentials being bound and unbound to a build. An instance is created and attached to a build when it is
+ * first looked up via {@link #getOrCreate(Run)}. This binds any existing {@link CredentialsParameterValue}s using the
+ * {@link hudson.model.Cause.UserIdCause} if available. Other plugins may
+ * {@linkplain #bindCredentialsParameter(String, CredentialsParameterValue) bind} and
+ * {@linkplain #unbindCredentialsParameter(String) unbind} parameters during a build.
+ *
+ * @since 2.3.0
+ */
+public final class CredentialsParameterBinder extends InvisibleAction {
+
+    /**
+     * Gets or creates a CredentialsParameterBinder for the given run.
+     * This automatically imports credentials parameters provided in a {@link ParametersAction}.
+     */
+    @Nonnull
+    public static CredentialsParameterBinder getOrCreate(@Nonnull final Run<?, ?> run) {
+        CredentialsParameterBinder resolver = run.getAction(CredentialsParameterBinder.class);
+        if (resolver == null) {
+            resolver = new CredentialsParameterBinder();
+            final ParametersAction action = run.getAction(ParametersAction.class);
+            if (action != null) {
+                final Cause.UserIdCause cause = run.getCause(Cause.UserIdCause.class);
+                final String userId = cause == null ? null : cause.getUserId();
+                for (final ParameterValue parameterValue : action) {
+                    if (parameterValue instanceof CredentialsParameterValue) {
+                        resolver.bindCredentialsParameter(userId, (CredentialsParameterValue) parameterValue);
+                    }
+                }
+            }
+            run.addAction(resolver);
+        }
+        return resolver;
+    }
+
+    private final Map<String, CredentialsParameterBinding> boundCredentials = new ConcurrentHashMap<>();
+
+    /**
+     * Binds a credentials parameter with an optional user ID. User credentials require a user ID.
+     */
+    public void bindCredentialsParameter(@CheckForNull final String userId, @Nonnull final CredentialsParameterValue parameterValue) {
+        boundCredentials.put(parameterValue.getName(), CredentialsParameterBinding.fromParameter(userId, parameterValue));
+    }
+
+    /**
+     * Unbinds a credentials parameter.
+     */
+    public void unbindCredentialsParameter(@Nonnull final String parameterName) {
+        boundCredentials.remove(parameterName);
+    }
+
+    @CheckForNull
+    @Restricted(NoExternalUse.class)
+    public CredentialsParameterBinding forParameterName(@Nonnull final String parameterName) {
+        return boundCredentials.get(parameterName);
+    }
+
+    boolean isEmpty() {
+        return boundCredentials.isEmpty();
+    }
+}

src/main/java/com/cloudbees/plugins/credentials/builds/CredentialsParameterBinding.java

@@ -0,0 +1,77 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2019 CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.cloudbees.plugins.credentials.builds;
+
+import com.cloudbees.plugins.credentials.CredentialsParameterValue;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.NoExternalUse;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+
+/**
+ * Associates a user ID to a {@link CredentialsParameterValue}. This is effectively a flattened tuple of that.
+ *
+ * @since 2.3.0
+ */
+@Restricted(NoExternalUse.class)
+public class CredentialsParameterBinding {
+
+    static CredentialsParameterBinding fromParameter(@CheckForNull final String userId, @Nonnull final CredentialsParameterValue parameterValue) {
+        return new CredentialsParameterBinding(userId, parameterValue.getName(), parameterValue.getValue(),
+                parameterValue.isDefaultValue());
+    }
+
+    private final String userId;
+    private final String parameterName;
+    private final String credentialsId;
+    private final boolean isDefaultValue;
+
+    private CredentialsParameterBinding(String userId, String parameterName, String credentialsId, boolean isDefaultValue) {
+        this.userId = userId;
+        this.parameterName = parameterName;
+        this.credentialsId = credentialsId;
+        this.isDefaultValue = isDefaultValue;
+    }
+
+    @CheckForNull
+    public String getUserId() {
+        return userId;
+    }
+
+    @Nonnull
+    public String getParameterName() {
+        return parameterName;
+    }
+
+    @CheckForNull
+    public String getCredentialsId() {
+        return credentialsId;
+    }
+
+    public boolean isDefaultValue() {
+        return isDefaultValue;
+    }
+}