1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache license, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the license for the specific language governing permissions and 15 * limitations under the license. 16 */ 17 package org.apache.logging.log4j.util; 18 19 /** 20 * Exposes methods to add and remove key-value pairs to and from {@code ReadOnlyStringMap}. 21 * 22 * @see ReadOnlyStringMap 23 * @since 2.7 24 */ 25 public interface StringMap extends ReadOnlyStringMap { 26 27 /** 28 * Removes all key-value pairs from this collection. 29 * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications 30 * to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or 31 * {@link #forEach(TriConsumer, Object)}. 32 * @throws UnsupportedOperationException if this collection has been {@linkplain #isFrozen() frozen}. 33 */ 34 void clear(); 35 36 /** 37 * Indicates whether some other object is "equal to" this one. 38 * 39 * @param obj 40 * the reference object with which to compare. 41 * @return {@code true} if this object is the same as the obj argument; {@code false} otherwise. 42 * @see #hashCode() 43 */ 44 @Override 45 boolean equals(final Object obj); 46 47 /** 48 * Makes this collection immutable. Attempts to modify the collection after the {@code freeze()} method was called 49 * will result in an {@code UnsupportedOperationException} being thrown. 50 */ 51 void freeze(); 52 53 /** 54 * Returns a hash code value for the object. 55 * @return a hash code value for this object. 56 */ 57 @Override 58 int hashCode(); 59 60 /** 61 * Returns {@code true} if this object has been {@linkplain #freeze() frozen}, {@code false} otherwise. 62 * @return {@code true} if this object has been {@linkplain #freeze() frozen}, {@code false} otherwise 63 */ 64 boolean isFrozen(); 65 66 /** 67 * Copies all key-value pairs from the specified {@code ReadOnlyStringMap} into this {@code StringMap}. 68 * @param source the {@code ReadOnlyStringMap} to copy key-value pairs from 69 * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications 70 * to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or 71 * {@link #forEach(TriConsumer, Object)}. 72 * @throws UnsupportedOperationException if this collection has been {@linkplain #isFrozen() frozen}. 73 */ 74 void putAll(final ReadOnlyStringMap source); 75 76 /** 77 * Puts the specified key-value pair into the collection. 78 * 79 * @param key the key to add or remove. Keys may be {@code null}. 80 * @param value the value to add. Values may be {@code null}. 81 * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications 82 * to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or 83 * {@link #forEach(TriConsumer, Object)}. 84 * @throws UnsupportedOperationException if this collection has been {@linkplain #isFrozen() frozen}. 85 */ 86 void putValue(final String key, final Object value); 87 88 /** 89 * Removes the key-value pair for the specified key from this data structure. 90 * 91 * @param key the key to remove. May be {@code null}. 92 * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications 93 * to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or 94 * {@link #forEach(TriConsumer, Object)}. 95 * @throws UnsupportedOperationException if this collection has been {@linkplain #isFrozen() frozen}. 96 */ 97 void remove(final String key); 98 }