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.SortedMap;
024import java.util.function.Supplier;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028import org.tquadrat.foundation.util.internal.LazySortedMapImpl;
029
030/**
031 *  The interface for a
032 *  {@link SortedMap}
033 *  that will be initialised only when required.
034 *
035 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
036 *  @version $Id: LazySortedMap.java 1032 2022-04-10 17:27:44Z tquadrat $
037 *  @since 0.0.5
038 *
039 *  @param <K> The type of keys maintained by this map.
040 *  @param <V> The type of mapped values.
041 *
042 *  @see org.tquadrat.foundation.lang.Lazy
043 *
044 *  @UMLGraph.link
045 */
046@ClassVersion( sourceVersion = "$Id: LazySortedMap.java 1032 2022-04-10 17:27:44Z tquadrat $" )
047@API( status = STABLE, since = "0.0.5" )
048public sealed interface LazySortedMap<K,V> extends LazyMap<K,V>, SortedMap<K,V>
049    permits LazySortedMapImpl
050{
051        /*---------*\
052    ====** Methods **==========================================================
053        \*---------*/
054    /**
055     *  Creates a new {@code LazySortedMap} instance that is already
056     *  initialised.
057     *
058     *  @param <K> The type of keys maintained by this map.
059     *  @param <V> The type of mapped values.
060     *  @param  value   The value.
061     *  @return The new instance.
062     */
063    @API( status = STABLE, since = "0.0.5" )
064    public static <K,V> LazySortedMap<K,V> of( final SortedMap<K,V> value )
065    {
066        return new LazySortedMapImpl<>( requireNonNullArgument( value, "value" ) );
067    }   //  of()
068
069    /**
070     *  Creates a new {@code LazySortedMap} instance that uses the given
071     *  supplier to create the internal map, but that supplier will not
072     *  populate the map with entries.
073     *
074     *  @param <K> The type of keys maintained by this map.
075     *  @param <V> The type of mapped values.
076     *  @param  supplier    The supplier that initialises the new instance of
077     *      {@code LazySortedMap} when needed.
078     *  @return The new instance.
079     */
080    @API( status = STABLE, since = "0.0.5" )
081    public static <K,V> LazySortedMap<K,V> use( final Supplier<? extends SortedMap<K, V>> supplier )
082    {
083        return new LazySortedMapImpl<>( false, supplier );
084    }   //  use()
085
086    /**
087     *  Creates a new {@code LazySortedMap} instance that uses the given
088     *  supplier to initialise.
089     *
090     *  @param <K> The type of keys maintained by this map.
091     *  @param <V> The type of mapped values.
092     *  @param  doPopulate  {@code true} if the provided supplier will put
093     *      values to the map on initialisation, {@code false} if it will
094     *      create an empty map.
095     *  @param  supplier    The supplier that initialises the new instance of
096     *      {@code LazySortedMap} when needed.
097     *  @return The new instance.
098     */
099    @API( status = STABLE, since = "0.0.5" )
100    public static <K,V> LazySortedMap<K,V> use( final boolean doPopulate, final Supplier<? extends SortedMap<K, V>> supplier )
101    {
102        return new LazySortedMapImpl<>( doPopulate, supplier );
103    }   //  use()
104}
105//  interface LazySortedMap
106
107/*
108 *  End of File
109 */