001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2019–2020 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.settings;
018
019import java.lang.annotation.Annotation;
020
021import java.util.Set;
022
023import org.microbean.settings.Value;
024
025/**
026 * An abstraction of a source of {@link String}-typed configuration
027 * values.
028 *
029 * <p>{@link Source} instances are used most commonly by {@link
030 * Settings} instances, which layer conversion and arbitration atop
031 * them.</p>
032 *
033 * @threadsafety Instances of this class must be safe for concurrent
034 * use by multiple threads.
035 *
036 * @author <a href="https://about.me/lairdnelson"
037 * target="_parent">Laird Nelson</a>
038 *
039 * @see #getValue(String, Set)
040 *
041 * @see Value
042 *
043 * @see Settings
044 *
045 * @see Settings#get(String, Set, Class, BiFunction)
046 */
047public abstract class Source {
048
049  /**
050   * Creates or otherwise acquires and returns a {@link Value} for the
051   * supplied {@code name} and {@link Set} of qualifiers.
052   *
053   * @param name the name of the setting for which a {@link Value} is
054   * to be returned; must not be {@code null}
055   * 
056   * @param qualifiers a {@link Set} of qualifier {@link Annotation}
057   * instances; may be {@code null}
058   *
059   * @return a suitable {@link Value}, or {@code null} if no {@link
060   * Value} could be created or acquired
061   *
062   * @exception NullPointerException if {@code name} is {@code null}
063   *
064   * @exception ValueAcquisitionException if there was a procedural
065   * problem acquiring a {@link Value}
066   *
067   * @nullability Implementations of this method are permitted to
068   * return {@code null}.
069   *
070   * @idempotency An implementation of this method need not be
071   * idempotent.  That is, two invocations supplied with the same
072   * {@code name} and {@code qualifiers} parameter values may or may
073   * not return {@link Value}s that are identical, {@linkplain
074   * Object#equals(Object) equal} or neither.
075   *
076   * @threadsafety Implementations of this method must be safe for
077   * concurrent use by multiple threads.
078   */
079  public abstract Value getValue(final String name, final Set<Annotation> qualifiers);
080  
081}