/*
 * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.security;

import java.net.URI;
import java.util.*;
import static java.security.KeyStore.*;

/**
 * Configuration data that specifies the keystores in a keystore domain.
 * A keystore domain is a collection of keystores that are presented as a
 * single logical keystore. The configuration data is used during
 * {@code KeyStore}
 * {@link KeyStore#load(KeyStore.LoadStoreParameter) load} and
 * {@link KeyStore#store(KeyStore.LoadStoreParameter) store} operations.
 * <p>
 * The following syntax is supported for configuration data:
 * <pre>{@code
 * domain <domainName> [<property> ...] {
 * keystore <keystoreName> [<property> ...] ;
 * ...
 * };
 * ...
 * }</pre>
 * where {@code domainName} and {@code keystoreName} are identifiers
 * and {@code property} is a key/value pairing. The key and value are
 * separated by an 'equals' symbol and the value is enclosed in double
 * quotes. A property value may be either a printable string or a binary
 * string of colon-separated pairs of hexadecimal digits. Multi-valued
 * properties are represented as a comma-separated list of values,
 * enclosed in square brackets.
 * See {@link Arrays#toString(java.lang.Object[])}.
 * <p>
 * To ensure that keystore entries are uniquely identified, each
 * entry's alias is prefixed by its {@code keystoreName} followed
 * by the entry name separator and each {@code keystoreName} must be
 * unique within its domain. Entry name prefixes are omitted when
 * storing a keystore.
 * <p>
 * Properties are context-sensitive: properties that apply to
 * all the keystores in a domain are located in the domain clause,
 * and properties that apply only to a specific keystore are located
 * in that keystore's clause.
 * Unless otherwise specified, a property in a keystore clause overrides
 * a property of the same name in the domain clause. All property names
 * are case-insensitive. The following properties are supported:
 * <dl>
 * <dt> {@code keystoreType="<type>"} </dt>
 * <dd> The keystore type. </dd>
 * <dt> {@code keystoreURI="<url>"} </dt>
 * <dd> The keystore location. </dd>
 * <dt> {@code keystoreProviderName="<name>"} </dt>
 * <dd> The name of the keystore's JCE provider. </dd>
 * <dt> {@code keystorePasswordEnv="<environment-variable>"} </dt>
 * <dd> The environment variable that stores a keystore password.
 * Alternatively, passwords may be supplied to the constructor
 * method in a {@code Map<String, ProtectionParameter>}. </dd>
 * <dt> {@code entryNameSeparator="<separator>"} </dt>
 * <dd> The separator between a keystore name prefix and an entry name.
 * When specified, it applies to all the entries in a domain.
 * Its default value is a space. </dd>
 * </dl>
 * <p>
 * For example, configuration data for a simple keystore domain
 * comprising three keystores is shown below:
 * <pre>
 *
 * domain app1 {
 * keystore app1-truststore
 * keystoreURI="file:///app1/etc/truststore.jks";
 *
 * keystore system-truststore
 * keystoreURI="${java.home}/lib/security/cacerts";
 *
 * keystore app1-keystore
 * keystoreType="PKCS12"
 * keystoreURI="file:///app1/etc/keystore.p12";
 * };
 *
 * </pre>
 * @since 1.8
 */
public final class DomainLoadStoreParameter implements LoadStoreParameter {

 private final URI configuration;
 private final Map<String,ProtectionParameter> protectionParams;

 /**
 * Constructs a DomainLoadStoreParameter for a keystore domain with
 * the parameters used to protect keystore data.
 *
 * @param configuration identifier for the domain configuration data.
 * The name of the target domain should be specified in the
 * {@code java.net.URI} fragment component when it is necessary
 * to distinguish between several domain configurations at the
 * same location.
 *
 * @param protectionParams the map from keystore name to the parameter
 * used to protect keystore data.
 * A {@code java.util.Collections.EMPTY_MAP} should be used
 * when protection parameters are not required or when they have
 * been specified by properties in the domain configuration data.
 * It is cloned to prevent subsequent modification.
 *
 * @exception NullPointerException if {@code configuration} or
 * {@code protectionParams} is {@code null}
 */
 public DomainLoadStoreParameter(URI configuration,
 Map<String,ProtectionParameter> protectionParams) {
 if (configuration == null || protectionParams == null) {
 throw new NullPointerException("invalid null input");
 }
 this.configuration = configuration;
 this.protectionParams =
 Collections.unmodifiableMap(new HashMap<>(protectionParams));
 }

 /**
 * Gets the identifier for the domain configuration data.
 *
 * @return the identifier for the configuration data
 */
 public URI getConfiguration() {
 return configuration;
 }

 /**
 * Gets the keystore protection parameters for keystores in this
 * domain.
 *
 * @return an unmodifiable map of keystore names to protection
 * parameters
 */
 public Map<String,ProtectionParameter> getProtectionParams() {
 return protectionParams;
 }

 /**
 * Gets the keystore protection parameters for this domain.
 * Keystore domains do not support a protection parameter.
 *
 * @return always returns {@code null}
 */
 @Override
 public KeyStore.ProtectionParameter getProtectionParameter() {
 return null;
 }
}