001/*
002 * ============================================================================
003 * Copyright © 2002-2020 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.util;
019
020import static org.apiguardian.api.API.Status.STABLE;
021import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
022
023import java.util.Comparator;
024import java.util.List;
025import java.util.function.Consumer;
026import java.util.function.Supplier;
027
028import org.apiguardian.api.API;
029import org.tquadrat.foundation.annotation.ClassVersion;
030import org.tquadrat.foundation.util.internal.LazyListImpl;
031
032/**
033 *  The interface for a
034 *  {@link List}
035 *  that will be initialised only when required.
036 *
037 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
038 *  @version $Id: LazyList.java 1032 2022-04-10 17:27:44Z tquadrat $
039 *  @since 0.0.5
040 *
041 *  @param  <E> The type of elements in this list.
042 *
043 *  @see org.tquadrat.foundation.lang.Lazy
044 *
045 *  @note   There is no implementation of a {@code map()} method in this
046 *      interface because it is assumed that this would be confusing: such a
047 *      {@code map()} method would operate on the whole list that is wrapped by
048 *      this value, and not on an entry as one would expect. Refer to
049 *      {@link org.tquadrat.foundation.lang.Lazy#map(java.util.function.Function)}.
050 *
051 *  @UMLGraph.link
052 */
053@ClassVersion( sourceVersion = "$Id: LazyList.java 1032 2022-04-10 17:27:44Z tquadrat $" )
054@API( status = STABLE, since = "0.0.5" )
055public sealed interface LazyList<E> extends List<E>
056    permits LazyListImpl
057{
058        /*---------*\
059    ====** Methods **==========================================================
060        \*---------*/
061    /**
062     *  If this {@code LazyList} instance has been initialised already, the
063     *  provided
064     *  {@link Consumer}
065     *  will be executed; otherwise nothing happens.
066     *
067     *  @param  consumer    The consumer.
068     */
069    public void ifPresent( final Consumer<? super List<E>> consumer );
070
071    /**
072     *  Forces the initialisation of this {@code LazyList} instance.
073     */
074    public void init();
075
076    /**
077     *  Checks whether this {@code LazyList} instance has been initialised
078     *  already.
079     *
080     *  @return {@code true} if the instance was initialised, {@code false}
081     *      otherwise.
082     */
083    public boolean isPresent();
084
085    /**
086     *  Creates a new {@code LazyList} instance that is already initialised.
087     *
088     *  @param  <E> The type of elements in this list.
089     *  @param  value   The value.
090     *  @return The new instance.
091     */
092    @API( status = STABLE, since = "0.0.5" )
093    public static <E> LazyList<E> of( final List<E> value )
094    {
095        return new LazyListImpl<>( requireNonNullArgument( value, "value" ) );
096    }   //  of()
097
098    /**
099     *  {@inheritDoc}
100     */
101    @Override
102    public void sort( final Comparator<? super E> c );
103
104    /**
105     *  Creates a new {@code LazyList} instance that uses the given supplier to
106     *  create the internal map, but that supplier does not provide values on
107     *  initialisation.
108     *
109     *  @param  <E> The type of elements in this list.
110     *  @param  supplier    The supplier that initialises for the new instance
111     *      of {@code LazyList} when needed.
112     *  @return The new instance.
113     */
114    @API( status = STABLE, since = "0.0.5" )
115    public static <E> LazyList<E> use( final Supplier<? extends List<E>> supplier )
116    {
117        return new LazyListImpl<>( false, supplier );
118    }   //  use()
119
120    /**
121     *  Creates a new {@code LazyList} instance that uses the given supplier to
122     *  initialise.
123     *
124     *  @param  <E> The type of elements in this list.
125     *  @param  doPopulate  {@code true} if the provided supplier will put
126     *      entries to the list on initialisation, {@code false} if it will
127     *      create an empty list.
128     *  @param  supplier    The supplier that initialises for the new instance
129     *      of {@code LazyList} when needed.
130     *  @return The new instance.
131     */
132    @API( status = STABLE, since = "0.0.5" )
133    public static <E> LazyList<E> use( final boolean doPopulate, final Supplier<? extends List<E>> supplier )
134    {
135        return new LazyListImpl<>( doPopulate, supplier );
136    }   //  use()
137}
138//  interface LazyList
139
140/*
141 *  End of File
142 */