Added a new concept of deep link handlers. (#330)

* Add support for deeplink handlers to mach index.

* Rename .java to .kt

* Convert BaseDeepLinkDelegate to Kotlin.

* Add new concept of DeepLinkHandler.kt

* Update handler test to test several success and failure scenarios.

* Added documentation

* Cleanup, fixed Java support and added tests.
Better error handling in the processor.
Added support for throwing on type conversion errors.

* Cleanup

* Fix Proguard/R8 config for new requirements.
Add Proguard/R8 config to sample release build type.

* type fix

* Fixed keep rules and tested with obfuscation.
Do not use InBetweenDepLinkHandler on Java test.
Cleaner way to get the type of the args object that only works because of the way we define these here.

* Use lambdas to handle type conversion issues to give implementing apps more flexibility.

* Fixed formatting for ktlint

* Moved DeepLinkHandler<T> from abstract class to interface.
Changed behavior so that the arguments class must only contain a subset of all placeholders or query elements in the deep link.
Added support for custom type converters.
Updated reflection logic to find arg type to work on implemented interfaces and extended classes that implement the interface.
Moved type conversion error handlers to BaseDeepLinkDelegate.kt.
Rewrote project speciffic DeepLinkDelegate creation fully and support more constructor overrides.
Added updated tests for new features.
Added error when havong two @com.airbnb.deeplinkdelegate.DeepLinkHandler  annotated classes in one package. Added test for that error case.

* Add type conversion support for generic types.

* Fixed R8/Proguard rule
Added support for no parameter class.
Added logging to handlers
Cleanup removed warnings.

* Fixed R8/Proguard rule
Added support for no parameter class.
Added logging to handlers
Cleanup removed warnings.
Moved type converters to functional interface so that the suopported set can change during runtime.
Renamed parameters to deepLinkArgs

* KSP to 1.0

* Keep registries public.

* fix handling of null returned from annotated methods.
added unit tests for the behavior.

* Update interface for deep link handler argument type conversion errors.
Add handler and handler arg class to DeepLinkResult.
Fix issue when handler was implemented on extension class plus added tests for this and further removed extension case.

* Cleanup documentation

Co-authored-by: Andreas Rossbacher <andreas.rossbacher@airbnb.com>

Author: rossbacher

README.md

@@ -48,6 +48,85 @@ public class MainActivity extends Activity {
 }
 ```
 
+### DeepLinkHandler Annotations
+
+You can annotate a Kotlin `object` that is extending `com.airbnb.deeplinkdispatch.handler.DeepLinkHandler`
+with an `@DeepLink` annotation.
+
+```kotlin
+@DeepLink("foo://example.com/handlerDeepLink/{param1}?query1={queryParameter}")
+object ProjectDeepLinkHandler : DeepLinkHandler<ProjectDeepLinkHandlerArgs>() {
+    override fun handleDeepLink(parameters: ProjectDeepLinkHandlerArgs) {
+        /**
+         * From here any internal/3rd party navigation framework can be called the provided args.
+         */
+    }
+}
+
+data class ProjectDeepLinkHandlerArgs(
+    @DeeplinkParam("param1", DeepLinkParamType.Path) val number: Int,
+    @DeeplinkParam("query1", DeepLinkParamType.Query) val flag: Boolean?,
+)
+```
+
+DeepLinkDispatch will then call the `handleDeepLink` function in your handler with the path placeholders
+and queryParameters converted into an instance of the specified type class.
+
+Query parameter conversion is supported for nullable and non nullable versions of `Boolean`,`Int`,
+`Long`,`Short`,`Byte`,`Double`,`Float` and `String` as well as the same types in Java. For other
+types see: [Type conversion](#type-conversion)
+
+This will give compile time safety, as all placeholders and query parameters specified in the template
+inside the `@DeepLink` annotation must be present in the arguments class for the processor to pass.
+This is also true the other way around as all fields in the arguments class must be annotated and must
+be present in the template inside the annotation.
+
+From this function you can now call into any internal or 3rd party navigation system
+without any Intent being fired at all and with type safety for your arguments.
+
+*Note:* Even though they must be listed in the template and annotation, argument values annotated
+with `DeepLinkParamType.Query` can be null as they are allowed to not be present in the matched url.
+
+#### Type conversion
+
+If you want to support the automatic conversions of types other than `Boolean`,`Int`,`Long`,`Short`,`Byte`,
+`Double`,`Float` and `String` in deep link argument classes you can add support by adding your own type
+converters in the `DeepLinkDelegate` class that you are instantiating.
+
+Type conversion is handled via a lambda that you can set in the `DeepLinkDelegate` constructor.
+
+All type converters you want to add get added to an instance of `TypeConverters` which then in turn
+gets returned by the lambda. This way you can add type converters on the fly while the app is running
+(e.g. if you just downloaded a dynamic feature which supports additional types).
+
+There is an example of this in the `sample` app for this. Here is a brief overview:
+
+```java
+TypeConverters typeConverters = new TypeConverters();
+typeConverters.put(ColorDrawable.class, value -> {
+  switch (value.toLowerCase()) {
+    case "red":
+      return new ColorDrawable(0xff0000ff);
+  }
+});
+
+Function0<TypeConverters> typeConvertersLambda = () -> typeConverters;
+
+DeepLinkDelegate deepLinkDelegate = new DeepLinkDelegate(
+  ...
+  typeConvertersLambda,
+  ...);
+```
+
+#### Type conversion errors
+
+If a url parameter cannot be converted to the specified type, the system will -- by default -- set the
+value to `0` or `null`, depending on if the type is nullable. However this behavior can be overwritten
+by implementing a lambda `Function3<DeepLinkUri, Type, String, Integer>` and setting it to
+`typeConversionErrorNullable` and/or `typeConversionErrorNonNullable` via the `DeepLinkDelegate`
+constructor. When called, the lambda will let you know about the matching `DeepLinkUri` template, the
+type and the value that was tried to type convert so you can also log these events.
+
 ### Method Annotations
 
 You can also annotate any `public static` method with `@DeepLink`. DeepLinkDispatch will call that
@@ -604,15 +683,12 @@ At runtime we traverse the graph for each module to find the correct action to u
 * Configurable path segments can have empty values e.g. `<brand>` can be set to `""` in the previous example. Which would then match `dld://airbnb/cereal`. If a deeplink like that is defined already somewhere else the same match rules as mentioned before apply to which match actually gets found.
 * Because of limitations of the algo the last path element (the item behind the last slash) cannot  be a configurable path segment with it's value set to `""`. Currently the system will allow you to do this but will not correctly match in that case.
 
-## Proguard Rules
+## Proguard/R8 Rules
 
-```
--keep @interface com.airbnb.deeplinkdispatch.DeepLink
--keepclasseswithmembers class * {
-    @com.airbnb.deeplinkdispatch.DeepLink <methods>;
-}
-```
-**Note:** remember to include Proguard rules to keep Custom annotations you have used, for example by package:
+The Proguard/R8 rules mandatory for teh lib are defined in the [proguard-rules.pro](deeplinkdispatch/proguard-rules.pro) in `deeplinkdispatch`. However
+they are already included via `consumerProguardFiles` so there is nothing you have to do to include them.
+
+Please note however that you must add your own Proguard/R8 rules to keep Custom annotations you have used. For example:
 
 ```
 -keep @interface your.package.path.deeplink.<annotation class name>

build.gradle

@@ -31,6 +31,12 @@ allprojects {
     }
 }
 
+tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
+    kotlinOptions {
+        allWarningsAsErrors = true
+    }
+}
+
 def getReleaseRepositoryUrl() {
     return hasProperty('RELEASE_REPOSITORY_URL') ? RELEASE_REPOSITORY_URL
             : "https://oss.sonatype.org/service/local/staging/deploy/maven2/"

deeplinkdispatch-base/src/main/java/com/airbnb/deeplinkdispatch/DeepLinkEntry.kt

@@ -33,13 +33,21 @@ data class DeepLinkMatchResult(
 
     override fun toString(): String {
         return "uriTemplate: ${deeplinkEntry.uriTemplate} " +
-            "activity: ${deeplinkEntry.activityClass.name} " +
-            "method: ${deeplinkEntry.method} " +
+            "activity: ${deeplinkEntry.clazz.name} " +
+            "${if (deeplinkEntry is DeepLinkEntry.MethodDeeplinkEntry) "method: ${deeplinkEntry.method} " else ""}" +
             "parameters: $parameterMap"
     }
 
-    private val firstConfigurablePathSegmentIndex: Int by lazy { deeplinkEntry.uriTemplate.indexOf(configurablePathSegmentPrefixChar) }
-    private val firstPlaceholderIndex: Int by lazy { deeplinkEntry.uriTemplate.indexOf(componentParamPrefixChar) }
+    private val firstConfigurablePathSegmentIndex: Int by lazy {
+        deeplinkEntry.uriTemplate.indexOf(
+            configurablePathSegmentPrefixChar
+        )
+    }
+    private val firstPlaceholderIndex: Int by lazy {
+        deeplinkEntry.uriTemplate.indexOf(
+            componentParamPrefixChar
+        )
+    }
     private val firstNonConcreteIndex: Int by lazy {
         if (firstPlaceholderIndex == -1 && firstConfigurablePathSegmentIndex == -1) {
             -1
@@ -78,21 +86,25 @@ data class DeepLinkMatchResult(
     }
 }
 
-data class DeepLinkEntry(
-    val uriTemplate: String,
-    /**
-     * The class name where the annotation corresponding to where an instance of DeepLinkEntry is declared.
-     */
-    val className: String,
-    val method: String?
-) {
+sealed class DeepLinkEntry(open val uriTemplate: String, open val className: String) {
 
-    enum class Type {
-        CLASS,
-        METHOD
-    }
+    data class ActivityDeeplinkEntry(
+        override val uriTemplate: String,
+        override val className: String
+    ) : DeepLinkEntry(uriTemplate, className)
 
-    val activityClass: Class<*> by lazy {
+    data class MethodDeeplinkEntry(
+        override val uriTemplate: String,
+        override val className: String,
+        val method: String
+    ) : DeepLinkEntry(uriTemplate, className)
+
+    data class HandlerDeepLinkEntry(
+        override val uriTemplate: String,
+        override val className: String
+    ) : DeepLinkEntry(uriTemplate, className)
+
+    val clazz: Class<*> by lazy {
         try {
             Class.forName(className)
         } catch (e: ClassNotFoundException) {
@@ -103,8 +115,4 @@ data class DeepLinkEntry(
             )
         }
     }
-
-    override fun toString(): String {
-        return "uriTemplate: $uriTemplate className: $className method: $method"
-    }
 }

deeplinkdispatch-base/src/main/java/com/airbnb/deeplinkdispatch/DeepLinkUri.java

@@ -16,8 +16,11 @@
 
 package com.airbnb.deeplinkdispatch;
 
+import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
+import org.jetbrains.annotations.NotNull;
+
 import java.io.EOFException;
 import java.net.IDN;
 import java.net.InetAddress;
@@ -29,10 +32,13 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.HashSet;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 import okio.Buffer;
 
@@ -55,6 +61,7 @@ public final class DeepLinkUri {
   static final String CONVERT_TO_URI_ENCODE_SET = "^`{}|\\";
   static final String FORM_ENCODE_SET = " \"':;<=>@[]^`{}|/\\?#&!$(),~";
   static final String FRAGMENT_ENCODE_SET = "";
+  static final Pattern PLACEHOLDER_REGEX = Pattern.compile("\\{(.*?)\\}");
 
   /** Either "http" or "https". */
   private final String scheme;
@@ -91,7 +98,9 @@ public final class DeepLinkUri {
   /** Canonical URL. */
   private final String url;
 
-  private DeepLinkUri(Builder builder) {
+  private String urlTemplate;
+
+  private DeepLinkUri(Builder builder, String urlTemplate) {
     this.scheme = builder.scheme;
     this.username = percentDecode(builder.encodedUsername);
     this.password = percentDecode(builder.encodedPassword);
@@ -105,6 +114,7 @@ private DeepLinkUri(Builder builder) {
         ? percentDecode(builder.encodedFragment)
         : null;
     this.url = builder.toString();
+    this.urlTemplate = urlTemplate;
   }
 
   /** Returns this URL as a {@link URL java.net.URL}. */
@@ -301,6 +311,27 @@ String query() {
     return result.toString();
   }
 
+  public @NonNull
+  Set<String> getSchemeHostPathPlaceholders() {
+    if (toTemplateString() == null) return Collections.emptySet();
+    if (this.query() == null || this.query().isEmpty()) return getPlaceHolders(toTemplateString());
+    return getPlaceHolders(
+      toTemplateString().substring(0, toTemplateString().indexOf(this.query()))
+    );
+  }
+
+  @NotNull
+  private Set<String> getPlaceHolders(String input) {
+    final Matcher matcher = PLACEHOLDER_REGEX.matcher(input);
+    Set<String> placeholders = new HashSet<>(matcher.groupCount());
+    while (matcher.find()) {
+      for (int i = 1; i <= matcher.groupCount(); i++) {
+        placeholders.add(matcher.group(i));
+      }
+    }
+    return placeholders;
+  }
+
   @Nullable
   List<String> getQueryNamesAndValues() {
     return queryNamesAndValues;
@@ -454,6 +485,10 @@ static DeepLinkUri get(URI uri) {
     return url;
   }
 
+  public String toTemplateString() {
+    return urlTemplate;
+  }
+
   static final class Builder {
     String scheme;
     String encodedUsername = "";
@@ -463,6 +498,7 @@ static final class Builder {
     final List<String> encodedPathSegments = new ArrayList<>();
     List<String> encodedQueryNamesAndValues;
     String encodedFragment;
+    String templateUrl;
 
     Builder() {
       encodedPathSegments.add(""); // The default path is '/' which needs a trailing space.
@@ -668,7 +704,7 @@ Builder encodedFragment(String encodedFragment) {
     DeepLinkUri build() {
       if (scheme == null) throw new IllegalStateException("scheme == null");
       if (host == null) throw new IllegalStateException("host == null");
-      return new DeepLinkUri(this);
+      return new DeepLinkUri(this, templateUrl);
     }
 
     @Override public String toString() {
@@ -726,6 +762,9 @@ enum ParseResult {
     ParseResult parse(DeepLinkUri base, String input, boolean allowPlaceholderInScheme) {
       int pos = skipLeadingAsciiWhitespace(input, 0, input.length());
       int limit = skipTrailingAsciiWhitespace(input, pos, input.length());
+      if (allowPlaceholderInScheme) {
+        templateUrl = input;
+      }
 
       // Scheme.
       int schemeDelimiterOffset = schemeDelimiterOffset(input,