{"id":19017461,"url":"https://github.com/junkdog/graftt","last_synced_at":"2025-04-23T02:52:39.945Z","repository":{"id":57737539,"uuid":"187469352","full_name":"junkdog/graftt","owner":"junkdog","description":"annotation-driven bytecode surgery","archived":false,"fork":false,"pushed_at":"2020-10-13T14:08:30.000Z","size":5563,"stargazers_count":8,"open_issues_count":7,"forks_count":2,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-04-17T18:23:45.365Z","etag":null,"topics":["bytecode-instrumentation","bytecode-manipulation","javaagent","metaprogramming","monkey-patching"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/junkdog.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-19T11:44:01.000Z","updated_at":"2023-09-24T13:22:24.000Z","dependencies_parsed_at":"2022-08-24T14:59:43.012Z","dependency_job_id":null,"html_url":"https://github.com/junkdog/graftt","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fgraftt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fgraftt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fgraftt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junkdog%2Fgraftt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/junkdog","download_url":"https://codeload.github.com/junkdog/graftt/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250360259,"owners_count":21417718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bytecode-instrumentation","bytecode-manipulation","javaagent","metaprogramming","monkey-patching"],"created_at":"2024-11-08T19:47:06.180Z","updated_at":"2025-04-23T02:52:39.899Z","avatar_url":"https://github.com/junkdog.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# graftt - annotation-driven bytecode surgery \n\nRewrite existing classes by grafting bytecode from *Transplant* classes. Transplants are\nplain java classes and function like templates or patches; annotations define interactions\nwith the recipient class. The entire API consists of 4 annotations.\n\nTransplants have complete access to the recipient class: Existing methods can be wrapped,\nchanged or replaced entirely. Interfaces can be retrofitted and additional fields added.\nUpdate annotations on classes, methods and fields.\n \nAn agent (`java -javaagent`) applies transplants at load-time. Alternatively, \n`graftt-maven-plugin` finds and applies transplants within `target/classes`.  \n\nThe `core` module can be used for building custom tools. It imposes few restrictions on\nusage and revolves around [ASM's](https://asm.ow2.io/) tree API. \n\n_graftt_ sprung from [artemis-odb/570](https://github.com/junkdog/artemis-odb/issues/570),\nrefer to it for the discussion leading up to this.\n\nSee [wiki](https://github.com/junkdog/graftt/wiki) for more documentation.\n\n## Use-cases\n- Functionality for editors: callbacks and tighter tooling integration\n- Additional debugging capabilities: logging, record stack traces, additional callbacks\n- Extending existing functionality for final or otherwise non-extendable classes\n- The odd bug fix in imported dependencies\n- Add or modify `hashcode()` and `toString()`\n- Retrofit classes with additional interfaces \n\n\n## Example Transplant for SomeClass\n\n### A third-party class we wish to modify\n\n```java\npublic class SomeClass {\n    public final void yo() {\n        yolo();\n    }\n\n    private void yolo() {\n        // boo! we want to call \"invokedWithTransplant = true\"\n        // here (for some reason or other), but yo() is final\n        // and can't be extended, and this method is private\n        //\n        // ...\n        //\n        yoloCalled = true;\n    }\n\n    public boolean yoloCalled = false;\n    public static boolean invokedWithTransplant = false;\n}\n```\n\n### Create a _transplant_ class to donate some bytecode \n\n```java\n@Graft.Recipient(SomeClass.class) // target to modify\npublic class SomeClassTransplant {\n    \n    @Graft.Fuse // fuse with method in SomeClass\n    private void yolo() { // signature matches SomeClass.yolo()\n        SomeClass.invokedWithTransplant = true; // whoop-whoop \n        yolo(); // \"recursive continuation\", actually invokes SomeClass::yolo  \n    }\n}\n```\n\n### Resulting class\n\nOnce transplanted, decompiling the modified class yields something similar to:\n\n```java\npublic class SomeClass {\n    public final void yo() {\n        yolo();\n    }\n\n    private void yolo() {\n        SomeClass.invokedWithTransplant = true;\n        yolo$original();\n    }\n\n    private void yolo$original() {\n        yoloCalled = true;\n    }\n\n    public boolean yoloCalled = false;\n    public static boolean invokedWithTransplant = false;\n}\n```\n\n\n## API \n\n- **`@Graft.Recipient`** specifies which class to transplant to.\n- **`@Graft.Fuse`** transplants bytecode over to `@Graft.Recipient`, translating any\n  `FooTransplant` references to `Foo`. Call the original method at any time by invoking the\n  method currently being fused; e.g. Fusing `FooTransplant::bar` with `Foo::bar`, any\n  call to `bar()` inside the transplant will point to `Foo::bar$original` once applied.\n- **`@Graft.Mock`** to keep the compiler happy when you need to reference fields or\n  methods in the target class. Mocked references point to target class after transplant.\n- **`@Graft.Annotations`** overrides default configuration for removal and updating of\n  annotations. The default behavior copies all annotations from the transplanted elements\n  to the recipient.\n- Interfaces implemented by the transplant are added to the recipient.\n- All fields and methods, except those annotated with `@Graft.Mock`, are copied to recipient.\n\nNice to have, but not now:\n- **`@Graft.Remove`**: Remove field or method from target class.\n\n## Caveats\n- You're working against internal implementation; there are no semver guarantees\n- No rewiring of parent type on target class\n- No `@Graft.Fuse` for constructors; nice to have, but not initially\n- No GWT support\n- No android support (possible with a custom gradle task)\n\n## Usage\n\nCurrent `$VERSION` is `0.3.0`\n\n### Maven\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003enet.onedaybeard.graftt\u003c/groupId\u003e\n    \u003cartifactId\u003eapi\u003c/artifactId\u003e\n    \u003cversion\u003e${VERSION}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Gradle\n\n```groovy\nimplementation \"net.onedaybeard.graftt:api:${VERSION}\"\n```\n\n### Agent: Download\n\n`$ java -ea -javaagent:agent-${VERSION}.jar` ...\n\n - [Snapshot](https://oss.sonatype.org/content/repositories/snapshots/net/onedaybeard/graftt/agent/) \n - [Release](https://repo1.maven.org/maven2/net/onedaybeard/graftt/agent) \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunkdog%2Fgraftt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjunkdog%2Fgraftt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunkdog%2Fgraftt/lists"}