Remoter

Fork of josesamuel/remoter. This fork is Kotlin and KSP only — Java support and KAPT are dropped.

Remoter — An alternative to Android AIDL for Android remote IPC services using plain Kotlin interfaces

Remoter makes developing Android remote services intuitive without messing with AIDL.

Android IPC through AIDL

Android supports remote IPC using AIDL. This process of using AIDL is painful and limited.

Some of the problems and limitations of AIDL are:

• Unlike the intuitive way of defining interface definitions as an interface, AIDL forces you to define the interface in an ".aidl" file
• The .aidl file is usually in a different folder than your normal source
• You lose most of the IDE capability for the ".aidl"
• You can't use an existing interface class and convert that to a remote interface -- it has to be defined separately as ".aidl"
• Only limited predefined data types are supported in AIDL
• Any custom Parcelable class that you want to pass through the interface has to be defined again as another ".aidl" file!
• No overloaded methods! Methods with the same name fail
• Can't extend an AIDL with another
• Can't throw custom exceptions

Remoter - An intuitive way for Android IPC

Remoter solves the above problems in AIDL by allowing you to define the remote interface using a plain Kotlin interface, and implement it using a plain Kotlin implementation of the interface.

All you have to do is annotate the interface using @Remoter

@Remoter
interface ISampleService {
    // ...
}

• No messy .aidl, just plain simple interface
• Implement the interface directly using the intuitive normal Kotlin way, instead of extending Stub
• Fully interoperable with AIDL. Remoter creates the same serialized data as created by AIDL, so it is fully interoperable with AIDL
• Supports more data types than AIDL, everything supported by Parceler
• Make an interface that extends other interfaces as @Remoter
• Interface methods can throw any exceptions. Clients will get the same exception that is thrown.
• Remoter interface can be templated
• Remoter is an annotation processor that generates two helper classes during build time -- a client side Proxy and a service side Stub that allows you to wrap your interface and implementation
• Supports Kotlin coroutines!

At the client side

• Simply wrap the binder that you got from the ServiceConnection with the autogenerated Proxy for your interface

val sampleService: ISampleService = ISampleService_Proxy(binder)

At the service side

• Wrap the implementation with the autogenerated Stub to convert it as a remote Binder and return that from your service

val binder: Binder = ISampleService_Stub(sampleServiceImpl)

That's it!

Annotations

• @Remoter Annotate on an interface to make it a remote interface
  • You can also use a marker interface that can provide a list of interfaces for which to generate the Remoter Proxy/Stub classes. For this, annotate @Remoter on the marker interface and specify the list of classes for "classesToWrap"

/**
 * Example of a marker remoter interface that specifies other interfaces that should generate remoter proxy stub
 * <p>
 * In this case no proxy/stub gets generated for Marker, but it gets generated for IBaseA and IBaseB
 */
@Remoter(classesToWrap = [IBaseA::class, IBaseB::class])
interface Marker

• @ParamIn Mark an array or Parcelable parameter as an input only parameter(in of AIDL). By default, they are input and output (inout of AIDL)
• @ParamOut Mark an array or Parcelable parameter as an output only parameter(out of AIDL).
• @Oneway Annotate on a method (in the @Remoter interface) with void return to make it an asynchronous method.
• @NullableType Used to annotate a type parameter or suspend function return as nullable. See below for more details

Kotlin support with suspend functions

Remoter supports Kotlin interfaces with suspend functions.

• The suspend functions will be dispatched using the Dispatcher.IO context
• Kotlin Proxy can be created using the optional constructor that accepts IServiceConnector which moves service connection to a suspendable coroutine

Kotlin Example

• Define interface in Kotlin as suspend

@Remoter
interface ISampleService {

    /**
     * A suspend function which will be implemented by a service
     */
    suspend fun authenticate(userName:String, password:String) : Boolean
}

• Include the dependency for RemoterBuilder to take advantage of suspendable service connection

implementation 'me.sergeich:remoter-builder:3.0.0-alpha'

• From your coroutine, call the remote service call as follows

//From your coroutine context -

//create service using SERVICE_INTENT
val service = ISampleService_Proxy(context, SERVICE_INTENT)

//call the suspend function
val authenticated = service.authenticate(userName, password)

// The above call will
// - suspend the current context
// - connect to service,
// - make the remote call,
//
// all sequentially without blocking the calling thread!

• No need to take care of service connection!
• No need to move to background thread for service call and then to main thread to update UI!

Notes on Kotlin support

• Add remoter-builder dependency to get support for suspendable service connection using IServiceConnector
• If a suspend function has a nullable return type, explicitly annotate the method with @NullableType
• If any component of a generic parameter is nullable, explicitly mark the parameter with @NullableType (optionally specifying the nullable indexes)

Getting Remoter

Gradle dependency

dependencies {

    implementation 'me.sergeich:remoter-annotations:3.0.0-alpha'
    ksp 'me.sergeich:remoter:3.0.0-alpha'

    // If you're using Kotlin coroutines, include following
    // to make the service connection even simpler
    implementation 'me.sergeich:remoter-builder:3.0.0-alpha'
}

License

Copyright 2026 Sergei Glotov
Copyright 2017 Joseph Samuel

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.