001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2023–2025 microBean™.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
006 * the License.  ou may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
011 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
012 * specific language governing permissions and limitations under the License.
013 */
014package org.microbean.bean;
015
016import java.util.Collection;
017import java.util.List;
018
019/**
020 * A {@link ResolutionException} indicating that many contextual instances could not be reduced to one.
021 *
022 * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
023 */
024public final class AmbiguousResolutionException extends ResolutionException {
025
026
027  /*
028   * Static fields.
029   */
030
031
032  private static final long serialVersionUID = 1L;
033
034
035  /*
036   * Instance fields.
037   */
038
039
040  private final transient Collection<?> alternates;
041
042
043  /*
044   * Constructors.
045   */
046
047
048  /**
049   * Creates a new {@link AmbiguousResolutionException}.
050   *
051   * @param criteria the criteria by which a resolution was supposed to be effected; may be {@code null}
052   *
053   * @param alternates the contextual instances that could not be reduced; may be {@code null}
054   *
055   * @param message a detail message describing the exception; may be {@code null}
056   */
057  public AmbiguousResolutionException(final Object criteria,
058                                      final Collection<?> alternates,
059                                      final String message) {
060    super(criteria, message, null);
061    this.alternates = alternates == null || alternates.isEmpty() ? List.of() : List.copyOf(alternates);
062  }
063
064  /**
065   * Returns the contextual instances that could not be reduced.
066   *
067   * <p>This method never returns {@code null}.</p>
068   *
069   * @return a non-{@code null}, immutable {@link Collection} of contextual instances
070   */
071  public final Collection<?> alternates() {
072    return this.alternates;
073  }
074
075}