/*
 * Copyright (c) 2007 Mockito contributors
 * This program is made available under the terms of the MIT License.
 */

package org.mockito.stubbing;

import org.mockito.Incubating;
import org.mockito.invocation.InvocationOnMock;

/**
 * Allow to validate this answer is correct for the given invocation.
 *
 * <p>
 * When tests use a shared answer implementation, it may happen the answer cannot be used
 * with some methods. Implementing this interface indicate to Mockito it needs to verify the answer is compatible
 * with the stubbed interaction.
 * </p>
 *
 * <p>
 * In the following example the answer is shared and work as expected...
 *
 * <pre class="code"><code class="java">
 * when(mock.someMethod(anyString())).then(doSomethingTricky());
 *
 * static Answer doSomethingTricky() {
 *     return new Answer() {
 *         Object answer(InvocationOnMock invocation) {
 *             // tricky stuff
 *         }
 *     });
 * }
 * </code></pre>
 * </p>
 *
 * <p>
 * ...then later there's some refactoring or some new code that want to use the answer,
 * however it is not compatible anymore. In this example the answer may throw an exception because
 * the Answer cannot work with the return type or some parameter types.
 *
 * <pre class="code"><code class="java">
 * when(mock.someMethod(anyString(), anyInt())).then(doSomethingTricky()); // fail at answer execution time
 * when(mock.incompatibleMethod(anyVararg())).then(doSomethingTricky()); // fail at answer execution time
 * </code></pre>
 * </p>
 *
 * <p>
 * Instead of having an exception raised later at answer <em>execution time</em>, one can make this answer
 * validable at <em>stub time</em> by implementing this contract.
 *
 * <pre class="code"><code class="java">
 * when(mock.incompatibleMethod(anyVararg())).then(doSomethingTricky()); // fail at answer stub time
 *
 * static Answer doSomethingTricky() {
 *     return new TrickyAnswer();
 * }
 *
 * class Tricky Answer implements Answer, ValidableAnswer {
 *     public Object answer(InvocationOnMock invocation) {
 *         // tricky stuff
 *     }
 *
 *     public void validateFor(InvocationOnMock invocation) {
 *         // perform validation for this interaction
 *     }
 * }
 * </code></pre>
 * </p>
 *
 * @since 2.3.8
 */
@Incubating
public interface ValidableAnswer {

    /**
     * Validation of the answer at <em>stub time</em> for the given invocation.
     *
     * <p>
     * This method will be called by Mockito.
     * </p>
     *
     * <p>
     * The implementation must throw an MockitoException to indicate that this answer is not valid for
     * the given invocation. If the validation succeed the implementation must simply return without throwing.
     * </p>
     *
     * @param invocation The stubbed invocation
     *
     * @since 2.3.8
     */
    void validateFor(InvocationOnMock invocation);

}