Surgeon

English | 中文

Lib	surgeon-plugin	surgeon-compile
latest	1.0.3	1.0.1

Surgeon is a hot function replace framework for Android which was simple to use,flexible,high-performance.

Integration

//add plugin
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.tangxiaolv.surgeon:surgeon-plugin:1.0.3'
    }
}

//use plugin
apply plugin: 'com.android.library'
apply plugin: 'com.tangxiaolv.surgeon'

or

apply plugin: 'com.android.application'
apply plugin: 'com.tangxiaolv.surgeon'

//add annotationProcessor
dependencies {
    annotationProcessor 'com.tangxiaolv.surgeon:surgeon-compile:1.0.1'
}

Getting Started

1.Add annotation on target function

package com.tangxiaolv.sdk;
public class SDKActivity extends AppCompatActivity {
    //namespace usually is packageName + className,Also can define any string if you want. 
    //function function name,usually is current function name,Also can define any string if you want. 
    //namespace + function must unique
    @ReplaceAble(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getTwo")
    private String getTwo() {
        return "TWO";
    }
}

2.Add annotation on replace function

//Create ISurgeon subclass.
public class HotReplace implements ISurgeon {

    @Override
    public boolean singleton() {
        return false;
    }
    
    @Replace(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getTwo")
    public String getTwo(TargetHandle handle) {
        return "getTwo from HotReplace2";
    }
}

Advance

Target function

package com.tangxiaolv.sdk;
public class SDKActivity extends AppCompatActivity {

    @ReplaceAble(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getTwo")
    private String getTwo() {
        return "TWO";
    }
    
    @ReplaceAble(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getTwo.text")
    private String getTwo(String text) {
        return text;
    }
    
    @ReplaceAble(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getThree")
    private String getThree(String text) {
        return "getThree_"+text;
    }
}

1.Static Replace

public class HotReplace implements ISurgeon {
    @Override
    public boolean singleton() {
        return false;
    }

    //called before target function call
    //target : target function owner object
    @ReplaceBefore(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getTwo")
    public void getTwoBefore(Object target) {
    }
    
    //replace target function
    //handle :You can invoke target function or get target function owner by handler.
    @Replace(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getTwo")
    public String getTwo(TargetHandle handle) {
        return "getTwo from remote";
    }
    
    //replace target override function
    //handle :You can invoke target function or get target function owner by handler.
    @Replace(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getTwo.text")
    public String getTwo(TargetHandle handle,String text/**target params*/) {
        return "getTwo from remote";
    }
    
    //called after target function call
    //target : target function owner object
    @ReplaceAfter(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getTwo")
    public void getTwoAfter(Object target) {
    }
    
    //replace target function
    @Replace(namespace = "com.tangxiaolv.sdk.SDKActivity", function = "getThree")
    public String getThree(TargetHandle handle, String text) throws Throwable {
        String newText = text + "_hack!";
        //invoke origin method with new params
        return (String) handle.proceed(newText);
    }
}

1.Runtime Replace

//replace return value for target function
Surgeon.replace("com.tangxiaolv.sdk.SDKActivity.getTwo", "Runtime result");

//replace return value for target override function 
Surgeon.replace("com.tangxiaolv.sdk.SDKActivity.getTwo.text", "Runtime result");

//replace target function
Surgeon.replace("com.tangxiaolv.sdk.SDKActivity.getTwo", new ReplacerImpl<String>(){
    //params[0] = function owner's object,The other is origin params 
    @Override
    public void before(Object[] params) {
        super.before(params);
    }

    //params[0] = TargetHandle,The other is origin params
    @Override
    public String replace(Object[] params) {
        return super.replace(params);
    }

    //params[0] = function owner's object,The other is origin params
    @Override
    public void after(Object[] params) {
        super.after(params);
    }
});

ProGuard

-keep class * implements com.surgeon.weaving.core.interfaces.ISurgeon{*;}
-keep class * implements com.surgeon.weaving.core.interfaces.IMaster{*;}

License