001/**
002 * Copyright (C) 2011 rwoo@gmx.de
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *         http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package com.googlecode.catchexception.throwable.apis;
017
018import com.googlecode.catchexception.throwable.CatchThrowable;
019import com.googlecode.catchexception.throwable.ThrowingCallable;
020
021/**
022 * Supports <a href="http://en.wikipedia.org/wiki/Behavior_Driven_Development">BDD</a>-like approach to catch and verify
023 * throwables (<i>given/when/then</i>).
024 * <p>
025 * <code>import static com.googlecode.catchexception.throwable.apis
026 * .BDDCatchThrowable.*;
027
028 // given an empty list
029 List myList = new ArrayList();
030
031 // when we try to get the first element of the list
032 when(myList).get(1);
033
034 // then we expect an IndexOutOfBoundsThrowable
035 then(caughtThrowable())
036 .isInstanceOf(IndexOutOfBoundsThrowable.class)
037 .hasMessage("Index: 1, Size: 0")
038 .hasNoCause();
039
040 // then we expect an IndexOutOfBoundsThrowable (alternatively)
041 thenThrown(IndexOutOfBoundsThrowable.class);
042 </code>
043 *
044 * @author rwoo
045 * @author mariuszs
046 * @since 1.3.0
047 *
048 */
049public class BDDCatchThrowable {
050
051    /**
052     *
053     * @param actor
054     *            The instance that shall be proxied. Must not be <code>null</code>.
055     * @see com.googlecode.catchexception.throwable.CatchThrowable#catchThrowable(ThrowingCallable)
056     */
057    public static void when(ThrowingCallable actor) {
058        CatchThrowable.catchThrowable(actor);
059    }
060
061    /**
062     * Returns the throwable caught during the last call on the proxied object in the current thread.
063     *
064     * @return Returns the throwable caught during the last call on the proxied object in the current thread - if the
065     * call was made through a proxy that has been created via {@link #when(ThrowingCallable)}. Returns null the proxy
066     * has not caught an throwable. Returns null if the caught throwable belongs to a class that is no longer
067     * {@link ClassLoader loaded}.
068     */
069    public static Throwable caughtThrowable() {
070        return CatchThrowable.caughtThrowable();
071    }
072
073    public static <T extends Throwable> T caughtThrowable(Class<T> caughtThrowableType) {
074        return CatchThrowable.caughtThrowable(caughtThrowableType);
075    }
076    /**
077     * Throws an assertion if no throwable is thrown or if an throwable of an unexpected type is thrown.
078     * <p>
079     * EXAMPLE:
080     * <code>// given a list with nine members
081     List myList = Arrays.asList(1, 2, 3, 4, 5, 6, 7, 8, 9);
082
083     // when we try to get the 500th member of the fellowship
084     when(myList).get(500);
085
086     // then we expect an IndexOutOfBoundsThrowable
087     thenThrown(IndexOutOfBoundsThrowable.class);
088     </code>
089     *
090     * @param actualThrowableClazz
091     *            the expected type of the caught throwable.
092     */
093    @SuppressWarnings("rawtypes")
094    public static void thenThrown(Class actualThrowableClazz) {
095        CatchThrowableUtils.thenThrown(actualThrowableClazz);
096    }
097
098}