Remoter

Remoter - An alternative to Android AIDL for Android Remote IPC services using plain java 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 an inteface defintions 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 seperately 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 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 plain java interface, and implement it using plain java implementation of the interface.

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

@Remoter
public interface ISampleService {
    ...
}

• No messy .aidl, just plain simple interface
• Implement the interface directly using intuitive normal java 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
• Support kotlin coroutines!

At the client side

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

ISampleService sampleService = new ISampleService_Proxy( binder );

At the service side

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

Binder binder = new ISampleService_Stub( sampleServiceImpl );

That's it!

Annotations

• @Remoter Annotate on an interface to make it a remote interface
  • You an 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 generate for Marker, but it gets generated for IBaseA and IBaseB
   */
	@Remoter(classesToWrap = {IBaseA.class, IBaseB.class})
	private 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. If your interface (marked with @Remoter) has any suspend functions, then the generated Proxy and Stub will be in Kotlin, enabling to call your remoter service method from coroutines.

• 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 depednecy for RemoterBuilder to take advantage of suspended service connection

implementation 'com.josesamuel:remoter-builder:<VERSION>'

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

//From your coroutine context - 

//create service using serviceintent
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 thred to update UI!

Notes on Kotlin support

• Add remoter-builder dependency to get support for suspendable service connection using IServiceConnector
• vararg is not supported. Either use array or non suspend
• If any return is nullable type on a suspend function, explicitly mark the method with @NullableType
• If any types in a generic parameter is nullable, explicitly mnark those parameter with @NullableType optionally specifying which indexex of that type parameter are nullable

Getting Remoter

Gradle dependency

dependencies {

    implementation 'com.josesamuel:remoter-annotations:2.0.5'
    kapt 'com.josesamuel:remoter:2.0.5'
    
    
    //If using kotlin coroutines, include following 
    //to make even the service connection simpler - 
    
    implementation 'com.josesamuel:remoter-builder:2.0.5'
    
}

License

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.