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