/*
 * Copyright (c) 2021, 2023, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package Torello.Java.ReadOnly;

import Torello.Java.Additional.RemoveUnsupportedIterator;

import java.util.Map;
import java.util.Spliterator;
import java.util.stream.Stream;
import java.util.function.Consumer;
import java.util.function.IntFunction;
import java.util.Collection;


/**
 * Immutable variant of Java Collections Framework interface
 * <CODE>java&#46;util&#46;SequencedMap&lt;K, V&gt;</CODE>.
 * 
 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlySequencedMap DATA-FILE-ID=INTERFACES>
 * 
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE")
public interface ReadOnlySequencedMap<K, V> extends ReadOnlyMap<K, V>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Interface Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a reverse-ordered view of this map.  The
     * encounter order of mappings in the returned view is the inverse of the encounter order of
     * mappings in this map. The reverse ordering affects all order-sensitive operations, including
     * those on the view collections of the returned view.
     * 
     * @return a reverse-ordered view of this map
     */
    ReadOnlySequencedMap<K, V> reversed();

    /**
     * Returns the first key-value mapping in this map, or {@code null} if the map is empty.
     *
     * @implSpec
     * The implementation in this interface obtains the iterator of this map's entrySet.
     * If the iterator has an element, it returns an unmodifiable copy of that element.
     * Otherwise, it returns null.
     *
     * @return the first key-value mapping, or {@code null} if this map is empty
     */
    default ReadOnlyMap.Entry<K,V> firstEntry()
    {
        RemoveUnsupportedIterator<ReadOnlyMap.Entry<K, V>> it = entrySet().iterator();

        return it.hasNext() ? it.next() : null;
        // return it.hasNext() ? new NullableKeyValueHolder<>(it.next()) : null;
    }

    /**
     * Returns the last key-value mapping in this map, or {@code null} if the map is empty.
     *
     * @implSpec
     * The implementation in this interface obtains the iterator of the entrySet of this map's
     * reversed view.  If the iterator has an element, it returns an unmodifiable copy of
     * that element. Otherwise, it returns null.
     *
     * @return the last key-value mapping, or {@code null} if this map is empty
     */
    default ReadOnlyMap.Entry<K,V> lastEntry()
    {
        RemoveUnsupportedIterator<ReadOnlyMap.Entry<K, V>> it = reversed().entrySet().iterator();

        return it.hasNext() ? it.next() : null;
        // return it.hasNext() ? new NullableKeyValueHolder<>(it.next()) : null;
    }

    /**
     * Returns a {@code SequencedSet} view of this map's {@link #keySet keySet}.
     *
     * @implSpec
     * The implementation in this interface returns a {@code SequencedSet} instance
     * that behaves as follows. 
     * 
     * Its {@link ReadOnlySequencedSet#reversed reversed} method returns the
     * {@link #sequencedKeySet sequencedKeySet} view of the {@link #reversed reversed} view of this
     * map. Each of its other methods calls the corresponding method of the {@link #keySet keySet}
     * view of this map.
     * 
     * @return a {@code SequencedSet} view of this map's {@code keySet}
     */
    default ReadOnlySequencedSet<K> sequencedKeySet()
    {
        class ReadOnlySeqKeySet
            extends /* AbstractReadOnlyMap. */ ViewCollection<K>
            implements ReadOnlySequencedSet<K>
        {
            public java.util.Set<K> wrapToImmutableSet() { throw new Error(); }
            public java.util.Set<K> cloneToSet() { throw new Error(); }

            public ReadOnlyCollection<K> view()
            { return ReadOnlySequencedMap.this.keySet(); }

            public ReadOnlySequencedSet<K> reversed()
            { return ReadOnlySequencedMap.this.reversed().sequencedKeySet(); }

            public boolean equals(Object other)
            { return view().equals(other); }

            public int hashCode()
            { return view().hashCode(); }
        }

        return new ReadOnlySeqKeySet();
    }

    /**
     * Returns a {@code SequencedCollection} view of this map's {@link #values values} collection.
     *
     * @implSpec
     * The implementation in this interface returns a {@code SequencedCollection} instance
     * that behaves as follows. 
     * 
     * Its {@link ReadOnlySequencedCollection#reversed reversed} method returns the
     * {@link #sequencedValues sequencedValues} view of the {@link #reversed reversed} view of this
     * map. Its {@code Object.equals} and {@code Object.hashCode} methods are inherited from
     * {@code Object}. Each of its other methods calls the corresponding method of the
     * {@link #values values} view of this map.
     *
     * @return a {@code SequencedCollection} view of this map's {@code values} collection
     */
    default ReadOnlySequencedCollection<V> sequencedValues()
    {
        class ReadOnlySeqValues
            extends /* AbstractReadOnlyMap. */ ViewCollection<V>
            implements ReadOnlySequencedCollection<V>
        {
            public ReadOnlyCollection<V> view()
            { return ReadOnlySequencedMap.this.values(); }

            public ReadOnlySequencedCollection<V> reversed()
            { return ReadOnlySequencedMap.this.reversed().sequencedValues(); }
        }

        return new ReadOnlySeqValues();
    }

    /**
     * Returns a {@code SequencedSet} view of this map's {@link #entrySet entrySet}.
     * 
     * @implSpec
     * The implementation in this interface returns a {@code SequencedSet} instance that behaves as
     * follows.  Its {@link ReadOnlySequencedSet#reversed reversed} method returns the
     * {@link #sequencedEntrySet sequencedEntrySet} view of the {@link #reversed reversed} view of
     * this map.  Each of its other methods calls the corresponding method of the
     * {@link #entrySet entrySet} view of this map.
     * 
     * @return a {@code SequencedSet} view of this map's {@code entrySet}
     */
    default ReadOnlySequencedSet<ReadOnlyMap.Entry<K, V>> sequencedEntrySet()
    {
        class ReadOnlySeqEntrySet
            extends /* AbstractReadOnlyMap. */ ViewCollection<ReadOnlyMap.Entry<K, V>>
            implements ReadOnlySequencedSet<ReadOnlyMap.Entry<K, V>>
        {
            public java.util.Set<ReadOnlyMap.Entry<K, V>> wrapToImmutableSet()
            { throw new Error(); }

            public java.util.Set<ReadOnlyMap.Entry<K, V>> cloneToSet()
            { throw new Error(); }

            public ReadOnlyCollection<ReadOnlyMap.Entry<K, V>> view()
            { return ReadOnlySequencedMap.this.entrySet(); }

            public ReadOnlySequencedSet<ReadOnlyMap.Entry<K, V>> reversed()
            { return ReadOnlySequencedMap.this.reversed().sequencedEntrySet(); }

            public boolean equals(Object other)
            { return view().equals(other); }

            public int hashCode()
            { return view().hashCode(); }
        }

        return new ReadOnlySeqEntrySet();
    }

}


    // Copied from JDK
abstract class ViewCollection<E> implements ReadOnlyCollection<E>
{
    UnsupportedOperationException uoe()
    { return new UnsupportedOperationException(); }

    abstract ReadOnlyCollection<E> view();

    public boolean contains(Object o)                   { return view().contains(o); }
    public boolean containsAll(Collection<?> c)         { return view().containsAll(c); }
    public void forEach(Consumer<? super E> c)          { view().forEach(c); }
    public boolean isEmpty()                            { return view().isEmpty(); }
    public RemoveUnsupportedIterator<E> iterator()      { return view().iterator(); }
    public Stream<E> parallelStream()                   { return view().parallelStream(); }
    public int size()                                   { return view().size(); }
    public Spliterator<E> spliterator()                 { return view().spliterator(); }
    public Stream<E> stream()                           { return view().stream(); }
    public Object[] toArray()                           { return view().toArray(); }
    public <T> T[] toArray(IntFunction<T[]> generator)  { return view().toArray(generator); }
    public <T> T[] toArray(T[] a)                       { return view().toArray(a); }
    public String toString()                            { return view().toString(); }
}