1/*
2 * Copyright (c) 2007 Mockito contributors
3 * This program is made available under the terms of the MIT License.
4 */
5package org.mockito.plugins;
6
7import org.mockito.Incubating;
8import org.mockito.invocation.MockHandler;
9import 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 */
45public 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     */
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     */
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     */
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
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         */
128        boolean mockable();
129
130        /**
131         * informs why type is not mockable
132         */
133        String nonMockableReason();
134    }
135}
136