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 import java.io.Serializable;
20 import java.util.Map;
21
22 /**
23 * A read-only collection of String keys mapped to values of arbitrary type.
24 *
25 * @since 2.7
26 */
27 public interface ReadOnlyStringMap extends Serializable {
28 /**
29 * Returns a non-{@code null} mutable {@code Map<String, String>} containing a snapshot of this data structure.
30 *
31 * @return a mutable copy of this data structure in {@code Map<String, String>} form
32 */
33 Map<String, String> toMap();
34
35 /**
36 * Returns {@code true} if this data structure contains the specified key, {@code false} otherwise.
37 *
38 * @param key the key whose presence to check. May be {@code null}.
39 * @return {@code true} if this data structure contains the specified key, {@code false} otherwise
40 */
41 boolean containsKey(String key);
42
43 /**
44 * Performs the given action for each key-value pair in this data structure
45 * until all entries have been processed or the action throws an exception.
46 * <p>
47 * Some implementations may not support structural modifications (adding new elements or removing elements) while
48 * iterating over the contents. In such implementations, attempts to add or remove elements from the
49 * {@code BiConsumer}'s {@link BiConsumer#accept(Object, Object)} accept} method may cause a
50 * {@code ConcurrentModificationException} to be thrown.
51 * </p>
52 *
53 * @param action The action to be performed for each key-value pair in this collection
54 * @param <V> type of the value
55 * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications
56 * to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or
57 * {@link #forEach(TriConsumer, Object)}.
58 */
59 <V> void forEach(final BiConsumer<String, ? super V> action);
60
61 /**
62 * Performs the given action for each key-value pair in this data structure
63 * until all entries have been processed or the action throws an exception.
64 * <p>
65 * The third parameter lets callers pass in a stateful object to be modified with the key-value pairs,
66 * so the TriConsumer implementation itself can be stateless and potentially reusable.
67 * </p>
68 * <p>
69 * Some implementations may not support structural modifications (adding new elements or removing elements) while
70 * iterating over the contents. In such implementations, attempts to add or remove elements from the
71 * {@code TriConsumer}'s {@link TriConsumer#accept(Object, Object, Object) accept} method may cause a
72 * {@code ConcurrentModificationException} to be thrown.
73 * </p>
74 *
75 * @param action The action to be performed for each key-value pair in this collection
76 * @param state the object to be passed as the third parameter to each invocation on the specified
77 * triconsumer
78 * @param <V> type of the value
79 * @param <S> type of the third parameter
80 * @throws java.util.ConcurrentModificationException some implementations may not support structural modifications
81 * to this data structure while iterating over the contents with {@link #forEach(BiConsumer)} or
82 * {@link #forEach(TriConsumer, Object)}.
83 */
84 <V, S> void forEach(final TriConsumer<String, ? super V, S> action, final S state);
85
86 /**
87 * Returns the value for the specified key, or {@code null} if the specified key does not exist in this collection.
88 *
89 * @param key the key whose value to return
90 * @return the value for the specified key or {@code null}
91 */
92 <V> V getValue(final String key);
93
94 /**
95 * Returns {@code true} if this collection is empty (size is zero), {@code false} otherwise.
96 * @return {@code true} if this collection is empty (size is zero)
97 */
98 boolean isEmpty();
99
100 /**
101 * Returns the number of key-value pairs in this collection.
102 *
103 * @return the number of key-value pairs in this collection
104 */
105 int size();
106 }