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 createInvocation(Object target, MockCreationSettings settings, Method method, Callable realMethod, Object... args)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 { call()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 createInvocation(Object target, MockCreationSettings settings, Method method, RealMethodBehavior realMethod, Object... args)76 Invocation createInvocation(Object target, MockCreationSettings settings, Method method, RealMethodBehavior realMethod, Object... args); 77 } 78