A light weight URI routing framework for Android

Linker provides an annotation-based API to handle URI routing for Android. This library is written in kotlin, and the generated codes are also pure kotlin.

Dependencies

Add the following to your build.gradle file:

dependencies {
	api 'Me. Twocities: would: 0.0.5'
	kapt 'Me. Twocities: would - compiler: 0.0.5'
}Copy the code

Annotations

@Link for activity

Use annotation @Link indicate which URI was respect:

@Link("link://product/detail{id})
class ProductActivity: AppCompatActivity {
}Copy the code

@LinkPath @LinkQuery for parameters

@Link("link://product/detail/{id})
class ProductActivity: AppCompatActivity {
  @LinkPath("id") lateinit var productId: String
  @LinkQuery("title") lateinit var productTitle: String
}Copy the code

After annotation processing, an extension function bindLinkParams() of ProductActivity will be generated, you can use it to get values of @LinkPath @LinkQuery params:

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  bindLinkParams()
}Copy the code

@LinkModule for module

// generate LinkerExampleLinkModule
@LinkModule
class ExampleLinkModuleCopy the code

After annotation processing, a module class was generated, will contains informations of all defined @Link, @LinkPath, @LinkQuery. The generated class will be used to decided which uri will be routed.

@LinkModule supports multi android’s library module.

@LinkResolverBuilder for builder

// generate LinkerExampleLinkResolverBuilder
@LinkResolverBuilder(modules = arrayOf(ExampleLinkModule: :class, LibraryLinkModule: :class))
interface ExampleLinkResolverBuilderCopy the code

This will generate a LinkResolver’s builder:

val resolver = LinkerExampleLinkResolverBuilder(context).build()
Copy the code

The definition of LinkResolver is much simpler:

interface LinkResolver {
  fun resolve(link: String): Result
}Copy the code

Function resolve will parse the given link, and then return a Result, which has a nullable property of Intent, it will be null if no responding activities was found,

Routing:

val result = resolver.resolve("link//product/detail/123")
if (result.success()) startActivity(result.intent)Copy the code

Thanks to kotlin, we can simplify this by writing extension function like this:

startActivity("link://product/detail/123")Copy the code

see ObjectGraph for more details.

Advance

Linker also provide other mechanisms: Interceptor, FallbackHandler, which you can change the behavior of a link. You can add interceptors or set fallback handler by the generated builder class:

 val resolver = LinkerBuilder(context)
        .addInterceptor(HttpUrlInterceptor(context))
        .setFallbackHandler(DefaultUrlHandler(context))
        .setListener(ResolverListener())
        .build()Copy the code

the Listener will be notified when an link was resolved.

The interceptor will give you an ability to change a link’s intent, or put extra values to activity

// An interceptor handles how http(s) url was resolved
class HttpUrlInterceptor(private val context: Context) : Interceptor {
  override fun intercept(link: String.metadata: LinkMetadata?): Intent? {
    if (link.startsWith("http") or link.startsWith("https")) {
      // since `LINK` will be passed to intent automatically, we can return the intent directly
      return Intent(context, SimpleBrowserActivity: :class.java)
    }
    return null}}Copy the code

FallbackHandler

If there’s no activities match with the given link, or no interceptors has intercepted, the fallback handler be called. The [FallbackHandler] gives you the ability to handle unknown link: start another activity or show an error page.

TODO

Generate link’s builder when compiling
Support multi links for per activity
More unit tests

License

The Apache License, Version 2.0