feat: Add alternative proxy implementation (#1790)

build.gradle

@@ -198,6 +198,7 @@ task unitTest( type: Test ) {
     testLogging.exceptionFormat = 'full'
     filter {
         includeTestsMatching 'io.appium.java_client.internal.*'
+        includeTestsMatching 'io.appium.java_client.proxy.*'
     }
 }
 

docs/The-event_firing.md

@@ -3,7 +3,7 @@ since v8.0.0
 # The purpose
 
 This feature allows end user to organize the event logging on the client side. 
-Also this feature may be useful in a binding with standard or custom reporting
+Also, this feature may be useful in a binding with standard or custom reporting
 frameworks. The feature has been introduced first since Selenium API v4.  
 
 # The API
@@ -40,6 +40,7 @@ Listeners should implement WebDriverListener. It supports three types of events:
 To use this decorator you have to prepare a listener, create a decorator using this listener, 
 decorate the original WebDriver instance with this decorator and use the new WebDriver instance
 created by the decorator instead of the original one: 
+
 ```java
 WebDriver original = new AndroidDriver(); 
 // it is expected that MyListener class implements WebDriverListener
@@ -66,6 +67,7 @@ decorated.get("http://example.com/");
 WebElement header = decorated.findElement(By.tagName("h1")); 
 // if an error happens during any of these calls the the onError event is fired
 ```
+
 The instance of WebDriver created by the decorator implements all the same interfaces 
 as the original driver. A listener can subscribe to "specific" or "generic" events (or both). 
 A "specific" event correspond to a single specific method, a "generic" event correspond to any 
@@ -74,3 +76,81 @@ implement a method with a name derived from the target method to be watched. The
 for "before"-events receive the parameters passed to the decorated method. The listener 
 methods for "after"-events receive the parameters passed to the decorated method as well as the 
 result returned by this method.
+
+## createProxy API (since Java Client 8.3.0)
+
+This API is unique to Appium Java Client and does not exist in Selenium. The reason for 
+its existence is the fact that the original event listeners API provided by Selenium is limited
+because it can only use interface types for decorator objects. For example, the code below won't
+work:
+
+```java
+IOSDriver driver = new IOSDriver(new URL("http://doesnot.matter/"), new ImmutableCapabilities())
+{
+    @Override
+    protected void startSession(Capabilities capabilities)
+    {
+        // Override in a sake of simplicity to avoid the actual session start
+    }
+};
+WebDriverListener webDriverListener = new WebDriverListener()
+{
+};
+IOSDriver decoratedDriver = (IOSDriver) new EventFiringDecorator(IOSDriver.class, webDriverListener).decorate(
+        driver);
+```
+
+The last line throws `ClassCastException` because `decoratedDriver` is of type `IOSDriver`, 
+which is a class rather than an interface. 
+See the issue [#1694](https://github.com/appium/java-client/issues/1694) for more
+details. In order to workaround this limitation a special proxy implementation has been created,
+which is capable of decorating class types:
+
+```java
+import io.appium.java_client.proxy.MethodCallListener;
+import io.appium.java_client.proxy.NotImplementedException;
+
+import static io.appium.java_client.proxy.Helpers.createProxy;
+
+// ...
+
+MethodCallListener listener = new MethodCallListener() {
+    @Override
+    public void beforeCall(Object target, Method method, Object[] args) {
+        if (!method.getName().equals("get")) {
+            throw new NotImplementedException();
+        }
+        acc.append("beforeCall ").append(method.getName()).append("\n");
+    }
+
+    @Override
+    public void afterCall(Object target, Method method, Object[] args, Object result) {
+        if (!method.getName().equals("get")) {
+            throw new NotImplementedException();
+        }
+        acc.append("afterCall ").append(method.getName()).append("\n");
+    }
+};
+
+IOSDriver decoratedDriver = createProxy(
+        IOSDriver.class,
+        new Object[] {new URL("http://localhost:4723/"), new XCUITestOptions()},
+        new Class[] {URL.class, Capabilities.class},
+        listener
+);
+
+decoratedDriver.get("http://example.com/");
+
+assertThat(acc.toString().trim()).isEqualTo(
+        String.join("\n",
+                "beforeCall get",
+                "afterCall get"
+        )
+);
+```
+
+This proxy is not tied to WebDriver descendants and could be used to any classes that have
+**public** constructors. It also allows to intercept exceptions thrown by **public** class methods and/or
+change/replace the original methods behavior. It is important to know that callbacks are **not** invoked 
+for methods derived from the standard `Object` class, like `toString` or `equals`. 
+Check [unit tests](../src/test/java/io/appium/java_client/proxy/ProxyHelpersTest.java) for more examples.

src/main/java/io/appium/java_client/proxy/Helpers.java

@@ -0,0 +1,157 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * 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 io.appium.java_client.proxy;
+
+import com.google.common.base.Preconditions;
+import net.bytebuddy.ByteBuddy;
+import net.bytebuddy.dynamic.loading.ClassLoadingStrategy;
+import net.bytebuddy.implementation.MethodDelegation;
+import net.bytebuddy.matcher.ElementMatchers;
+
+import java.util.Collection;
+import java.util.Collections;
+
+public class Helpers {
+    private Helpers() {
+    }
+
+    /**
+     * Creates a transparent proxy instance for the given class.
+     * It is possible to provide one or more method execution listeners
+     * or replace particular method calls completely. Callbacks
+     * defined in these listeners are going to be called when any
+     * **public** method of the given class is invoked. Overridden callbacks
+     * are expected to be skipped if they throw
+     * {@link io.appium.java_client.proxy.NotImplementedException}.
+     *
+     * @param cls                 the class to which the proxy should be created.
+     *                            Must not be an interface.
+     * @param constructorArgs     Array of constructor arguments. Could be an
+     *                            empty array if the class provides a constructor without arguments.
+     * @param constructorArgTypes Array of constructor argument types. Must
+     *                            represent types of constructorArgs.
+     * @param listeners           One or more method invocation listeners.
+     * @param <T>                 Any class derived from Object
+     * @return Proxy instance
+     */
+    public static <T> T createProxy(
+            Class<T> cls,
+            Object[] constructorArgs,
+            Class<?>[] constructorArgTypes,
+            Collection<MethodCallListener> listeners
+    ) {
+        Preconditions.checkArgument(constructorArgs.length == constructorArgTypes.length,
+                String.format(
+                        "Constructor arguments array length %d must be equal to the types array length %d",
+                        constructorArgs.length, constructorArgTypes.length
+                )
+        );
+        Preconditions.checkArgument(!listeners.isEmpty(), "The collection of listeners must not be empty");
+        Preconditions.checkArgument(cls != null, "Class must not be null");
+        Preconditions.checkArgument(!cls.isInterface(), "Class must not be an interface");
+
+        //noinspection resource
+        Class<?> proxy = new ByteBuddy()
+                .subclass(cls)
+                .method(ElementMatchers.isPublic()
+                        .and(ElementMatchers.not(
+                                ElementMatchers.isDeclaredBy(Object.class)
+                                        .or(ElementMatchers.isOverriddenFrom(Object.class))
+                        )))
+                .intercept(MethodDelegation.to(Interceptor.class))
+                .make()
+                .load(cls.getClassLoader(), ClassLoadingStrategy.Default.WRAPPER)
+                .getLoaded()
+                .asSubclass(cls);
+
+        try {
+            //noinspection unchecked
+            T instance = (T) proxy
+                    .getConstructor(constructorArgTypes)
+                    .newInstance(constructorArgs);
+            Interceptor.LISTENERS.put(instance, listeners);
+            return instance;
+        } catch (SecurityException | ReflectiveOperationException e) {
+            throw new IllegalStateException(String.format("Unable to create a proxy of %s", cls.getName()), e);
+        }
+    }
+
+    /**
+     * Creates a transparent proxy instance for the given class.
+     * It is possible to provide one or more method execution listeners
+     * or replace particular method calls completely. Callbacks
+     * defined in these listeners are going to be called when any
+     * **public** method of the given class is invoked. Overridden callbacks
+     * are expected to be skipped if they throw NotImplementedException.
+     *
+     * @param cls       the class to which the proxy should be created.
+     *                  Must not be an interface. Must expose a constructor
+     *                  without arguments.
+     * @param listeners One or more method invocation listeners.
+     * @param <T>       Any class derived from Object
+     * @return Proxy instance
+     */
+    public static <T> T createProxy(Class<T> cls, Collection<MethodCallListener> listeners) {
+        return createProxy(cls, new Object[]{}, new Class[]{}, listeners);
+    }
+
+    /**
+     * Creates a transparent proxy instance for the given class.
+     * It is possible to provide one or more method execution listeners
+     * or replace particular method calls completely. Callbacks
+     * defined in these listeners are going to be called when any
+     * **public** method of the given class is invoked. Overridden callbacks
+     * are expected to be skipped if they throw NotImplementedException.
+     *
+     * @param cls      the class to which the proxy should be created.
+     *                 Must not be an interface. Must expose a constructor
+     *                 without arguments.
+     * @param listener Method invocation listener.
+     * @param <T>      Any class derived from Object
+     * @return Proxy instance
+     */
+    public static <T> T createProxy(Class<T> cls, MethodCallListener listener) {
+        return createProxy(cls, new Object[]{}, new Class[]{}, Collections.singletonList(listener));
+    }
+
+    /**
+     * Creates a transparent proxy instance for the given class.
+     * It is possible to provide one or more method execution listeners
+     * or replace particular method calls completely. Callbacks
+     * defined in these listeners are going to be called when any
+     * **public** method of the given class is invoked. Overridden callbacks
+     * are expected to be skipped if they throw NotImplementedException.
+     *
+     * @param cls                 the class to which the proxy should be created.
+     *                            Must not be an interface.
+     * @param constructorArgs     Array of constructor arguments. Could be an
+     *                            empty array if the class provides a constructor without arguments.
+     * @param constructorArgTypes Array of constructor argument types. Must
+     *                            represent types of constructorArgs.
+     * @param listener            Method invocation listener.
+     * @param <T>                 Any class derived from Object
+     * @return Proxy instance
+     */
+    public static <T> T createProxy(
+            Class<T> cls,
+            Object[] constructorArgs,
+            Class<?>[] constructorArgTypes,
+            MethodCallListener listener
+    ) {
+        return createProxy(cls, constructorArgs, constructorArgTypes, Collections.singletonList(listener));
+    }
+}