View Javadoc
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 }