1/*
2 * Copyright (c) 2016 Mockito contributors
3 * This program is made available under the terms of the MIT License.
4 */
5package org.mockito;
6
7import org.mockito.exceptions.misusing.RedundantListenerException;
8import org.mockito.invocation.Invocation;
9import org.mockito.invocation.InvocationFactory;
10import org.mockito.listeners.MockitoListener;
11import org.mockito.plugins.MockitoPlugins;
12
13/**
14 * Mockito framework settings and lifecycle listeners, for advanced users or for integrating with other frameworks.
15 * <p>
16 * To get <code>MockitoFramework</code> instance use {@link Mockito#framework()}.
17 * <p>
18 * For more info on listeners see {@link #addListener(MockitoListener)}.
19 *
20 * @since 2.1.0
21 */
22@Incubating
23public interface MockitoFramework {
24
25    /**
26     * Adds listener to Mockito.
27     * For a list of supported listeners, see the interfaces that extend {@link MockitoListener}.
28     * <p>
29     * Listeners can be useful for engs that extend Mockito framework.
30     * They are used in the implementation of unused stubbings warnings ({@link org.mockito.quality.MockitoHint}).
31     * <p>
32     * Make sure you remove the listener when the job is complete, see {@link #removeListener(MockitoListener)}.
33     * Currently the listeners list is thread local so you need to remove listener from the same thread otherwise
34     * remove is ineffectual.
35     * In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread.
36     * <p>
37     * If you are trying to add the listener but a listener of the same type was already added (and not removed)
38     * this method will throw {@link RedundantListenerException}.
39     * This is a safeguard to ensure users actually remove the listeners via {@link #removeListener(MockitoListener)}.
40     * We do not anticipate the use case where adding the same listener type multiple times is useful.
41     * If this safeguard is problematic, please contact us via Mockito issue tracker.
42     * <p>
43     * For usage examples, see Mockito codebase.
44     * If you have ideas and feature requests about Mockito listeners API
45     * we are very happy to hear about it via our issue tracker or mailing list.
46     *
47     * <pre class="code"><code class="java">
48     *   Mockito.framework().addListener(myListener);
49     * </code></pre>
50     *
51     * @param listener to add to Mockito
52     * @return this instance of mockito framework (fluent builder pattern)
53     * @since 2.1.0
54     */
55    @Incubating
56    MockitoFramework addListener(MockitoListener listener) throws RedundantListenerException;
57
58    /**
59     * When you add listener using {@link #addListener(MockitoListener)} make sure to remove it.
60     * Currently the listeners list is thread local so you need to remove listener from the same thread otherwise
61     * remove is ineffectual.
62     * In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread.
63     * <p>
64     * For usage examples, see Mockito codebase.
65     * If you have ideas and feature requests about Mockito listeners API
66     * we are very happy to hear about it via our issue tracker or mailing list.
67     *
68     * @param listener to remove
69     * @return this instance of mockito framework (fluent builder pattern)
70     * @since 2.1.0
71     */
72    @Incubating
73    MockitoFramework removeListener(MockitoListener listener);
74
75    /**
76     * Returns an object that has access to Mockito plugins.
77     * An example plugin is {@link org.mockito.plugins.MockMaker}.
78     * For information why and how to use this method see {@link MockitoPlugins}.
79     *
80     * @return object that gives access to mockito plugins
81     * @since 2.10.0
82     */
83    @Incubating
84    MockitoPlugins getPlugins();
85
86    /**
87     * Returns a factory that can create instances of {@link Invocation}.
88     * It is useful for framework integrations, because {@link Invocation} is {@link NotExtensible}.
89     *
90     * @return object that can construct invocations
91     * @since 2.10.0
92     */
93    @Incubating
94    InvocationFactory getInvocationFactory();
95}
96