1 /*
2 * Copyright (c) 2006 JMockit developers
3 * This file is subject to the terms of the MIT license (see LICENSE.txt).
4 */
5 package mockit;
6
7 import static java.lang.annotation.ElementType.METHOD;
8 import static java.lang.annotation.RetentionPolicy.RUNTIME;
9
10 import java.lang.annotation.Retention;
11 import java.lang.annotation.Target;
12
13 /**
14 * Used inside a {@linkplain MockUp fake} class to indicate a <em>fake method</em> whose implementation will temporarily
15 * replace the implementation of one or more matching "real" methods or constructors (these are the "faked"
16 * methods/constructors).
17 * <p>
18 * The fake method must have the same name and the same parameters in order to match a real method, except for an
19 * <em>optional</em> first parameter of type {@link Invocation}; if this extra parameter is present, the remaining ones
20 * (if any) must match the parameters in the real method. Alternatively, a single fake method having <em>only</em> the
21 * <code>Invocation</code> parameter will match all real methods of the same name, regardless of their parameters. The
22 * fake method must also have the same return type as the matching real method.
23 * <p>
24 * Method modifiers (<code>public</code>, <code>final</code>, <code>static</code>, etc.) between fake and faked methods
25 * <em>don't</em> have to be the same. It's perfectly fine to have a non-<code>static</code> fake method for a
26 * <code>static</code> faked method (or vice-versa), for example. Checked exceptions in the <code>throws</code> clause
27 * (if any) can also differ between the two matching methods.
28 * <p>
29 * A fake <em>method</em> can also target a <em>constructor</em>, in which case the previous considerations still apply,
30 * except for the name of the fake method which must be "<strong><code>$init</code></strong>".
31 * <p>
32 * Another special fake method, "<strong><code>void $clinit()</code></strong>", will target the <code>static</code>
33 * initializers of the faked class, if present in the fake class.
34 * <p>
35 * Yet another special fake method is "<strong><code>Object $advice(Invocation)</code></strong>", which if defined will
36 * match <em>every</em> method in the target class hierarchy.
37 *
38 * @see <a href="http://jmockit.github.io/tutorial/Faking.html#fakes" target="tutorial">Tutorial</a>
39 */
40 @Retention(RUNTIME)
41 @Target(METHOD)
42 public @interface Mock {
43
44 /**
45 * Number of expected invocations of the mock method. If 0 (zero), no invocations will be expected. A negative value
46 * (the default) means there is no expectation on the number of invocations; that is, the mock can be called any
47 * number of times or not at all during any test which uses it.
48 * <p>
49 * A non-negative value is equivalent to setting {@link #minInvocations minInvocations} and {@link #maxInvocations
50 * maxInvocations} to that same value.
51 *
52 * @return Number of expected invocations of the mock method
53 */
54 int invocations() default -1;
55
56 /**
57 * Minimum number of expected invocations of the mock method, starting from 0 (zero, which is the default).
58 *
59 * @return Minimum number of expected invocations of the mock method
60 *
61 * @see #invocations
62 * @see #maxInvocations
63 */
64 int minInvocations() default 0;
65
66 /**
67 * Maximum number of expected invocations of the mock method, if positive. If zero the mock is not expected to be
68 * called at all. A negative value (the default) means there is no expectation on the maximum number of invocations.
69 *
70 * @return Maximum number of expected invocations of the mock method
71 *
72 * @see #invocations
73 * @see #minInvocations
74 */
75 int maxInvocations() default -1;
76 }