anchor.diff:  === 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 `StandardCredentials.getId()` of a credentials.
  -For any given context and authentication, the `StandardCredentials.getId()` should consistently return the same credentials instance.
  +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 `StandardCredentials.getId()` other than it must not contain `${...}`
  +Do not make any assumptions about the format of a `IdCredentials.getId()` other than it must not contain `${...}`
   ====
   
   .Historical evolution of the API
  
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: ****
  
  === 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)
        )
      )
    )
  );
  ----
  