Home | History | Annotate | Download | only in mockito 
      1 /*
      2  * Copyright (c) 2016 Mockito contributors
      3  * This program is made available under the terms of the MIT License.
      4  */
      5 package org.mockito;
      6 
      7 import org.mockito.exceptions.misusing.RedundantListenerException;
      8 import org.mockito.listeners.MockitoListener;
      9 
     10 /**
     11  * Mockito framework settings and lifecycle listeners, for advanced users or for integrating with other frameworks.
     12  * <p>
     13  * To get <code>MockitoFramework</code> instance use {@link Mockito#framework()}.
     14  * <p>
     15  * For more info on listeners see {@link #addListener(MockitoListener)}.
     16  *
     17  * @since 2.1.0
     18  */
     19 @Incubating
     20 public interface MockitoFramework {
     21 
     22     /**
     23      * Adds listener to Mockito.
     24      * For a list of supported listeners, see the interfaces that extend {@link MockitoListener}.
     25      * <p>
     26      * Listeners can be useful for engs that extend Mockito framework.
     27      * They are used in the implementation of unused stubbings warnings ({@link org.mockito.quality.MockitoHint}).
     28      * <p>
     29      * Make sure you remove the listener when the job is complete, see {@link #removeListener(MockitoListener)}.
     30      * Currently the listeners list is thread local so you need to remove listener from the same thread otherwise
     31      * remove is ineffectual.
     32      * In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread.
     33      * <p>
     34      * If you are trying to add the listener but a listener of the same type was already added (and not removed)
     35      * this method will throw {@link RedundantListenerException}.
     36      * This is a safeguard to ensure users actually remove the listeners via {@link #removeListener(MockitoListener)}.
     37      * We do not anticipate the use case where adding the same listener type multiple times is useful.
     38      * If this safeguard is problematic, please contact us via Mockito issue tracker.
     39      * <p>
     40      * For usage examples, see Mockito codebase.
     41      * If you have ideas and feature requests about Mockito listeners API
     42      * we are very happy to hear about it via our issue tracker or mailing list.
     43      *
     44      * <pre class="code"><code class="java">
     45      *   Mockito.framework().addListener(myListener);
     46      * </code></pre>
     47      *
     48      * @param listener to add to Mockito
     49      * @since 2.1.0
     50      */
     51     @Incubating
     52     MockitoFramework addListener(MockitoListener listener) throws RedundantListenerException;
     53 
     54     /**
     55      * When you add listener using {@link #addListener(MockitoListener)} make sure to remove it.
     56      * Currently the listeners list is thread local so you need to remove listener from the same thread otherwise
     57      * remove is ineffectual.
     58      * In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread.
     59      * <p>
     60      * For usage examples, see Mockito codebase.
     61      * If you have ideas and feature requests about Mockito listeners API
     62      * we are very happy to hear about it via our issue tracker or mailing list.
     63      *
     64      * @param listener to remove
     65      * @since 2.1.0
     66      */
     67     @Incubating
     68     MockitoFramework removeListener(MockitoListener listener);
     69 }
     70