1/*
2 * Copyright (c) 2007 Mockito contributors
3 * This program is made available under the terms of the MIT License.
4 */
5package org.mockito.stubbing;
6
7import org.mockito.Mockito;
8
9/**
10 * Stubs void method with an exception. E.g:
11 *
12 * <pre class="code"><code class="java">
13 * stubVoid(mock).toThrow(new RuntimeException()).on().someMethod();
14 *
15 * //you can stub with different behavior for consecutive method calls.
16 * //Last stubbing (e.g: toReturn()) determines the behavior for further consecutive calls.
17 * stubVoid(mock)
18 *  .toThrow(new RuntimeException())
19 *  .toReturn()
20 *  .on().someMethod();
21 * </code></pre>
22 *
23 * See examples in javadoc for {@link Mockito#stubVoid}
24 */
25public interface VoidMethodStubbable<T> {
26
27    /**
28     * Stubs void method with an exception. E.g:
29     *
30     * <pre class="code"><code class="java">
31     * stubVoid(mock).toThrow(new RuntimeException()).on().someMethod();
32     * </code></pre>
33     *
34     * If throwable is a checked exception then it has to
35     * match one of the checked exceptions of method signature.
36     *
37     * See examples in javadoc for {@link Mockito#stubVoid}
38     *
39     * @param throwable to be thrown on method invocation
40     *
41     * @return VoidMethodStubbable - typically to choose void method and finish stubbing
42     */
43    VoidMethodStubbable<T> toThrow(Throwable throwable);
44
45    /**
46     * Stubs void method to 'just return' (e.g. to <b>not</b> to throw any exception)
47     * <p>
48     * <b>Only use this method if you're stubbing consecutive calls.</b>
49     * <p>
50     * For example:
51     * <pre class="code"><code class="java">
52     * stubVoid(mock)
53     *   .toReturn()
54     *   .toThrow(new RuntimeException())
55     *   .on().foo(10);
56     * </code></pre>
57     * <ul>
58     * <li>first time foo(10) is called the mock will 'just return' (e.g. don't throw any exception)</li>
59     * <li>second time foo(10) is called the mock will throw RuntimeException</li>
60     * <li>every consecutive time foo(10) is called the mock will throw RuntimeException</li>
61     * </ul>
62     * <p>
63     * See examples in javadoc for {@link Mockito#stubVoid}
64     *
65     * @return VoidMethodStubbable - typically to choose void method and finish stubbing
66     */
67    VoidMethodStubbable<T> toReturn();
68
69    /**
70     * Stubs a void method with generic {@link Answer}
71     * <p>
72     * For Example:
73     * <pre class="code"><code class="java">
74     * stubVoid(mock)
75     *   .toAnswer(new Answer() {
76     *                 public Object answer(InvocationOnMOck invocation) {
77     *                     Visitor v = (Visitor) invocation.getArguments()[0];
78     *                     v.visitMock(invocation.getMock());
79     *
80     *                     return null;
81     *                 }
82     *             })
83     *    .on().accept(any());
84     * </code></pre>
85     *
86     * @param answer the custom answer to execute.
87     *
88     * @return VoidMethodStubbable - typically to choose void method and finish stubbing
89     */
90    VoidMethodStubbable<T> toAnswer(Answer<?> answer);
91
92    /**
93     * Choose void method for stubbing. E.g:
94     *
95     * <pre class="code"><code class="java">
96     * stubVoid(mock).toThrow(new RuntimeException()).on().someMethod("some arg");
97     * </code></pre>
98     *
99     * See examples in javadoc for {@link Mockito#stubVoid}
100     *
101     * @return mock object itself
102     */
103    T on();
104}