Merge branch 'master' into JENKINS-70101

Author: jimklimov

docs/consumer.adoc

@@ -281,26 +281,6 @@ We leverage the https://plugins.jenkins.io/authentication-tokens[Authentication
 This means that we can use the `AuthenticationTokens.matcher(Class)` to restrict the list of credentials to the subset that can be converted.
 Alternatively, more complex conversion contexts can be handled with `AuthenticationTokens.matcher(AuthenticationTokenContext)`
 
-* We want to let the user select the credentials to toggle the deployment state of a blue/green deployment for a completed build.
-+
-[source,java]
-----
-CredentialsProvider.listCredentialsInItem(
-    StandardCredentials.class, // <1>
-    job,
-    Jenkins.getAuthentication2(), // <2>
-    URIRequirementBuilder.fromUri(loadBalancerUrl),
-    CredentialsMatchers.allOf(
-      AuthenticationTokens.matcher(LoadBalancerAuthentication.class),
-      CredentialsMatchers.withProperty("permission", "lb.switch") // <3>
-    )
-)
-----
-<1> There are different credential types that can be used to authenticate with the load balancer, this is the common base class.
-<2> This is an immediate action performed by the user.
-<3> In this case there may be multiple credentials available to the user, we only want the ones with `"lb.switch".equals(credential.getPermission())`.
-Any credentials that do not have a `getPermission()` method will be excluded as well as any that do not have the corresponding return value.
-
 * We want to let the user specify the credentials used to update the post commit receive hooks of a source control system for any corresponding jobs configured in Jenkins.
 +
 [NOTE]
@@ -379,24 +359,21 @@ If we have a job, "foobar", and we configure a credentials parameter on that job
 
 If you are working outside the context of a `Run` then you will not have to deal with the complexities of credentials expressions.
 
-In most cases the retrieval will just be a call to one of the `CredentialsProvider.lookupCredentialsInItem(...)`/`CredentialsProvider.lookupCredentialsInItemGroup(...)` wrapped within `CredentialsMatchers.firstOrNull(..., CredentialsMatchers.withId(...))`, for example:
+In most cases the retrieval will just be a call to `CredentialsProvider.findCredentialByIdInItemGroup` or `CredentialsProvider.findCredentialByIdInItem`:
 
 [source,java]
 ----
-StandardCredentials c = CredentialsMatchers.firstOrNull(
-  CredentialsProvider.lookupCredentialsInItem(
+StandardCredentials c = CredentialsProvider.findCredentialByIdInItem(
+    credentialsId,
     StandardCredentials.class, // <1>
     job, // <1>
     job instanceof Queue.Task // <1>
       ? Tasks.getAuthenticationOf((Queue.Task)job))
       : ACL.SYSTEM2,
     URIRequirementBuilder.fromUri(...) // <1>
-  ),
-  CredentialsMatchers.withId(credentialsId) // <2>
-);
+  );
 ----
 <1> These should be the same as your call to `CredentialsProvider.listCredentialsInItem(...)`/`CredentialsProvider.listCredentialsInItemGroup(...)`/`StandardListBoxModel.includeMatchingAs(...)` in order to ensure that we get the same credential instance back.
-<2> If you had additional `CredentialsMatcher` expressions in your call to `CredentialsProvider.listCredentialsInItem(...)`/`CredentialsProvider.listCredentialsInItemGroup(...)`/`StandardListBoxModel.includeMatchingAs(...)` then you should merge them here with a `CredentialsMatchers.allOf(...)`
 
 Once you have retrieved a non-null credentials instance, all non-secret properties can be assumed as eager-fetch immutable.
 
@@ -412,20 +389,18 @@ The recommended way to use a credential is through the https://plugins.jenkins.i
 
 [source,java]
 ----
-StandardCredentials c = CredentialsMatchers.firstOrNull( // <1>
-    CredentialsProvider.listCredentialsInItem(
+StandardCredentials c = CredentialsProvider.findCredentialByIdInItem( // <1>
+      credentialsId,
       StandardCredentials.class,
       job,
       job instanceof Queue.Task
         ? Tasks.getAuthenticationOf2((Queue.Task)job))
         : ACL.SYSTEM2,
       URIRequirementBuilder.fromUri(issueTrackerUrl)
-    ),
-    CredentialsMatchers.allOf(
-      CredentialsMatchers.withId(credentialsId),
-      AuthenticationTokens.matcher(IssueTrackerAuthentication.class) // <2>
-    )
-  );
+    );
+if (c != null && !AuthenticationTokens.matcher(IssueTrackerAuthentication.class).matches(c)) {
+  c = null;
+}
 IssueTrackerAuthentication auth = AuthenticationTokens.convert(
   IssueTrackerAuthentication.class, // <2>
   c // <3>
@@ -449,32 +424,6 @@ StandardCredentials c = ...;
 CredentialsProvider.track(job, c);
 ----
 
-In most cases we can avoid holding object references longer than necessary by combining all these methods together:
-
-[source,java]
-----
-IssueTrackerAuthentication auth = AuthenticationTokens.convert(
-  IssueTrackerAuthentication.class,
-  CredentialsProvider.track(
-    job,
-    CredentialsMatchers.firstOrNull(
-      CredentialsProvider.listCredentialsInItem(
-        StandardCredentials.class,
-        job,
-        job instanceof Queue.Task
-          ? Tasks.getAuthenticationOf2((Queue.Task)job))
-          : ACL.SYSTEM2,
-        URIRequirementBuilder.fromUri(issueTrackerUrl)
-      ),
-      CredentialsMatchers.allOf(
-        CredentialsMatchers.withId(credentialsId),
-        AuthenticationTokens.matcher(IssueTrackerAuthentication.class)
-      )
-    )
-  )
-);
-----
-
 === Binding user supplied credentials parameters to builds
 
 A running build can be supplied with credentials parameter values.

docs/implementation.adoc

@@ -576,7 +576,6 @@ The `CredentialsProvider` extension point is perhaps one of the more complicated
 * Where the backing store is remote from Jenkins then:
 
 ** potentially has to be able to either instantiate `java.lang.reflect.Proxy` implementations for credentials, or create on-demand implementation classes using http://asm.ow2.org/[ASM] (or similar).
-** potentially has to deal with parsing the `CredentialsMatcher` query language in order to minimize transfer of information over the network.
 ** may need to store Jenkins specific state in Jenkins in order to provide credentials domain support.
 
 * Where the backing store is local to Jenkins but contextual to a specific Jenkins model object and not covered by the three existing credentials providers: System, User and Folder, then replication of that code will likely be required.
@@ -597,7 +596,6 @@ These existing examples are probably not good as reference examples as they have
 +
 A good reference implementation would be clean of such distractions.
 * [ ] Provide links to some other implementations of credentials providers for other use cases.
-* [ ] Provide some details on how the Credentials Query Language can be used to limit querying credentials from the remote service
 
 ====
 
@@ -698,6 +696,8 @@ Listing credentials operations are normally restricted to the population of cred
 Such requests are AJAX requests, so we have the option to block without affecting the rest of the Jenkins UI.
 
 Blocking for more than between 5 and 10 seconds, however, will cause user frustration, thus for this type of request we try to serve the response live and fall-back to the cache if the live response takes too long.
+
+Runtime lookups of credentials is normally limited to loading a specific credential by id, so consider overriding the methods which take an id argument.
 ====
 
 These different caching concerns are addresses at different points in the credentials API:

pom.xml

@@ -29,7 +29,7 @@
   <parent>
     <groupId>org.jenkins-ci.plugins</groupId>
     <artifactId>plugin</artifactId>
-    <version>5.2102.v5f5fe09fccf1</version>
+    <version>6.2122.v70b_7b_f659d72</version>
     <relativePath />
   </parent>
 
@@ -212,23 +212,6 @@
           <compatibleSinceVersion>1354</compatibleSinceVersion>
         </configuration>
       </plugin>
-      <plugin>
-        <groupId>org.antlr</groupId>
-        <artifactId>antlr4-maven-plugin</artifactId>
-        <!-- This must be compatible with the ANTLR runtime provided by Jenkins core. -->
-        <version>4.13.2</version>
-        <configuration>
-          <listener>true</listener>
-          <visitor>true</visitor>
-        </configuration>
-        <executions>
-          <execution>
-            <goals>
-              <goal>antlr4</goal>
-            </goals>
-          </execution>
-        </executions>
-      </plugin>
     </plugins>
   </build>
 </project>