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