KeySelector (Java SE 26 & JDK 26)
Description: declaration: module: java.xml.crypto, package: javax.xml.crypto, class: KeySelector
Keywords: javax.xml.crypto.KeySelector class

# Class KeySelector

java.lang.Object
javax.xml.crypto.KeySelector

public abstract class KeySelector extends Object
A selector that finds and returns a key using the data contained in a `KeyInfo` object. An example of an implementation of this class is one that searches a `KeyStore` for trusted keys that match information contained in a `KeyInfo`.

Whether or not the returned key is trusted and the mechanisms used to determine that is implementation-specific.

Since:
  1.6

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `KeySelector.Purpose`
  The purpose of the key that is to be selected.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `KeySelector()`
  Default no-args constructor; intended for invocation by subclasses only.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract KeySelectorResult`
  `select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context)`
  Attempts to find a key that satisfies the specified constraints.
  `static KeySelector`
  `singletonKeySelector(Key key)`
  Returns a `KeySelector` that always selects the specified key, regardless of the `KeyInfo` passed to it.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### KeySelector

    protected KeySelector()
    Default no-args constructor; intended for invocation by subclasses only.

- ## Method Details

  - ### select

    public abstract KeySelectorResult select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context) throws KeySelectorException
    Attempts to find a key that satisfies the specified constraints.
    Parameters:
      `keyInfo` - a `KeyInfo` (may be `null`)
      `purpose` - the key's purpose (`KeySelector.Purpose.SIGN`, `KeySelector.Purpose.VERIFY`, `KeySelector.Purpose.ENCRYPT`, or `KeySelector.Purpose.DECRYPT`)
      `method` - the algorithm method that this key is to be used for. Only keys that are compatible with the algorithm and meet the constraints of the specified algorithm should be returned.
      `context` - an `XMLCryptoContext` that may contain useful information for finding an appropriate key. If this key selector supports resolving `RetrievalMethod` types, the context's `baseURI` and `dereferencer` parameters (if specified) should be used by the selector to resolve and dereference the URI.
    Returns:
      the result of the key selector
    Throws:
      `KeySelectorException` - if an exceptional condition occurs while attempting to find a key. Note that an inability to find a key is not considered an exception (`null` should be returned in that case). However, an error condition (ex: network communications failure) that prevented the `KeySelector` from finding a potential key should be considered an exception.
      `ClassCastException` - if the data type of `method` is not supported by this key selector

  - ### singletonKeySelector

    public static KeySelector singletonKeySelector(Key key)
    Returns a `KeySelector` that always selects the specified key, regardless of the `KeyInfo` passed to it.
    Parameters:
      `key` - the sole key to be stored in the key selector
    Returns:
      a key selector that always selects the specified key
    Throws:
      `NullPointerException` - if `key` is `null`