001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 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.io.Serializable;
020
021import java.lang.annotation.Annotation;
022
023import java.util.Collection;
024import java.util.Collections; // for javadoc only
025import java.util.Set;
026
027/**
028 * Provides <a href="{@docRoot}/overview-summary.html#ambiguity">value
029 * arbitration services</a> most commonly to a {@link Settings}
030 * instance in cases where {@linkplain Value setting values} would
031 * otherwise be indistinguishable from one another.
032 *
033 * @author <a href="https://about.me/lairdnelson"
034 * target="_parent">Laird Nelson</a>
035 *
036 * @see #arbitrate(Set, String, Set, Collection)
037 *
038 * @see Settings#arbitrate(Set, String, Set, Collection)
039 *
040 * @see Settings#Settings(Set, BiFunction, ConverterProvider,
041 * Iterable)
042 */
043public abstract class Arbiter implements Serializable {
044
045
046  /*
047   * Static fields.
048   */
049
050  
051  /**
052   * The version of this class for {@linkplain Serializable
053   * serialization purposes}.
054   */
055  private static final long serialVersionUID = 1L;
056
057
058  /*
059   * Constructors.
060   */
061
062  
063  /**
064   * Creates a new {@link Arbiter}.
065   */
066  protected Arbiter() {
067    super();
068  }
069
070
071  /*
072   * Instance methods.
073   */
074
075
076  /**
077   * Performs <em>value arbitration</em> on a {@link Collection} of
078   * {@link Value}s that (normally) a {@link Settings} instance
079   * determined were indistinguishable during value acquisition, and
080   * returns the {@link Value} to be used instead (normally drawn from
081   * the {@link Collection} according to some heuristic).
082   *
083   * @param sources the {@link Set} of {@link Source}s in effect
084   * during the current value acquisition operation; must not be
085   * {@code null}; must be {@linkplain
086   * Collections#unmodifiableSet(Set) unmodifiable}; must be safe for
087   * concurrent read-only access by multiple threads
088   *
089   * @param name the name of the setting value being sought; must not
090   * be {@code null}
091   *
092   * @param qualifiers the {@link Set} of qualifier {@link
093   * Annotation}s in effect during the current value acquisition
094   * operation; must not be {@code null}; must be {@linkplain
095   * Collections#unmodifiableSet(Set) unmodifiable}; must be safe for
096   * concurrent read-only access by multiple threads
097   *
098   * @param values the {@link Collection} of {@link Value}s acquired
099   * during the current value acquisition operation that were deemed
100   * to be indistinguishable; must not be {@code null}; must be
101   * {@linkplain Collections#unmodifiableSet(Set) unmodifiable}; must
102   * be safe for concurrent read-only access by multiple threads
103   *
104   * @return the result of value arbitration as a single {@link
105   * Value}, or {@code null} if this {@link Arbiter} could not select
106   * a single {@link Value}
107   *
108   * @exception NullPointerException if any parameter value is {@code
109   * null}
110   *
111   * @exception ArbitrationException if there was a procedural problem
112   * with arbitration
113   */
114  public abstract Value arbitrate(final Set<? extends Source> sources, // non-null
115                                  final String name, // non-null
116                                  final Set<? extends Annotation> qualifiers,
117                                  final Collection<? extends Value> values);
118  
119}