001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2022 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.invoke;
018
019import java.util.NoSuchElementException;
020
021/**
022 * An {@link OptionalSupplier} implementation that indicates permanent
023 * absence.
024 *
025 * @author <a href="https://about.me/lairdnelson"
026 * target="_parent">Laird Nelson</a>
027 */
028public final class Absence<T> implements OptionalSupplier<T> {
029
030
031  /*
032   * Static fields.
033   */
034
035
036  private static final Absence<?> INSTANCE = new Absence<Void>();
037
038
039  /*
040   * Constructors.
041   */
042
043
044  private Absence() {
045    super();
046  }
047
048
049  /*
050   * Instance methods.
051   */
052
053
054  /**
055   * Returns {@link Determinism#ABSENT} when invoked.
056   *
057   * @return {@link Determinism#ABSENT} when invoked
058   *
059   * @nullability This method never returns {@code null}.
060   *
061   * @idempotency This method is idempotent and deterministic.
062   *
063   * @threadsafety This method is safe for concurrent use by multiple
064   * threads.
065   */
066  @Override // OptionalSupplier<T>
067  public final Determinism determinism() {
068    return Determinism.ABSENT;
069  }
070
071  /**
072   * Throws a {@link NoSuchElementException} when invoked.
073   *
074   * @return nothing
075   *
076   * @exception NoSuchElementException when invoked
077   *
078   * @nullability This method never returns {@code null}.
079   *
080   * @idempotency This method is idempotent and deterministic.
081   *
082   * @threadsafety This method is safe for concurrent use by multiple
083   * threads.
084   */
085  @Override // OptionalSupplier<T>
086  public final T get() {
087    throw new NoSuchElementException();
088  }
089
090
091  /*
092   * Static methods.
093   */
094
095
096  /**
097   * Returns the sole instance of this class.
098   *
099   * @param <T> the type of the nonexistent value the returned {@link
100   * Absence} will never {@linkplain #get() supply}
101   *
102   * @return the sole instance of this class
103   *
104   * @nullability This method never returns {@code null}.
105   *
106   * @idempotency This method is idempotent and deterministic.
107   *
108   * @threadsafety This method is safe for concurrent use by multiple
109   * threads.
110   */
111  @SuppressWarnings("unchecked")
112  public static final <T> Absence<T> instance() {
113    return (Absence<T>)INSTANCE;
114  }
115
116}