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