001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
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, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.lang;
019
020import static org.apiguardian.api.API.Status.STABLE;
021
022import java.util.function.Supplier;
023
024import org.apiguardian.api.API;
025import org.tquadrat.foundation.annotation.ClassVersion;
026import org.tquadrat.foundation.lang.internal.SoftLazyImpl;
027
028/**
029 *  Instances of the class {@code SoftLazy} allow to lazy load data that may be
030 *  needed more than once, but not permanently. An example might be data that
031 *  is needed during the startup phase of a program, but never again later.<br>
032 *  <br>The initializer method that is provided to
033 *  {@link #use(Supplier)}
034 *  must return the same result for each invocation, and this may not be
035 *  {@code null}.
036 *
037 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
038 *  @version $Id: SoftLazy.java 1060 2023-09-24 19:21:40Z tquadrat $
039 *  @since 0.0.5
040 *
041 *  @param  <T> The type of the cached data.
042 */
043@ClassVersion( sourceVersion = "$Id: SoftLazy.java 1060 2023-09-24 19:21:40Z tquadrat $" )
044@API( status = STABLE, since = "0.0.5" )
045public sealed interface SoftLazy<T>
046    permits org.tquadrat.foundation.lang.internal.SoftLazyImpl
047{
048        /*---------*\
049    ====** Methods **==========================================================
050        \*---------*/
051    /**
052     *  Returns the value from this instance of {@code SoftLazy}.
053     *
054     *  @return The value.
055     */
056    public T get();
057
058    /**
059     *  Creates an instance of {@code SoftLazy}.
060     *
061     *  @param  <D> The type of the cached data.
062     *  @param  initializer The initializer method.
063     *  @return The new instance of  {@code SoftLazy}.
064     */
065    @SuppressWarnings( "ClassReferencesSubclass" )
066    public static <D> SoftLazy<D> use( final Supplier<D> initializer )
067    {
068        final var retValue = new SoftLazyImpl<>( initializer );
069
070        //---* Done *----------------------------------------------------------
071        return retValue;
072    }   //  use()
073}
074//  class SoftLazy
075
076/*
077 *  End of File
078 */