Home | History | Annotate | Download | only in invocation 
      1 /*
      2  * Copyright (c) 2017 Mockito contributors
      3  * This program is made available under the terms of the MIT License.
      4  */
      5 package org.mockito.invocation;
      6 
      7 import org.mockito.Incubating;
      8 import org.mockito.MockitoFramework;
      9 import org.mockito.mock.MockCreationSettings;
     10 
     11 import java.io.Serializable;
     12 import java.lang.reflect.Method;
     13 import java.util.concurrent.Callable;
     14 
     15 /**
     16  * Available via {@link MockitoFramework#getInvocationFactory()}.
     17  * Provides means to create instances of {@link Invocation} objects.
     18  * Useful for framework integrations that need to programmatically simulate method calls on mock objects.
     19  * To simulate a method call on mock, one needs an instance of {@link Invocation}.
     20  * <p>
     21  * Please don't provide your own implementation of {@link Invocation} type.
     22  * Mockito team needs flexibility to add new methods to this interface if we need to.
     23  * If you integrate Mockito framework and you need an instance of {@link Invocation}, use {@link #createInvocation(Object, MockCreationSettings, Method, RealMethodBehavior, Object...)}.
     24  *
     25  * @since 2.10.0
     26  */
     27 @Incubating
     28 public interface InvocationFactory {
     29 
     30     /**
     31      * @deprecated Use {@link #createInvocation(Object, MockCreationSettings, Method, RealMethodBehavior, Object...)} instead.
     32      *
     33      * Why deprecated? We found use cases where we need to handle Throwable and ensure correct stack trace filtering
     34      * (removing Mockito internals from the stack trace). Hence the introduction of {@link RealMethodBehavior}.
     35      *
     36      * Creates instance of an {@link Invocation} object.
     37      * This method is useful for framework integrators to programmatically simulate method calls on mocks using {@link MockHandler}.
     38      * It enables advanced framework integrations.
     39      *
     40      * @param target the mock object the method is invoked on.
     41      * @param settings creation settings of the mock object.
     42      * @param method java method invoked on mock.
     43      * @param realMethod real method behavior. Needed for spying / invoking real behavior on mock objects.
     44      * @param args the java method arguments
     45      *
     46      * @return invocation instance
     47      * @since 2.10.0
     48      */
     49     @Deprecated
     50     Invocation createInvocation(Object target, MockCreationSettings settings, Method method, Callable realMethod, Object... args);
     51 
     52     /**
     53      * Behavior of the real method.
     54      *
     55      * @since 2.14.0
     56      */
     57     interface RealMethodBehavior<R> extends Serializable {
     58         R call() throws Throwable;
     59     }
     60 
     61     /**
     62      * Creates instance of an {@link Invocation} object.
     63      * This method is useful for framework integrators to programmatically simulate method calls on mocks using {@link MockHandler}.
     64      * It enables advanced framework integrations.
     65      *
     66      * @param target the mock object the method is invoked on.
     67      * @param settings creation settings of the mock object.
     68      * @param method java method invoked on mock.
     69      * @param realMethod real method behavior. Needed for spying / invoking real behavior on mock objects.
     70      * @param args the java method arguments
     71      *
     72      * @return invocation instance
     73      * @since 2.14.0
     74      */
     75     @Incubating
     76     Invocation createInvocation(Object target, MockCreationSettings settings, Method method, RealMethodBehavior realMethod, Object... args);
     77 }
     78