Bytecode rewriter that creates overloads of methods which vary only by return type.
Clone or download

README.md

Overload Return

An annotation and bytecode rewriter that creates overloads of methods which vary only by return type. This is not legal in source but is perfectly valid in bytecode.

@OverloadReturn(CharSequence.class)
public String greeting() {
  return "Hi";
}

will produce the following bytecode:

public java.lang.String greeting();
  descriptor: ()Ljava/lang/String;
  flags: ACC_PUBLIC
  Code:
    stack=1, locals=1, args_size=1
       0: ldc #2    // String hello
       2: areturn
    LineNumberTable:
      line 5: 0

public java.lang.CharSequence greeting();
  descriptor: ()Ljava/lang/CharSequence;
  flags: ACC_PUBLIC, ACC_SYNTHETIC
  Code:
    stack=1, locals=1, args_size=1
       0: aload_0
       1: invokevirtual #3    // Method greeting:()Ljava/lang/String;
       4: areturn

The second method will be generated by the compiler. It is marked as synthetic so that it does not show up in the IDE to consumers. The annotation is also removed from the original method leaving no runtime trace of the tool.

This is useful for migrating a public API without breaking binary compatibility with old clients.

For example, a method which previously was declared as void can be updated to return a value.

public void remove(K key) {
  // ...
}

can be changed to

@OverloadReturn(void.class)
public V remove(K key) {
  // ...
  return oldValue;
}

Since the method previously had a return type of void, this will be both a source- and binary-compatible change (since the method couldn't be used as an expression).

TODO reference return type migration advice

TODO primitive return type migration advice

Usage

The annotation is available in an artifact at the Maven coordinates com.jakewharton.overloadreturn:overload-return-annotations.

This artifact can be added as compileOnly (Gradle) or provided (Maven) so that it does not wind up in the final artifact if desired.

Android Gradle Plugin

Add and apply the plugin to any library or application module and it will automatically register itself as a transform.

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath 'com.android.tools.build:gradle:…'
    classpath 'com.jakewharton.overloadreturn:overload-return-gradle-plugin:…'
  }
}

apply plugin: 'com.android.library' // or .application
apply plugin: 'com.jakewharton.overloadreturn'

Command Line

TODO CLI

Other

TODO see command line or integrate yourself

License

Copyright 2018 Jake Wharton

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.