001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2017–2019 microBean.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.  See the License for the specific language governing
015 * permissions and limitations under the License.
016 */
017package org.microbean.configuration.spi;
018
019import java.io.Serializable;
020
021import java.util.Map;
022import java.util.Set;
023
024import org.microbean.configuration.Configurations;
025
026import org.microbean.configuration.api.ConfigurationValue;
027
028/**
029 * An accessor of {@link ConfigurationValue}s in configuration space.
030 *
031 * <p>{@link Configuration} instances are typically controlled in the
032 * service of a governing {@link Configurations} object.</p>
033 *
034 * @author <a href="https://about.me/lairdnelson"
035 * target="_parent">Laird Nelson</a>
036 *
037 * @see #getValue(Map, String)
038 *
039 * @see ConfigurationValue
040 *
041 * @see Configurations#loadConfigurations()
042 */
043public interface Configuration {
044
045  /**
046   * Installs a {@link Configurations} object into this {@link
047   * Configuration} implementation.
048   *
049   * @param configurations the {@link Configurations} to install; must
050   * not be {@code null}
051   *
052   * @exception NullPointerException if {@code configurations} is
053   * {@code null}
054   */
055  public void setConfigurations(final Configurations configurations);
056
057  /**
058   * Returns a {@link ConfigurationValue} suitable for the supplied
059   * {@code configurationCoordinates} and {@code name}, or {@code
060   * null} if there is no suitable value.
061   *
062   * <p>Implementations of this method may return {@code null}.</p>
063   *
064   * <p>The {@link ConfigurationValue} that is returned must
065   * {@linkplain ConfigurationValue#getName() have a name} that is
066   * equal to the supplied {@code name}.</p>
067   *
068   * <p>The {@link ConfigurationValue} that is returned must be
069   * {@linkplain ConfigurationValue#ConfigurationValue(Serializable,
070   * Map, String, String, boolean) created} with this {@link
071   * Configuration} as the first parameter value supplied to its
072   * {@linkplain ConfigurationValue#ConfigurationValue(Serializable,
073   * Map, String, String, boolean) constructor}.</p>
074   *
075   * <p>The {@link ConfigurationValue} that is returned must be
076   * {@linkplain ConfigurationValue#ConfigurationValue(Serializable,
077   * Map, String, String, boolean) created} with a {@linkplain
078   * ConfigurationValue#getCoordinates() set of configuration
079   * coordinates} that is a subset of the supplied {@code
080   * configurationCoordinates}.</p>
081   *
082   * @param configurationCoordinates the configuration coordinates for
083   * which a value for the relevant configuration property, identified
084   * by the supplied {@code name}, should be returned; may be {@code
085   * null}
086   *
087   * @param name the name of the configuration property for which a
088   * {@link ConfigurationValue} will be returned; must not be {@code
089   * null}
090   *
091   * @return a {@link ConfigurationValue} suitable for the supplied
092   * {@code configurationCoordinates} and {@code name}, or {@code
093   * null}
094   *
095   * @exception NullPointerException if {@code name} is {@code null}
096   *
097   * @see ConfigurationValue
098   */
099  public ConfigurationValue getValue(final Map<String, String> configurationCoordinates, final String name);
100
101  /**
102   * Returns a {@link Set} of the names of all {@link
103   * ConfigurationValue}s that might be returned by this {@link
104   * Configuration}.
105   *
106   * <p>Implementations of this method must not return {@code
107   * null}.</p>
108   *
109   * <p>Just because a name appears in the returned {@link Set} does
110   * <em>not</em> mean that a {@link ConfigurationValue} will be
111   * returned for it in a location in configuration space identified
112   * by any arbitrary set of configuration coordinates.</p>
113   *
114   * @return a non-{@code null} {@link Set} of names
115   */
116  public Set<String> getNames();
117  
118}