com.fitbur.mockito.plugins.MockMaker Maven / Gradle / Ivy
/*
* Copyright (c) 2007 Mockito contributors
* This program is made available under the terms of the MIT License.
*/
package com.fitbur.mockito.plugins;
import com.fitbur.mockito.Incubating;
import com.fitbur.mockito.invocation.MockHandler;
import com.fitbur.mockito.mock.MockCreationSettings;
/**
* The facility to create mocks.
*
* By default, an internal byte-buddy/asm/objenesis based implementation is used.
*
* {@code MockMaker} is an extension point that makes it possible to use custom dynamic proxies
* and avoid using the default byte-buddy/asm/objenesis implementation.
* For example, the android users can use a MockMaker that can work with Dalvik virtual machine
* and hence bring Mockito to android apps developers.
*
* Using the extension point
*
* Suppose you wrote an extension to create mocks with some Awesome library, in order to tell
* Mockito to use it you need to put in your classpath:
*
* -
* The implementation itself, for example
org.awesome.mockito.AwesomeMockMaker that
* extends the MockMaker.
*
* -
* A file "
mockito-extensions/com.fitbur.mockito.plugins.MockMaker". The content of this file is
* exactly a one line with the qualified name:
* org.awesome.mockito.AwesomeMockMaker.
*
*
*
*
* Note that if several mockito-extensions/com.fitbur.mockito.plugins.MockMaker files exists in the classpath
* Mockito will only use the first returned by the standard {@link ClassLoader#getResource} mechanism.
*
* @see com.fitbur.mockito.mock.MockCreationSettings
* @see com.fitbur.mockito.invocation.MockHandler
* @since 1.9.5
*/
public interface MockMaker {
/**
* If you want to provide your own implementation of {@code MockMaker} this method should:
*
* - Create a proxy object that implements {@code settings.typeToMock} and potentially also {@code settings.extraInterfaces}.
* - You may use the information from {@code settings} to create/configure your proxy object.
* - Your proxy object should carry the {@code handler} with it. For example, if you generate byte code
* to create the proxy you could generate an extra field to keep the {@code handler} with the generated object.
* Your implementation of {@code MockMaker} is required to provide this instance of {@code handler} when
* {@link #getHandler(Object)} is called.
*
*
*
* @param settings Mock creation settings like type to mock, extra interfaces and so on.
* @param handler See {@link com.fitbur.mockito.invocation.MockHandler}.
* Do not provide your own implementation at this time. Make sure your implementation of
* {@link #getHandler(Object)} will return this instance.
* @param Type of the mock to return, actually the settings.getTypeToMock.
* @return The mock instance.
* @since 1.9.5
*/
T createMock(
MockCreationSettings settings,
MockHandler handler
);
/**
* Returns the handler for the {@code mock}. Do not provide your own implementations at this time
* because the work on the {@link MockHandler} api is not completed.
* Use the instance provided to you by Mockito at {@link #createMock} or {@link #resetMock}.
*
* @param mock The mock instance.
* @return The mock handler, but may return null - it means that there is no handler attached to provided object.
* This means the passed object is not really a Mockito mock.
* @since 1.9.5
*/
MockHandler getHandler(Object mock);
/**
* Replaces the existing handler on {@code mock} with {@code newHandler}.
*
* The invocation handler actually store invocations to achieve
* stubbing and verification. In order to reset the mock, we pass
* a new instance of the invocation handler.
*
* Your implementation should make sure the {@code newHandler} is correctly associated to passed {@code mock}
*
* @param mock The mock instance whose invocation handler is to be replaced.
* @param newHandler The new invocation handler instance.
* @param settings The mock settings - should you need to access some of the mock creation details.
* @since 1.9.5
*/
void resetMock(
Object mock,
MockHandler newHandler,
MockCreationSettings settings
);
/**
* Indicates if the given type can be mocked by this mockmaker.
*
* Mockmaker may have different capabilities in term of mocking, typically
* Mockito 1.x's internal mockmaker cannot mock final types. Other implementations, may
* have different limitations.
*
* @param type The type inspected for mockability.
* @return object that carries the information about mockability of given type.
* @since 2.0
*/
@Incubating
TypeMockability isTypeMockable(Class type);
/**
* Carries the mockability information
*
* @since 2.0
*/
@Incubating
static interface TypeMockability {
/**
* informs if type is mockable
*/
boolean mockable();
/**
* informs why type is not mockable
*/
String nonMockableReason();
}
}