Add classes and methods to aid in the upgrade to 2.7.13

Unsurprisingly there are a number of incompatibilities between
the current version (1.10.19) and 2.7.13. These classes and
methods were added to fix the problems found while trying to
build against 2.7.13.

The classes in org.mockito.compat were added to act as a layer
to insulate the code against those changes in mockito. The
intent is that the existing code will be changed to use those
classes instead of the ones that they extend so it builds
against 1.10.19. Then the upgrade will modify those classes
to make them work with 2.7.13 so that the code continues to
build. After the upgrade has been completed then the code that
used those compat classes will be modified to use standard
mockito and the classes will be deleted.

The MockitoHamcrest method exists upstream, this is just a
copy of that which works in 2.7.13. This is needed to support
using hamcrest based matchers with mockito.

The changes to InvocationOnMock adds a method that is new in
2.7.13 and deprecate the method that will be removed. Existing
code will be modified to use the new method and the upgrade will
delete the old one.

Bug: 32912773
Test: make checkbuild
Change-Id: I31dc4d3fc84558afda0c00f8054ec1fd4ec54c5a

5 files changed, 241 insertions, 1 deletions

diff --git a/src/main/java/org/mockito/compat/ArgumentMatcher.java b/src/main/java/org/mockito/compat/ArgumentMatcher.java
new file mode 100644
index 0000000..b288c8a
--- /dev/null
+++ b/src/main/java/org/mockito/compat/ArgumentMatcher.java
@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2017 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.mockito.compat;
+
+/**
+ * Base class for code that has to compile against Mockito 1.x and Mockito 2.x.
+ */
+public abstract class ArgumentMatcher<T> extends org.mockito.ArgumentMatcher<T> {
+
+    @Override
+    public boolean matches(Object argument) {
+      return matchesObject(argument);
+    }
+
+    public abstract boolean matchesObject(Object o);
+}
diff --git a/src/main/java/org/mockito/compat/CapturingMatcher.java b/src/main/java/org/mockito/compat/CapturingMatcher.java
new file mode 100644
index 0000000..aa586ea
--- /dev/null
+++ b/src/main/java/org/mockito/compat/CapturingMatcher.java
@@ -0,0 +1,30 @@
+/*
+ * Copyright (C) 2017 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.mockito.compat;
+
+/**
+ * Base class for code that has to compile against Mockito 1.x and Mockito 2.x.
+ */
+public abstract class CapturingMatcher<T>
+        extends org.mockito.internal.matchers.CapturingMatcher<T> {
+
+    @Override
+    public boolean matches(Object argument) {
+      return matchesObject(argument);
+    }
+
+    public abstract boolean matchesObject(Object o);
+}
diff --git a/src/main/java/org/mockito/hamcrest/MockitoHamcrest.java b/src/main/java/org/mockito/hamcrest/MockitoHamcrest.java
new file mode 100644
index 0000000..f6ccd03
--- /dev/null
+++ b/src/main/java/org/mockito/hamcrest/MockitoHamcrest.java
@@ -0,0 +1,165 @@
+/*
+ * Copyright (c) 2016 Mockito contributors
+ * This program is made available under the terms of the MIT License.
+ */
+package org.mockito.hamcrest;
+
+import org.hamcrest.Matcher;
+import org.mockito.ArgumentMatcher;
+import org.mockito.Mockito;
+
+/**
+ * Allows matching arguments with hamcrest matchers; back ported from 2.7.13
+ * to help with upgrade.
+ * 
+ * <b>Requires</b> <a href="http://hamcrest.org/JavaHamcrest/">hamcrest</a> on classpath,
+ * Mockito <b>does not</b> depend on hamcrest!
+ * Note the <b>NullPointerException</b> auto-unboxing caveat described below.
+ * <p/>
+ * Before implementing or reusing an existing hamcrest matcher please read
+ * how to deal with sophisticated argument matching in {@link ArgumentMatcher}.
+ * <p/>
+ * Mockito 2.1.0 was decoupled from Hamcrest to avoid version incompatibilities
+ * that have impacted our users in past. Mockito offers a dedicated API to match arguments
+ * via {@link ArgumentMatcher}.
+ * Hamcrest integration is provided so that users can take advantage of existing Hamcrest matchers.
+ * <p/>
+ * Example:
+ * <pre>
+ *     import static org.mockito.hamcrest.MockitoHamcrest.argThat;
+ *
+ *     //stubbing
+ *     when(mock.giveMe(argThat(new MyHamcrestMatcher())));
+ *
+ *     //verification
+ *     verify(mock).giveMe(argThat(new MyHamcrestMatcher()));
+ * </pre>
+ * <b>NullPointerException</b> auto-unboxing caveat.
+ * In rare cases when matching primitive parameter types you <b>*must*</b> use relevant intThat(), floatThat(), etc. method.
+ * This way you will avoid <code>NullPointerException</code> during auto-unboxing.
+ * Due to how java works we don't really have a clean way of detecting this scenario and protecting the user from this problem.
+ * Hopefully, the javadoc describes the problem and solution well.
+ * If you have an idea how to fix the problem, let us know via the mailing list or the issue tracker.
+ *
+ * @since 2.1.0
+ */
+public class MockitoHamcrest {
+
+    /**
+     * Allows matching arguments with hamcrest matchers.
+     * <p/>
+     * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>null</code> or default value for primitive (0, false, etc.)
+     * @since 2.1.0
+     */
+    @SuppressWarnings("unchecked")
+    public static <T> T argThat(Matcher<T> matcher) {
+        return Mockito.argThat(matcher);
+    }
+
+    /**
+     * Enables integrating hamcrest matchers that match primitive <code>char</code> arguments.
+     * Note that {@link #argThat} will not work with primitive <code>char</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
+     * <p/>
+     * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>0</code>.
+     */
+    public static char charThat(Matcher<Character> matcher) {
+        return Mockito.charThat(matcher);
+    }
+
+    /**
+     * Enables integrating hamcrest matchers that match primitive <code>boolean</code> arguments.
+     * Note that {@link #argThat} will not work with primitive <code>boolean</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
+     * <p/>
+     * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>false</code>.
+     */
+    public static boolean booleanThat(Matcher<Boolean> matcher) {
+        return Mockito.booleanThat(matcher);
+    }
+
+    /**
+     * Enables integrating hamcrest matchers that match primitive <code>byte</code> arguments.
+     * Note that {@link #argThat} will not work with primitive <code>byte</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
+     * <p/>
+     * * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>0</code>.
+     */
+    public static byte byteThat(Matcher<Byte> matcher) {
+        return Mockito.byteThat(matcher);
+    }
+
+    /**
+     * Enables integrating hamcrest matchers that match primitive <code>short</code> arguments.
+     * Note that {@link #argThat} will not work with primitive <code>short</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
+     * <p/>
+     * * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>0</code>.
+     */
+    public static short shortThat(Matcher<Short> matcher) {
+        return Mockito.shortThat(matcher);
+    }
+
+    /**
+     * Enables integrating hamcrest matchers that match primitive <code>int</code> arguments.
+     * Note that {@link #argThat} will not work with primitive <code>int</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
+     * <p/>
+     * * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>0</code>.
+     */
+    public static int intThat(Matcher<Integer> matcher) {
+        return Mockito.intThat(matcher);
+    }
+
+    /**
+     * Enables integrating hamcrest matchers that match primitive <code>long</code> arguments.
+     * Note that {@link #argThat} will not work with primitive <code>long</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
+     * <p/>
+     * * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>0</code>.
+     */
+    public static long longThat(Matcher<Long> matcher) {
+        return Mockito.longThat(matcher);
+    }
+
+    /**
+     * Enables integrating hamcrest matchers that match primitive <code>float</code> arguments.
+     * Note that {@link #argThat} will not work with primitive <code>float</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
+     * <p/>
+     * * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>0</code>.
+     */
+    public static float floatThat(Matcher<Float> matcher) {
+        return Mockito.floatThat(matcher);
+    }
+
+    /**
+     * Enables integrating hamcrest matchers that match primitive <code>double</code> arguments.
+     * Note that {@link #argThat} will not work with primitive <code>double</code> matchers due to <code>NullPointerException</code> auto-unboxing caveat.
+     * <p/>
+     * * See examples in javadoc for {@link MockitoHamcrest} class
+     *
+     * @param matcher decides whether argument matches
+     * @return <code>0</code>.
+     */
+    public static double doubleThat(Matcher<Double> matcher) {
+        return Mockito.doubleThat(matcher);
+    }
+}
diff --git a/src/main/java/org/mockito/internal/invocation/InvocationImpl.java b/src/main/java/org/mockito/internal/invocation/InvocationImpl.java
index 19193fa..19e85f7 100644
--- a/src/main/java/org/mockito/internal/invocation/InvocationImpl.java
+++ b/src/main/java/org/mockito/internal/invocation/InvocationImpl.java
@@ -62,6 +62,10 @@ public class InvocationImpl implements Invocation, VerificationAwareInvocation {
         return arguments;
     }
 
+    public <T> T getArgument(int index) {
+        return (T) arguments[index];
+    }
+
     public <T> T getArgumentAt(int index, Class<T> clazz) {
         return (T) arguments[index];
     }
@@ -131,4 +135,4 @@ public class InvocationImpl implements Invocation, VerificationAwareInvocation {
     public void ignoreForVerification() {
         isIgnoredForVerification = true;
     }
-}
\ No newline at end of file
+}
diff --git a/src/main/java/org/mockito/invocation/InvocationOnMock.java b/src/main/java/org/mockito/invocation/InvocationOnMock.java
index 815b8a4..179ae56 100644
--- a/src/main/java/org/mockito/invocation/InvocationOnMock.java
+++ b/src/main/java/org/mockito/invocation/InvocationOnMock.java
@@ -37,10 +37,22 @@ public interface InvocationOnMock extends Serializable {
     Object[] getArguments();
     
     /**
+     * Returns casted argument at the given index.
+     *
+     * Can lookup in expanded arguments form {@link #getArguments()}.
+     *
+     * @param index argument index
+     * @return casted argument at the given index
+     * @since 2.1.0
+     */
+    <T> T getArgument(int index);
+
+    /**
     * Returns casted argument using position
     * @param index argument position
     * @param clazz argument type
     * @return casted argument on position
+    * @deprecated Use getArgument(int) instead.
     */
     <T> T getArgumentAt(int index, Class<T> clazz);