1e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson/* 2e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Copyright (c) 2007 Mockito contributors 3e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This program is made available under the terms of the MIT License. 4e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 5e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonpackage org.mockito.plugins; 6e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 7e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.Incubating; 8e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.invocation.MockHandler; 9e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.mock.MockCreationSettings; 10e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 11e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson/** 12e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The facility to create mocks. 13e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 14e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>By default, an internal cglib/asm/objenesis based implementation is used.</p> 15e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 16e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>{@code MockMaker} is an extension point that makes it possible to use custom dynamic proxies 17e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and avoid using the default cglib/asm/objenesis implementation. 18e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * For example, the android users can use a MockMaker that can work with Dalvik virtual machine 19e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and hence bring Mockito to android apps developers.</p> 20e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 21e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3>Using the extension point</h3> 22e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 23e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>Suppose you wrote an extension to create mocks with some <em>Awesome</em> library, in order to tell 24e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito to use it you need to put in your <strong>classpath</strong>: 25e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ol style="list-style-type: lower-alpha"> 26e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>The implementation itself, for example <code>org.awesome.mockito.AwesomeMockMaker</code> that extends the <code>MockMaker</code>.</li> 27e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>A file "<code>mockito-extensions/org.mockito.plugins.MockMaker</code>". The content of this file is 28e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * exactly a <strong>one</strong> line with the qualified name: <code>org.awesome.mockito.AwesomeMockMaker</code>.</li> 29e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ol></p> 30e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 31e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>Note that if several <code>mockito-extensions/org.mockito.plugins.MockMaker</code> files exists in the classpath 32e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito will only use the first returned by the standard {@link ClassLoader#getResource} mechanism. 33e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 34e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @see org.mockito.mock.MockCreationSettings 35e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @see org.mockito.invocation.MockHandler 36e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @since 1.9.5 37e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 38e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson@Incubating 39e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonpublic interface MockMaker { 40e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 41e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 42e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If you want to provide your own implementation of {@code MockMaker} this method should: 43e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 44e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Create a proxy object that implements {@code settings.typeToMock} and potentially also {@code settings.extraInterfaces}.</li> 45e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>You may use the information from {@code settings} to create/configure your proxy object.</li> 46e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Your proxy object should carry the {@code handler} with it. For example, if you generate byte code 47e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * to create the proxy you could generate an extra field to keep the {@code handler} with the generated object. 48e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Your implementation of {@code MockMaker} is required to provide this instance of {@code handler} when 49e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link #getHandler(Object)} is called. 50e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 51e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 52e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 53e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param settings - mock creation settings like type to mock, extra interfaces and so on. 54e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param handler See {@link org.mockito.invocation.MockHandler}. 55e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Do not</b> provide your own implementation at this time. Make sure your implementation of 56e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link #getHandler(Object)} will return this instance. 57e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param <T> Type of the mock to return, actually the <code>settings.getTypeToMock</code>. 58e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return The mock instance. 59e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @since 1.9.5 60e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 61e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson <T> T createMock( 62e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MockCreationSettings<T> settings, 63e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MockHandler handler 64e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson ); 65e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 66e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 67e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Returns the handler for the {@code mock}. <b>Do not</b> provide your own implementations at this time 68e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * because the work on the {@link MockHandler} api is not completed. 69e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Use the instance provided to you by Mockito at {@link #createMock} or {@link #resetMock}. 70e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 71e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mock The mock instance. 72e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return may return null - it means that there is no handler attached to provided object. 73e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This means the passed object is not really a Mockito mock. 74e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @since 1.9.5 75e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 76e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MockHandler getHandler(Object mock); 77e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 78e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 79e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Replaces the existing handler on {@code mock} with {@code newHandler}. 80e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 81e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>The invocation handler actually store invocations to achieve 82e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stubbing and verification. In order to reset the mock, we pass 83e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * a new instance of the invocation handler.</p> 84e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 85e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>Your implementation should make sure the {@code newHandler} is correctly associated to passed {@code mock}</p> 86e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 87e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mock The mock instance whose invocation handler is to be replaced. 88e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param newHandler The new invocation handler instance. 89e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param settings The mock settings - should you need to access some of the mock creation details. 90e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @since 1.9.5 91e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 92e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson void resetMock( 93e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson Object mock, 94e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MockHandler newHandler, 95e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MockCreationSettings settings 96e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson ); 97e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson}