1/*
2 * Copyright 2001-2009 OFFIS, Tammo Freese
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 *     http://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 */
16package org.easymock;
17
18/**
19 * Allows setting expectations for an associated expected invocation.
20 * Implementations of this interface are returned by
21 * {@link EasyMock#expect(Object)}, and by {@link EasyMock#expectLastCall()}.
22 *
23 * @param <T> type of what should be returned by this expected call
24 */
25public interface IExpectationSetters<T> {
26
27    /**
28     * Sets a return value that will be returned for the expected invocation.
29     *
30     * @param value
31     *            the value to return.
32     * @return this object to allow method call chaining.
33     */
34    IExpectationSetters<T> andReturn(T value);
35
36    /**
37     * Sets a throwable that will be thrown for the expected invocation.
38     *
39     * @param throwable
40     *            the throwable to throw.
41     * @return this object to allow method call chaining.
42     */
43    IExpectationSetters<T> andThrow(Throwable throwable);
44
45    /**
46     * Sets an object that will be used to calculate the answer for the expected
47     * invocation (either return a value, or throw an exception).
48     *
49     * @param answer
50     *            the object used to answer the invocation.
51     * @return this object to allow method call chaining.
52     */
53    IExpectationSetters<T> andAnswer(IAnswer<? extends T> answer);
54
55    /**
56     * Sets an object implementing the same interface as the mock. The expected
57     * method call will be delegated to it with the actual arguments. The answer
58     * returned by this call will then be the answer returned by the mock
59     * (either return a value, or throw an exception).
60     *
61     * @param delegateTo
62     *            the object the call is delegated to.
63     * @return the value returned by the delegated call.
64     */
65    IExpectationSetters<T> andDelegateTo(Object delegateTo);
66
67    /**
68     * Sets a stub return value that will be returned for the expected
69     * invocation.
70     *
71     * @param value
72     *            the value to return.
73     */
74    void andStubReturn(T value);
75
76    /**
77     * Sets a stub throwable that will be thrown for the expected invocation.
78     *
79     * @param throwable
80     *            the throwable to throw.
81     */
82    void andStubThrow(Throwable throwable);
83
84    /**
85     * Sets a stub object that will be used to calculate the answer for the
86     * expected invocation (either return a value, or throw an exception).
87     *
88     * @param answer
89     *            the object used to answer the invocation.
90     */
91    void andStubAnswer(IAnswer<? extends T> answer);
92
93    /**
94     * Sets a stub object implementing the same interface as the mock. The
95     * expected method call will be delegated to it with the actual arguments.
96     * The answer returned by this call will then be the answer returned by the
97     * mock (either return a value, or throw an exception).
98     *
99     * @param delegateTo
100     *            the object the call is delegated to.
101     */
102    void andStubDelegateTo(Object delegateTo);
103
104    /**
105     * Sets stub behavior for the expected invocation (this is needed for void
106     * methods).
107     */
108    void asStub();
109
110    /**
111     * Expect the last invocation <code>count</code> times.
112     *
113     * @param count
114     *            the number of invocations expected.
115     * @return this object to allow method call chaining.
116     */
117    IExpectationSetters<T> times(int count);
118
119    /**
120     * Expect the last invocation between <code>min</code> and
121     * <code>max</code> times.
122     *
123     * @param min
124     *            the minimum number of invocations expected.
125     * @param max
126     *            the maximum number of invocations expected.
127     * @return this object to allow method call chaining.
128     */
129    IExpectationSetters<T> times(int min, int max);
130
131    /**
132     * Expect the last invocation once. This is default in EasyMock.
133     *
134     * @return this object to allow method call chaining.
135     */
136    IExpectationSetters<T> once();
137
138    /**
139     * Expect the last invocation at least once.
140     *
141     * @return this object to allow method call chaining.
142     */
143    IExpectationSetters<T> atLeastOnce();
144
145    /**
146     * Expect the last invocation any times.
147     *
148     * @return this object to allow method call chaining.
149     */
150    IExpectationSetters<T> anyTimes();
151}
152