001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      https://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 implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections4.iterators;
018
019import java.util.Objects;
020
021import org.apache.commons.collections4.MapIterator;
022import org.apache.commons.collections4.Unmodifiable;
023
024/**
025 * Decorates a map iterator such that it cannot be modified.
026 * <p>
027 * Attempts to modify it will result in an UnsupportedOperationException.
028 * </p>
029 *
030 * @param <K> The type of keys.
031 * @param <V> The type of mapped values.
032 * @since 3.0
033 */
034public final class UnmodifiableMapIterator<K, V> implements MapIterator<K, V>, Unmodifiable {
035
036    /**
037     * Decorates the specified iterator such that it cannot be modified.
038     *
039     * @param <K>  The key type.
040     * @param <V>  The value type.
041     * @param iterator  The iterator to decorate.
042     * @return A new unmodifiable map iterator.
043     * @throws NullPointerException If the iterator is null.
044     */
045    public static <K, V> MapIterator<K, V> unmodifiableMapIterator(
046            final MapIterator<? extends K, ? extends V> iterator) {
047        Objects.requireNonNull(iterator, "iterator");
048        if (iterator instanceof Unmodifiable) {
049            @SuppressWarnings("unchecked") // safe to upcast
050            final MapIterator<K, V> tmpIterator = (MapIterator<K, V>) iterator;
051            return tmpIterator;
052        }
053        return new UnmodifiableMapIterator<>(iterator);
054    }
055
056    /** The iterator being decorated */
057    private final MapIterator<? extends K, ? extends V> iterator;
058
059    /**
060     * Constructs a new instance.
061     *
062     * @param iterator  The iterator to decorate
063     */
064    private UnmodifiableMapIterator(final MapIterator<? extends K, ? extends V> iterator) {
065        this.iterator = iterator;
066    }
067
068    @Override
069    public K getKey() {
070        return iterator.getKey();
071    }
072
073    @Override
074    public V getValue() {
075        return iterator.getValue();
076    }
077
078    @Override
079    public boolean hasNext() {
080        return iterator.hasNext();
081    }
082
083    @Override
084    public K next() {
085        return iterator.next();
086    }
087
088    /**
089     * Always throws {@link UnsupportedOperationException}.
090     *
091     * @throws UnsupportedOperationException Always thrown.
092     */
093    @Override
094    public void remove() {
095        throw new UnsupportedOperationException("remove() is not supported");
096    }
097
098    /**
099     * Always throws {@link UnsupportedOperationException}.
100     *
101     * @param value Ignored.
102     * @throws UnsupportedOperationException Always thrown.
103     */
104    @Override
105    public V setValue(final V value) {
106        throw new UnsupportedOperationException("setValue() is not supported");
107    }
108
109}