Module java.base
Package java.security

# Class KeyStore.Builder

java.lang.Object
java.security.KeyStore.Builder

Enclosing class:
  `KeyStore`

public abstract static class KeyStore.Builder extends Object
A description of a to-be-instantiated `KeyStore` object.

An instance of this class encapsulates the information needed to instantiate and initialize a `KeyStore` object. That process is triggered when the getKeyStore() method is called.

This makes it possible to decouple configuration from `KeyStore` object creation and e.g. delay a password prompt until it is needed.

Since:
  1.5
See Also:
  - `KeyStore`
  - `KeyStoreBuilderParameters`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`Builder()`
Construct a new `Builder`.

## Method Summary

Modifier and Type
Method
Description
`abstract KeyStore`
`getKeyStore()`
Returns the `KeyStore` described by this object.
`abstract KeyStore.ProtectionParameter`
`getProtectionParameter(String alias)`
Returns the `ProtectionParameter` that should be used to obtain the `Entry` with the given alias.
`static KeyStore.Builder`
`newInstance(File file, KeyStore.ProtectionParameter protection)`
Returns a new `Builder` object.
`static KeyStore.Builder`
`newInstance(String type, Provider provider, File file, KeyStore.ProtectionParameter protection)`
Returns a new `Builder` object.
`static KeyStore.Builder`
`newInstance(String type, Provider provider, KeyStore.ProtectionParameter protection)`
Returns a new `Builder` object.
`static KeyStore.Builder`
`newInstance(KeyStore keyStore, KeyStore.ProtectionParameter protectionParameter)`
Returns a new `Builder` that encapsulates the given `KeyStore`.

### Methods declared in class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### Builder

protected Builder()
Construct a new `Builder`.

## Method Details

### getKeyStore

public abstract KeyStore getKeyStore() throws KeyStoreException
Returns the `KeyStore` described by this object.

Returns:
  the `KeyStore` described by this object
Throws:
  `KeyStoreException` - if an error occurred during the operation, for example if the `KeyStore` could not be instantiated or loaded

### getProtectionParameter

public abstract KeyStore.ProtectionParameter getProtectionParameter(String alias) throws KeyStoreException
Returns the `ProtectionParameter` that should be used to obtain the `Entry` with the given alias. The `getKeyStore` method must be invoked before this method may be called.

Parameters:
  `alias` - the alias of the `KeyStore` entry
Returns:
  the `ProtectionParameter` that should be used to obtain the `Entry` with the given alias.
Throws:
  `NullPointerException` - if alias is `null`
  `KeyStoreException` - if an error occurred during the operation
  `IllegalStateException` - if the `getKeyStore` method has not been invoked prior to calling this method

### newInstance

public static KeyStore.Builder newInstance(KeyStore keyStore, KeyStore.ProtectionParameter protectionParameter)
Returns a new `Builder` that encapsulates the given `KeyStore`. The getKeyStore() method of the returned object will return `keyStore`, the getProtectionParameter() method will return `protectionParameters`.

This is useful if an existing `KeyStore` object needs to be used with builder-based APIs.

Parameters:
  `keyStore` - the `KeyStore` to be encapsulated
  `protectionParameter` - the `ProtectionParameter` used to protect the `KeyStore` entries
Returns:
  a new `Builder` object
Throws:
  `NullPointerException` - if `keyStore` or `protectionParameter` is `null`
  `IllegalArgumentException` - if the `keyStore` has not been initialized

### newInstance

public static KeyStore.Builder newInstance(String type, Provider provider, File file, KeyStore.ProtectionParameter protection)
Returns a new `Builder` object.

The first call to the `getKeyStore()` method on the returned builder will create a `KeyStore` of type `type` and call its `load()` method. The `inputStream` argument is constructed from `file`. If `protection` is a `PasswordProtection`, the password is obtained by calling the `getPassword` method. Otherwise, if `protection` is a `CallbackHandlerProtection`, the password is obtained by invoking the CallbackHandler.

Subsequent calls to `getKeyStore()` return the same object as the initial call. If the initial call failed with a `KeyStoreException`, subsequent calls also throw a `KeyStoreException`.

The `KeyStore` is instantiated from `provider` if non-null. Otherwise, all installed providers are searched.

Calls to `getProtectionParameter()` will return a `PasswordProtection` object encapsulating the password that was used to invoke the `load` method.

Note that the `getKeyStore()` method is executed within the `AccessControlContext` of the code invoking this method.

Parameters:
  `type` - the type of `KeyStore` to be constructed
  `provider` - the provider from which the `KeyStore` is to be instantiated (or `null`)
  `file` - the File that contains the `KeyStore` data
  `protection` - the `ProtectionParameter` securing the `KeyStore` data
Returns:
  a new `Builder` object
Throws:
  `NullPointerException` - if type, file or protection is `null`
  `IllegalArgumentException` - if protection is not an instance of either PasswordProtection or CallbackHandlerProtection; or if file does not exist or does not refer to a normal file

### newInstance

public static KeyStore.Builder newInstance(File file, KeyStore.ProtectionParameter protection)
Returns a new `Builder` object.

The first call to the `getKeyStore()` method on the returned builder will create a `KeyStore` using `file` to detect the keystore type and then call its `load()` method. It uses the same algorithm to determine the keystore type as described in `KeyStore.getInstance(File, LoadStoreParameter)`. The `inputStream` argument is constructed from `file`. If `protection` is a `PasswordProtection`, the password is obtained by calling the `getPassword` method. Otherwise, if `protection` is a `CallbackHandlerProtection`, the password is obtained by invoking the CallbackHandler.

Subsequent calls to `getKeyStore()` return the same object as the initial call. If the initial call failed with a `KeyStoreException`, subsequent calls also throw a `KeyStoreException`.

Calls to `getProtectionParameter()` will return a `PasswordProtection` object encapsulating the password that was used to invoke the `load` method.

Note that the `getKeyStore()` method is executed within the `AccessControlContext` of the code invoking this method.

Parameters:
  `file` - the File that contains the `KeyStore` data
  `protection` - the `ProtectionParameter` securing the `KeyStore` data
Returns:
  a new `Builder` object
Throws:
  `NullPointerException` - if file or protection is `null`
  `IllegalArgumentException` - if protection is not an instance of either PasswordProtection or CallbackHandlerProtection; or if file does not exist or does not refer to a normal file
Since:
  9

### newInstance

public static KeyStore.Builder newInstance(String type, Provider provider, KeyStore.ProtectionParameter protection)
Returns a new `Builder` object.

Each call to the `getKeyStore()` method on the returned builder will return a new `KeyStore` object of type `type`. Its `load()` method is invoked using a `LoadStoreParameter` that encapsulates `protection`.

The `KeyStore` is instantiated from `provider` if non-null. Otherwise, all installed providers are searched.

Calls to `getProtectionParameter()` will return `protection`.

Note that the `getKeyStore()` method is executed within the `AccessControlContext` of the code invoking this method.

Parameters:
  `type` - the type of `KeyStore` to be constructed
  `provider` - the provider from which the `KeyStore` is to be instantiated (or `null`)
  `protection` - the `ProtectionParameter` securing the `Keystore`
Returns:
  a new `Builder` object
Throws:
  `NullPointerException` - if type or protection is `null`