001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2023–2024 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.  You 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 ReductionException} 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 class AmbiguousReductionException extends ReductionException {
025
026  private static final long serialVersionUID = 1L;
027
028  private final transient Collection<?> alternates;
029
030
031  /*
032   * Constructors.
033   */
034
035
036  /**
037   * Creates a new {@link AmbiguousReductionException}.
038   *
039   * @param criteria the criteria by which a reduction was supposed to be effected; may be {@code null}
040   *
041   * @param alternates the contextual instances that could not be reduced; may be {@code null}
042   *
043   * @param message a detail message describing the exception; may be {@code null}
044   */
045  public AmbiguousReductionException(final Object criteria,
046                                     final Collection<?> alternates,
047                                     final String message) {
048    super(criteria, message, null);
049    if (alternates == null || alternates.isEmpty()) {
050      this.alternates = List.of();
051    } else {
052      this.alternates = List.copyOf(alternates);
053    }
054  }
055
056  /**
057   * Returns the contextual instances that could not be reduced.
058   *
059   * <p>This method never returns {@code null}.</p>
060   *
061   * @return a non-{@code null}, immutable {@link Collection} of contextual instances
062   */
063  public final Collection<?> alternates() {
064    return this.alternates;
065  }
066
067}