001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- 002 * 003 * Copyright © 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. 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 org.microbean.assign.AttributedType; 017 018/** 019 * A supplier of {@link References} objects. 020 * 021 * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a> 022 * 023 * @see #references(AttributedType) 024 * 025 * @see #reference(AttributedType) 026 * 027 * @see References 028 */ 029// TODO: not crazy about the circular dependencies, but they're no worse than, say, a sealed class 030public interface ReferencesSelector { 031 032 /** 033 * Destroys the supplied contextual reference if and only if it meets the conditions for destruction. 034 * 035 * @param r a contextual reference; may be {@code null} in which case {@code false} will be returned 036 * 037 * @return {@code true} if and only if destruction occurred 038 * 039 * @exception DestructionException if an error occurs 040 */ 041 public boolean destroy(final Object r); // e.g. CDI's Instance#destroy(Object); works only on normal- and @Dependent-scoped objects 042 043 /** 044 * Returns a {@link References} capable of locating contextual references of the relevant type. 045 * 046 * @param <R> the contextual reference type 047 * 048 * @param t an {@link AttributedType} describing the contextual reference type; must not be {@code null} 049 * 050 * @return a non-{@code null} {@link References} 051 * 052 * @exception NullPointerException if {@code t} is {@code null} 053 * 054 * @see References 055 */ 056 public <R> References<R> references(final AttributedType t); 057 058 /** 059 * A convenience method that acquires and returns what is presumed, possibly incorrectly, to be the sole contextual 060 * reference of the relevant type. 061 * 062 * @param <R> the contextual reference type 063 * 064 * @param t an {@link AttributedType} describing the contextual reference type; must not be {@code null} 065 * 066 * @return a non-{@code null} contextual reference 067 * 068 * @exception NullPointerException if {@code t} is {@code null} 069 * 070 * @exception UnsatisfiedReductionException if there is no contextual reference for the relevant type 071 * 072 * @exception AmbiguousReductionException if there is more than one contextual reference for the relevant type 073 * 074 * @see #references(AttributedType) 075 * 076 * @see References#get() 077 */ 078 public default <R> R reference(final AttributedType t) { 079 return this.<R>references(t).get(); 080 } 081 082}