1 /* 2 * Copyright (c) 2007 Mockito contributors 3 * This program is made available under the terms of the MIT License. 4 */ 5 package org.mockito.plugins; 6 7 import org.mockito.Incubating; 8 import org.mockito.invocation.MockHandler; 9 import org.mockito.mock.MockCreationSettings; 10 11 /** 12 * The facility to create mocks. 13 * 14 * <p>By default, an internal byte-buddy/asm/objenesis based implementation is used.</p> 15 * 16 * <p>{@code MockMaker} is an extension point that makes it possible to use custom dynamic proxies 17 * and avoid using the default byte-buddy/asm/objenesis implementation. 18 * For example, the android users can use a MockMaker that can work with Dalvik virtual machine 19 * and hence bring Mockito to android apps developers.</p> 20 * 21 * <h3>Using the extension point</h3> 22 * 23 * <p>Suppose you wrote an extension to create mocks with some <em>Awesome</em> library, in order to tell 24 * Mockito to use it you need to put in your <strong>classpath</strong>: 25 * <ol style="list-style-type: lower-alpha"> 26 * <li> 27 * The implementation itself, for example <code>org.awesome.mockito.AwesomeMockMaker</code> that 28 * extends the <code>MockMaker</code>. 29 * </li> 30 * <li> 31 * A file "<code>mockito-extensions/org.mockito.plugins.MockMaker</code>". The content of this file is 32 * exactly a <strong>one</strong> line with the qualified name: 33 * <code>org.awesome.mockito.AwesomeMockMaker</code>. 34 * </li> 35 * </ol> 36 * </p> 37 * 38 * <p>Note that if several <code>mockito-extensions/org.mockito.plugins.MockMaker</code> files exists in the classpath 39 * Mockito will only use the first returned by the standard {@link ClassLoader#getResource} mechanism. 40 * 41 * @see org.mockito.mock.MockCreationSettings 42 * @see org.mockito.invocation.MockHandler 43 * @since 1.9.5 44 */ 45 public interface MockMaker { 46 47 /** 48 * If you want to provide your own implementation of {@code MockMaker} this method should: 49 * <ul> 50 * <li>Create a proxy object that implements {@code settings.typeToMock} and potentially also {@code settings.extraInterfaces}.</li> 51 * <li>You may use the information from {@code settings} to create/configure your proxy object.</li> 52 * <li>Your proxy object should carry the {@code handler} with it. For example, if you generate byte code 53 * to create the proxy you could generate an extra field to keep the {@code handler} with the generated object. 54 * Your implementation of {@code MockMaker} is required to provide this instance of {@code handler} when 55 * {@link #getHandler(Object)} is called. 56 * </li> 57 * </ul> 58 * 59 * @param settings Mock creation settings like type to mock, extra interfaces and so on. 60 * @param handler See {@link org.mockito.invocation.MockHandler}. 61 * <b>Do not</b> provide your own implementation at this time. Make sure your implementation of 62 * {@link #getHandler(Object)} will return this instance. 63 * @param <T> Type of the mock to return, actually the <code>settings.getTypeToMock</code>. 64 * @return The mock instance. 65 * @since 1.9.5 66 */ createMock( MockCreationSettings<T> settings, MockHandler handler )67 <T> T createMock( 68 MockCreationSettings<T> settings, 69 MockHandler handler 70 ); 71 72 /** 73 * Returns the handler for the {@code mock}. <b>Do not</b> provide your own implementations at this time 74 * because the work on the {@link MockHandler} api is not completed. 75 * Use the instance provided to you by Mockito at {@link #createMock} or {@link #resetMock}. 76 * 77 * @param mock The mock instance. 78 * @return The mock handler, but may return null - it means that there is no handler attached to provided object. 79 * This means the passed object is not really a Mockito mock. 80 * @since 1.9.5 81 */ getHandler(Object mock)82 MockHandler getHandler(Object mock); 83 84 /** 85 * Replaces the existing handler on {@code mock} with {@code newHandler}. 86 * 87 * <p>The invocation handler actually store invocations to achieve 88 * stubbing and verification. In order to reset the mock, we pass 89 * a new instance of the invocation handler.</p> 90 * 91 * <p>Your implementation should make sure the {@code newHandler} is correctly associated to passed {@code mock}</p> 92 * 93 * @param mock The mock instance whose invocation handler is to be replaced. 94 * @param newHandler The new invocation handler instance. 95 * @param settings The mock settings - should you need to access some of the mock creation details. 96 * @since 1.9.5 97 */ resetMock( Object mock, MockHandler newHandler, MockCreationSettings settings )98 void resetMock( 99 Object mock, 100 MockHandler newHandler, 101 MockCreationSettings settings 102 ); 103 104 /** 105 * Indicates if the given type can be mocked by this mockmaker. 106 * 107 * <p>Mockmaker may have different capabilities in term of mocking, typically 108 * Mockito 1.x's internal mockmaker cannot mock final types. Other implementations, may 109 * have different limitations.</p> 110 * 111 * @param type The type inspected for mockability. 112 * @return object that carries the information about mockability of given type. 113 * @since 2.1.0 114 */ 115 @Incubating isTypeMockable(Class<?> type)116 TypeMockability isTypeMockable(Class<?> type); 117 118 /** 119 * Carries the mockability information 120 * 121 * @since 2.1.0 122 */ 123 @Incubating 124 interface TypeMockability { 125 /** 126 * informs if type is mockable 127 */ mockable()128 boolean mockable(); 129 130 /** 131 * informs why type is not mockable 132 */ nonMockableReason()133 String nonMockableReason(); 134 } 135 } 136