GitHub - JakeWharton/OverloadReturn: Bytecode rewriter that creates overloads of...
source link: https://github.com/JakeWharton/OverloadReturn
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK