1 /*
2 * Copyright 2011-2024 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.googlecode.catchexception.throwable.apis;
17
18 import com.googlecode.catchexception.throwable.CatchThrowable;
19 import com.googlecode.catchexception.throwable.ThrowingCallable;
20
21 /**
22 * Supports <a href="http://en.wikipedia.org/wiki/Behavior_Driven_Development">BDD</a>-like approach to catch and verify
23 * throwables (<i>given/when/then</i>).
24 * <p>
25 * {@code
26 * import static com.googlecode.catchexception.throwable.apis
27 * .BDDCatchThrowable.*;
28 *
29 * // given an empty list
30 * List myList = new ArrayList();
31 *
32 * // when we try to get the first element of the list
33 * when(myList).get(1);
34 *
35 * // then we expect an IndexOutOfBoundsThrowable
36 * then(caughtThrowable())
37 * .isInstanceOf(IndexOutOfBoundsThrowable.class)
38 * .hasMessage("Index: 1, Size: 0")
39 * .hasNoCause();
40 *
41 * // then we expect an IndexOutOfBoundsThrowable (alternatively)
42 * thenThrown(IndexOutOfBoundsThrowable.class);
43 * }
44 */
45 public class BDDCatchThrowable {
46
47 /**
48 * When.
49 *
50 * @param actor
51 * The instance that shall be proxied. Must not be <code>null</code>.
52 *
53 * @see com.googlecode.catchexception.throwable.CatchThrowable#catchThrowable(ThrowingCallable)
54 */
55 public static void when(ThrowingCallable actor) {
56 CatchThrowable.catchThrowable(actor);
57 }
58
59 /**
60 * Returns the throwable caught during the last call on the proxied object in the current thread.
61 *
62 * @return Returns the throwable caught during the last call on the proxied object in the current thread - if the
63 * call was made through a proxy that has been created via {@link #when(ThrowingCallable)}. Returns null the
64 * proxy has not caught an throwable. Returns null if the caught throwable belongs to a class that is no
65 * longer {@link ClassLoader loaded}.
66 */
67 public static Throwable caughtThrowable() {
68 return CatchThrowable.caughtThrowable();
69 }
70
71 /**
72 * Caught throwable.
73 *
74 * @param <T>
75 * the generic type
76 * @param caughtThrowableType
77 * the caught throwable type
78 *
79 * @return the t
80 *
81 * @deprecated Use caghtThrowable() instead as the passed argument does nothing
82 */
83 @Deprecated(since = "2.3.0", forRemoval = true)
84 public static <T extends Throwable> T caughtThrowable(Class<T> caughtThrowableType) {
85 return CatchThrowable.caughtThrowable(caughtThrowableType);
86 }
87
88 /**
89 * Throws an assertion if no throwable is thrown or if an throwable of an unexpected type is thrown.
90 * <p>
91 * EXAMPLE: <code>// given a list with nine members
92 List myList = Arrays.asList(1, 2, 3, 4, 5, 6, 7, 8, 9);
93
94 // when we try to get the 500th member of the fellowship
95 when(myList).get(500);
96
97 // then we expect an IndexOutOfBoundsThrowable
98 thenThrown(IndexOutOfBoundsThrowable.class);
99 </code>
100 *
101 * @param actualThrowableClazz
102 * the expected type of the caught throwable.
103 */
104 @SuppressWarnings("rawtypes")
105 public static void thenThrown(Class actualThrowableClazz) {
106 CatchThrowableUtils.thenThrown(actualThrowableClazz);
107 }
108
109 }