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 *      http://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.logging.log4j.util;
018
019/**
020 * Exposes methods to add and remove key-value pairs to and from {@code ReadOnlyStringMap}.
021 *
022 * @see ReadOnlyStringMap
023 * @since 2.7
024 */
025public interface StringMap extends ReadOnlyStringMap {
026
027    /**
028     * Removes all key-value pairs from this collection.
029     * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications
030     *          to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or
031     *          {@link #forEach(TriConsumer, Object)}.
032     * @throws UnsupportedOperationException if this collection has been {@linkplain #isFrozen() frozen}.
033     */
034    void clear();
035
036    /**
037     * Indicates whether some other object is "equal to" this one.
038     *
039     * @param obj
040     *            the reference object with which to compare.
041     * @return {@code true} if this object is the same as the obj argument; {@code false} otherwise.
042     * @see #hashCode()
043     */
044    @Override
045    boolean equals(final Object obj);
046
047    /**
048     * Makes this collection immutable. Attempts to modify the collection after the {@code freeze()} method was called
049     * will result in an {@code UnsupportedOperationException} being thrown.
050     */
051    void freeze();
052
053    /**
054     * Returns a hash code value for the object.
055     * @return a hash code value for this object.
056     */
057    @Override
058    int hashCode();
059
060    /**
061     * Returns {@code true} if this object has been {@linkplain #freeze() frozen}, {@code false} otherwise.
062     * @return  {@code true} if this object has been {@linkplain #freeze() frozen}, {@code false} otherwise
063     */
064    boolean isFrozen();
065
066    /**
067     * Copies all key-value pairs from the specified {@code ReadOnlyStringMap} into this {@code StringMap}.
068     * @param source the {@code ReadOnlyStringMap} to copy key-value pairs from
069     * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications
070     *          to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or
071     *          {@link #forEach(TriConsumer, Object)}.
072     * @throws UnsupportedOperationException if this collection has been {@linkplain #isFrozen() frozen}.
073     */
074    void putAll(final ReadOnlyStringMap source);
075
076    /**
077     * Puts the specified key-value pair into the collection.
078     *
079     * @param key the key to add or remove. Keys may be {@code null}.
080     * @param value the value to add. Values may be {@code null}.
081     * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications
082     *          to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or
083     *          {@link #forEach(TriConsumer, Object)}.
084     * @throws UnsupportedOperationException if this collection has been {@linkplain #isFrozen() frozen}.
085     */
086    void putValue(final String key, final Object value);
087
088    /**
089     * Removes the key-value pair for the specified key from this data structure.
090     *
091     * @param key the key to remove. May be {@code null}.
092     * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications
093     *          to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or
094     *          {@link #forEach(TriConsumer, Object)}.
095     * @throws UnsupportedOperationException if this collection has been {@linkplain #isFrozen() frozen}.
096     */
097    void remove(final String key);
098}