Firefly

Lightweight thrift client code generator and runtime library for Android and Java.

Code generated by firefly has much fewer methods(about 1%) and lines than standard thrift code, which helps applications avoid the notorious 64k limit on methods in Android applications.

For exmaple, evernote's public api is provided with thrift. Methods count of standard thrift generated code:

<root>: 20815
  com: 20815

evernote: 20815

 edam: 20815

  error: 226

  limits: 2

  notestore: 15225

  type: 2776

  userstore: 2586 Overall method count: 20815 

Methods count of Firefly generated code:

<root>: 204
  com: 204

evernote: 204

 edam: 204

  error: 10

  limits: 1

  notestore: 90

  type: 85

  userstore: 18 Overall method count: 204 

Firefly has an acceptable performance. Local process takes several tens of milliseconds when cold booting a service, which thrift code takes several milliseconds. Hot call takes less than one millisecond almost as fast as thrift code. Anyway, the time taken by local process is ignorable, comparing to the time taken by network.

This project is inspired by Square's wire and retrofit, and I shamelessly copy a lot of code from Twitter's scrooge and Google's gson.

Compiling thrift files

Preparation:

• clone this repository
• install sbt

To compile thrift files:

$ cd generator $ sbt 'run [--output <output-dir>] <thrift-file1> [<thrift-file2> ...]'

If you want to generate files with Rx smell or supports Android's Parcelable, just put --rx or --android in the last, like this:

$ cd generator $ sbt 'run [--output <output-dir>] <thrift-file1> [<thrift-file2> ...] --rx --android'

If you generate codes with --android, your project should dependents on com.meituan.firefly:lib-android instead of com.meituan.firefly:library.

Gradle plugin

If you are using Gradle, you may use the Gradle Plugin:

buildscript {

  repositories {

jcenter()
  
}

  dependencies {

classpath 'com.meituan.firefly:gradle-plugin:0.2.4'  
}
 
}
 apply plugin: 'com.meituan.firefly'

you can change the input diretory and output diretory, like this:

apply plugin: 'com.meituan.firefly' apply plugin: 'com.android.library' firefly {

  inputDir file('${
project.projectDir
}
/src/main/idl')
  outputDir file('${
project.buildDir
}
/generated/source/firefly') 
}

• inputDir's default value is '${ project.projectDir } /src/main/idl'
• outputDir's default value is '${ project.buildDir } /generated/source/firefly'
• rxStyle's default value is false
• android's default value is false

Please notice that, the plugin must be declared before plugin com.android.library, com.android.application or java. Pay attention to the arguments rxStyle and android. If you change them, all the output file will be re-generated.

If you want to generate code with rx smell or support android's Parcelable:

apply plugin: 'com.meituan.firefly' apply plugin: 'java' firefly {

  rxStyle true
  android true 
}

The generator assumes that thrift files included by the target thrift file are placed in the same dir of the target thrift file.

Using Firefly in your application

The library package contains runtime support libraries that must be included in applications that use Firefly-generated code.

Include via Maven:

<dependency>
<groupId>com.meituan.firefly</groupId>
<artifactId>library</artifactId>
<version>0.2.4</version> </dependency>

or Gradle:

compile 'com.meituan.firefly:library:0.2.4'

or sbt:

libraryDependencies += "com.meituan.firefly" % "library" % "0.2.4"

Given the following thrift file for example:

namespace java com.meituan.greeting service GreetingService{

  string greet(string name);
 
}
 

It generates an interface named GreetingService.

Use of generated code:

final OkHttpClient okhttpClient = new OkHttpClient();

GreetingService greetingService = Thrift.instance.create(GreetingService.class, new SimpleProtocolFactory(){

  @Override
  public TProtocol get() {

return new TBinaryProtocol(new OkhttpTransport(YOUR_SERVICE_URL, okhttpClient));

  
}
 
}
;  String greeting = greetingService.greet("Han meimei");

Make sure that ProtocolFactory.get() return a new Protocol for each call, or return a same thread-safe Protocol for every call.

Roadmap

• RxJava support
• Gradle Plugin generates codes automatically
• Serializable support
• Android Parcelable support

License

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.