Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jakewharton/overloadreturn

Bytecode rewriter that creates overloads of methods which vary only by return type.
https://github.com/jakewharton/overloadreturn

Last synced: 13 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
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.



```java

@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, ACC_BRIDGE

  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.



```java

public void remove(K key) {

  // ...

}

```



can be changed to



```java

@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 could not 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.



```groovy

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



You can build the CLI by running `./gradlew :overload-return-compiler:assemble`. Archives will be

available in `overload-return-compiler/build/distributions/` or an exploded copy is available at

`overload-return-compiler/build/install/`.



The CLI takes two arguments: the root directory of class files to read and the output directory

where processed class files will be written.



```

$ overload-return-compiler --help

Usage: overload-return-compiler [OPTIONS] INPUT OUTPUT



Options:

  --debug     Show debug information while processing

  -h, --help  Show this message and exit



Arguments:

  INPUT   Directory containing class files and resources

  OUTPUT  Directory for processed class files and resources

```



### Other



The compiler is available as a Java API for integration into any system where a CLI isn't desired.



```java

OverloadReturnCompiler compiler = new OverloadReturnCompiler();

byte[] inputBytes = // ...

byte[] outputBytes = compiler.parse(inputBytes).toBytes();

```



You can also process an entire input directory to an output directory just like the CLI.



```java

OverloadReturnCompiler compiler = new OverloadReturnCompiler();

Path inputDir = // ...

Path outputDir = // ...

compiler.processDirectory(inputDir, outputDir);

```



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.