anchor.diff:  ****
   
   === Retrieve a previously selected credentials instance
  +
  +Assuming you have previously stored the `IdCredentials.getId()`, at some point in time you will want to retrieve it.
  +
  +If you are working in the context of a `Run` then this is essentially quite simple:
  +
  +[source,java]
  +----
  +StandardCredentials c = CredentialsProvider.findCredentialsById(
  +  idOrExpression, // <1>
  +  StandardCredentials.class, // <2>
  +  run, // <3>
  +  URIRequirementBuilder.fromUri(...) // <4>
  +); // <5>
  +----
  +<1> This method call will take care of evaluating credentials expressions for you.
  +<2> You can use a more specific type if you need to.
  +<3> You must supply the `hudson.model.Run` instance, the authentication will be determined based on the authentication that the run is using and / or the authentication of the triggering user if the triggering user selected a credential in a credentials parameter and they have permission to supply their own personal credentials.
  +<4> Always supply the domain information used when displaying the original drop-down as there could be duplicate IDs between domains.
  +<5> The credential usage will be automatically associated with the `Run` via the fingerprint API for you.
  +
  +.Why are credentials expressions permissions so complex
  +****
  +If we have a job, "foobar", and we configure a credentials parameter on that job, we can have a number of different ways the credentials get selected:
  +
  +* There is the possibility that the parameter uses a default value. The default value should be resolved in the context of the job's authentication from `Tasks.getAuthenticationOf(job)`
  +* If the user selects a value, they may have `Credentials/USE_ITEM`, in which case the value should be resolved in the context of the job's authentication from `Tasks.getAuthenticationOf(job)`
  +* If the user selects a value, they may have `Credentials/USE_OWN`, in which case the value should be resolved in the context of their own per-user credentials store
  +****
  +
  +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.lookupCredentials(...)` wrapped within `CredentialsMatchers.firstOrNull(..., CredentialsMatchers.withId(...))`, for example:
  +
  +[source,java]
  +----
  +StandardCredentials c = CredentialsMatchers.firstOrNull(
  +  CredentialsProvider.lookupCredentials(
  +    StandardCredentials.class, // <1>
  +    job, // <1>
  +    job instanceof Queue.Task // <1>
  +      ? Tasks.getAuthenticationOf((Queue.Task)job))
  +      : ACL.SYSTEM,
  +    URIRequirementBuilder.fromUri(...) // <1>
  +  ),
  +  CredentialsMatchers.withId(credentialsId) // <2>
  +);
  +----
  +<1> These should be the same as your call to `CredentialsProvider.listCredentials(...)`/`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.listCredentials(...)`/`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.
  +
  +=== Retrieve the secret from a specific credentials instance.
  +
  +All `Secret` and `SecretBytes` properties should be assumed as lazy-fetch and (even if not explicitly declared as such) assume that they could throw either `IOException` or `InterruptedException` on first invocation.
  +
  +If you access a `Secret` or `SecretBytes` property, you should ensure that the credential usage is tracked against the context object for which it was resolved _(unless you are using it in the context of form validation)_.
  +
  +If you need to send the credentials instance to another node (which is not recommended) then you should use `CredentialsProvider.snapshot(...)` and send the snapshot. Taking a snapshot is equivalent to accessing a `Secret` or `SecretBytes` property from the point of view of credentials usage tracking.
  +
  +The recommended way to use a credential is through the https://wiki.jenkins.io/display/JENKINS/Authentication+Tokens+API+Plugin[Authentication Tokens API]:
  +
  +[source,java]
  +----
  +StandardCredentials c = CredentialsMatchers.firstOrNull( // <1>
  +    CredentialsProvider.listCredentials(
  +      StandardCredentials.class,
  +      job,
  +      job instanceof Queue.Task
  +        ? Tasks.getAuthenticationOf((Queue.Task)job))
  +        : ACL.SYSTEM,
  +      URIRequirementBuilder.fromUri(issueTrackerUrl)
  +    ),
  +    CredentialsMatchers.allOf(
  +      CredentialsMatchers.withId(credentialsId),
  +      AuthenticationTokens.matcher(IssueTrackerAuthentication.class) // <2>
  +    )
  +  );
  +IssueTrackerAuthentication auth = AuthenticationTokens.convert(
  +  IssueTrackerAuthentication.class, // <2>
  +  c // <3>
  +);
  +----
  +<1> Do not inline the call as we need to hold onto the credentials instance in order to track its usage.
  +<2> If you need a more complex mapping then the `AuthenticationTokenContext` version can be used.
  +<3> The returned authentication will be `null` if not credentials were found.
  +
  +=== Track usage of a credential against specific Jenkins context objects
  +
  +Any time you access a credentials secret _(outside of form validation)_ you are responsible to ensure that the credentials usage is tracked.
  +If you have used `CredentialsProvider.findCredentialsById` then this obligation has been taken care of for you.
  +
  +To track usage, just pass the credentials instance and the context object to the corresponding overload of `CredentialsProvider.track(_context_, credentials)`. If you have multiple credentials to track, you can use `CredentialsProvider.trackAll(_context_, credentials...)`
  +
  +[source,java]
  +----
  +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.listCredentials(
  +        StandardCredentials.class,
  +        job,
  +        job instanceof Queue.Task
  +          ? Tasks.getAuthenticationOf((Queue.Task)job))
  +          : ACL.SYSTEM,
  +        URIRequirementBuilder.fromUri(issueTrackerUrl)
  +      ),
  +      CredentialsMatchers.allOf(
  +        CredentialsMatchers.withId(credentialsId),
  +        AuthenticationTokens.matcher(IssueTrackerAuthentication.class)
  +      )
  +    )
  +  )
  +);
  +----
  
positive.code: );
  ----
  <1> We want username password credentials and we want the user to be able to selected them
  We need `StandardCredentials.getId()` to allow retrieval when building the job.
  We need `UsernamePasswordCredentials` to ensure that they are username and password.
  <2> We will be using these credentials in the context of a specific job.
  <3> For almost all implementations of `Job`, this will be `true`.
  
negative.code: === Persist a reference to a specific credential instance
  
  You should be using `StandardCredentials` (or a more specific sub-interface) to access the Credentials API.
  Persist the `IdCredentials.getId()` of a credentials.
  For any given context and authentication, the `IdCredentials.getId()` should consistently return the same credentials instance.
  
  [TIP]
  ====
  Do not make any assumptions about the format of a `IdCredentials.getId()` other than it must not contain `${...}`
  ====
  
  .Historical evolution of the API
  