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}