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.juneau.bct.assertions;
018
019import static java.util.Arrays.*;
020import static java.util.Collections.*;
021import static java.util.stream.Collectors.*;
022
023import java.io.*;
024import java.util.*;
025import java.util.function.*;
026
027import org.apache.juneau.commons.function.*;
028import org.apache.juneau.commons.utils.*;
029
030/**
031 * Used for fluent assertion calls against maps.
032 *
033 * <h2 class='section'>Test Methods:</h2>
034 * <ul class='javatree'>
035 *    <li class='jc'>{@link FluentMapAssertion}
036 *    <ul class='javatreec'>
037 *       <li class='jm'>{@link FluentMapAssertion#isEmpty() isEmpty()}
038 *       <li class='jm'>{@link FluentMapAssertion#isNotEmpty() isNotEmpty()}
039 *       <li class='jm'>{@link FluentMapAssertion#isContainsKey(String) isContainsKey(String)}
040 *       <li class='jm'>{@link FluentMapAssertion#isNotContainsKey(String) isNotContainsKey(String)}
041 *       <li class='jm'>{@link FluentMapAssertion#isSize(int) isSize(int)}
042 *    </ul>
043 *    <li class='jc'>{@link FluentObjectAssertion}
044 *    <ul class='javatreec'>
045 *       <li class='jm'>{@link FluentObjectAssertion#isExists() isExists()}
046 *       <li class='jm'>{@link FluentObjectAssertion#is(Object) is(Object)}
047 *       <li class='jm'>{@link FluentObjectAssertion#is(Predicate) is(Predicate)}
048 *       <li class='jm'>{@link FluentObjectAssertion#isNot(Object) isNot(Object)}
049 *       <li class='jm'>{@link FluentObjectAssertion#isAny(Object...) isAny(Object...)}
050 *       <li class='jm'>{@link FluentObjectAssertion#isNotAny(Object...) isNotAny(Object...)}
051 *       <li class='jm'>{@link FluentObjectAssertion#isNull() isNull()}
052 *       <li class='jm'>{@link FluentObjectAssertion#isNotNull() isNotNull()}
053 *       <li class='jm'>{@link FluentObjectAssertion#isString(String) isString(String)}
054 *       <li class='jm'>{@link FluentObjectAssertion#isSame(Object) isSame(Object)}
055 *       <li class='jm'>{@link FluentObjectAssertion#isType(Class) isType(Class)}
056 *       <li class='jm'>{@link FluentObjectAssertion#isExactType(Class) isExactType(Class)}
057 *    </ul>
058 * </ul>
059 *
060 * <h2 class='section'>Transform Methods:</h2>
061 * <ul class='javatree'>
062 *    <li class='jc'>{@link FluentMapAssertion}
063 *    <ul class='javatreec'>
064 *       <li class='jm'>{@link FluentMapAssertion#asValue(Object) asValue(Object)}
065 *       <li class='jm'>{@link FluentMapAssertion#asValues(Object...) asValues(Object...)}
066 *       <li class='jm'>{@link FluentMapAssertion#asValueMap(Object...) asValueMap(Object...)}
067 *       <li class='jm'>{@link FluentMapAssertion#asSize() asSize()}
068 *    </ul>
069 *    <li class='jc'>{@link FluentObjectAssertion}
070 *    <ul class='javatreec'>
071 *       <li class='jm'>{@link FluentObjectAssertion#asString() asString()}
072 *       <li class='jm'>{@link FluentObjectAssertion#asString(ThrowingFunction) asString(ThrowingFunction)}
073 *       <li class='jm'>{@link FluentObjectAssertion#asTransformed(UnaryOperator) asTransformed(UnaryOperator)}
074 *       <li class='jm'>{@link FluentObjectAssertion#asAny() asAny()}
075 * </ul>
076 * </ul>
077 *
078 * <h2 class='section'>Configuration Methods:</h2>
079 * <ul class='javatree'>
080 *    <li class='jc'>{@link Assertion}
081 *    <ul class='javatreec'>
082 *       <li class='jm'>{@link Assertion#setMsg(String, Object...) setMsg(String, Object...)}
083 *       <li class='jm'>{@link Assertion#setOut(PrintStream) setOut(PrintStream)}
084 *       <li class='jm'>{@link Assertion#setSilent() setSilent()}
085 *       <li class='jm'>{@link Assertion#setStdOut() setStdOut()}
086 *       <li class='jm'>{@link Assertion#setThrowable(Class) setThrowable(Class)}
087 *    </ul>
088 * </ul>
089 *
090 * <h2 class='section'>See Also:</h2><ul>
091 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauEcosystemOverview">Juneau Ecosystem</a>
092 * </ul>
093 *
094 * @param <K> The key type.
095 * @param <V> The value type.
096 * @param <R> The return type.
097 */
098@SuppressWarnings({
099   "java:S115", // Constants use UPPER_snakeCase convention (e.g., MSG_mapWasNotEmpty)
100   "unchecked" // Generic varargs parameters (K...keys) in the key-based assertion methods create generic arrays at call sites
101})
102public class FluentMapAssertion<K,V,R> extends FluentObjectAssertion<Map<K,V>,R> {
103
104   private static final Messages MESSAGES = Messages.of(FluentMapAssertion.class, "Messages");
105   private static final String MSG_mapWasNotEmpty = MESSAGES.getString("mapWasNotEmpty");
106   private static final String MSG_mapDidNotContainExpectedKey = MESSAGES.getString("mapDidNotContainExpectedKey");
107   private static final String MSG_mapContainedUnexpectedKey = MESSAGES.getString("mapContainedUnexpectedKey");
108   private static final String MSG_mapWasEmpty = MESSAGES.getString("mapWasEmpty");
109   private static final String MSG_mapDidNotHaveTheExpectedSize = MESSAGES.getString("mapDidNotHaveTheExpectedSize");
110
111   /**
112    * Chained constructor.
113    *
114    * <p>
115    * Used when transforming one assertion into another so that the assertion config can be used by the new assertion.
116    *
117    * @param creator
118    *    The assertion that created this assertion.
119    *    <br>Should be <jk>null</jk> if this is the top-level assertion.
120    * @param value
121    *    The object being tested.
122    *    <br>Can be <jk>null</jk> (assertions such as {@code isNull()} then operate on the absence of a value).
123    * @param returns
124    *    The object to return after a test method is called.
125    *    <br>If <jk>null</jk>, the test method returns this object allowing multiple test method calls to be
126    * used on the same assertion.
127    */
128   public FluentMapAssertion(Assertion creator, Map<K,V> value, R returns) {
129      super(creator, value, returns);
130   }
131
132   /**
133    * Constructor.
134    *
135    * @param value
136    *    The object being tested.
137    *    <br>Can be <jk>null</jk> (assertions such as {@code isNull()} then operate on the absence of a value).
138    * @param returns
139    *    The object to return after a test method is called.
140    *    <br>If <jk>null</jk>, the test method returns this object allowing multiple test method calls to be
141    * used on the same assertion.
142    */
143   public FluentMapAssertion(Map<K,V> value, R returns) {
144      this(null, value, returns);
145   }
146
147   /**
148    * Returns an integer assertion on the size of this map.
149    *
150    * <p>
151    * If the map is <jk>null</jk>, the returned assertion is a null assertion
152    * (meaning {@link FluentIntegerAssertion#isExists()} returns <jk>false</jk>).
153    *
154    * @return A new assertion.
155    */
156   public FluentIntegerAssertion<R> asSize() {
157      return new FluentIntegerAssertion<>(this, valueIsNull() ? null : value().size(), returns());
158   }
159
160   @Override /* Overridden from FluentObjectAssertion */
161   public FluentMapAssertion<K,V,R> asTransformed(UnaryOperator<Map<K,V>> function) {
162      return new FluentMapAssertion<>(this, function.apply(orElse(null)), returns());
163   }
164
165   /**
166    * Returns an object assertion on the value specified at the specified key.
167    *
168    * <p>
169    * If the map is <jk>null</jk> or the map doesn't contain the specified key, the returned assertion is a null assertion
170    * (meaning {@link FluentAnyAssertion#isExists()} returns <jk>false</jk>).
171    *
172    * @param key The key of the item to retrieve from the map.
173    * @return A new assertion.
174    */
175   public FluentAnyAssertion<V,R> asValue(K key) {
176      return new FluentAnyAssertion<>(this, get(key), returns());
177   }
178
179   /**
180    * Extracts a subset of this map.
181    *
182    * @param keys The entries to extract.
183    * @return This object.
184    */
185   public FluentMapAssertion<K,V,R> asValueMap(K...keys) {
186      if (valueIsNull())
187         return new FluentMapAssertion<>(this, null, returns());
188      var m1 = value();
189      Map<K,V> m2 = CollectionUtils.map();
190      for (var k : keys)
191         m2.put(k, m1.get(k));
192      return new FluentMapAssertion<>(this, m2, returns());
193   }
194
195   /**
196    * Returns a {@link FluentListAssertion} of the values of the specified keys.
197    *
198    * If the map is <jk>null</jk>, the returned assertion is a null assertion
199    * (meaning {@link FluentObjectAssertion#isExists()} returns <jk>false</jk>).
200    *
201    * @param keys The keys of the values to retrieve from the map.
202    * @return A new assertion.
203    */
204   public FluentListAssertion<Object,R> asValues(K...keys) {
205      return new FluentListAssertion<>(this, valueIsNull() ? null : stream(keys).map(this::get).collect(toList()), returns());
206   }
207
208   /**
209    * Asserts that the map contains the expected key.
210    *
211    * @param name The key name to check for.
212    * @return The fluent return object.
213    * @throws AssertionError If assertion failed or value was <jk>null</jk>.
214    */
215   public R isContainsKey(String name) throws AssertionError {
216      if (value().containsKey(name))
217         return returns();
218      throw error(MSG_mapDidNotContainExpectedKey, name, value());
219   }
220
221   /**
222    * Asserts that the map exists and is empty.
223    *
224    * @return The fluent return object.
225    * @throws AssertionError If assertion failed or value was <jk>null</jk>.
226    */
227   public R isEmpty() throws AssertionError {
228      if (! value().isEmpty())
229         throw error(MSG_mapWasNotEmpty);
230      return returns();
231   }
232
233   /**
234    * Asserts that the map contains the expected key.
235    *
236    * @param name The key name to check for.
237    * @return The fluent return object.
238    * @throws AssertionError If assertion failed or value was <jk>null</jk>.
239    */
240   public R isNotContainsKey(String name) throws AssertionError {
241      if (! value().containsKey(name))
242         return returns();
243      throw error(MSG_mapContainedUnexpectedKey, name, value());
244   }
245
246   /**
247    * Asserts that the map exists and is not empty.
248    *
249    * @return The fluent return object.
250    * @throws AssertionError If assertion failed or value was <jk>null</jk>.
251    */
252   public R isNotEmpty() throws AssertionError {
253      if (value().isEmpty())
254         throw error(MSG_mapWasEmpty);
255      return returns();
256   }
257
258   /**
259    * Asserts that the map exists and is the specified size.
260    *
261    * @param size The expected size.
262    * @return The fluent return object.
263    * @throws AssertionError If assertion failed or value was <jk>null</jk>.
264    */
265   public R isSize(int size) throws AssertionError {
266      if (size2() != size)
267         throw error(MSG_mapDidNotHaveTheExpectedSize, size, size2());
268      return returns();
269   }
270
271   @Override /* Overridden from Assertion */
272   public FluentMapAssertion<K,V,R> setMsg(String msg, Object...args) {
273      super.setMsg(msg, args);
274      return this;
275   }
276
277   @Override /* Overridden from Assertion */
278   public FluentMapAssertion<K,V,R> setOut(PrintStream value) {
279      super.setOut(value);
280      return this;
281   }
282
283   @Override /* Overridden from Assertion */
284   public FluentMapAssertion<K,V,R> setSilent() {
285      super.setSilent();
286      return this;
287   }
288
289   @Override /* Overridden from Assertion */
290   public FluentMapAssertion<K,V,R> setStdOut() {
291      super.setStdOut();
292      return this;
293   }
294
295   @Override /* Overridden from Assertion */
296   public FluentMapAssertion<K,V,R> setThrowable(Class<? extends RuntimeException> value) {
297      super.setThrowable(value);
298      return this;
299   }
300
301   private V get(K key) {
302      return orElse(emptyMap()).get(key);
303   }
304
305   private int size2() {
306      return value().size();
307   }
308}