JarCastingeasy-agent
This library was created to easily develop a Java agent that injects proxy code into the class bytecode.
If you write code in Java without needing to know the bytecode instrumentation, it is injected into bytecode.
If you want see more info about this framework, See Github wiki documentation
Table of content
🚀
Summary
From an architectural point of view, the Java agent is a good way to inject logic from outside your application.
Many applications are increasingly using cloud and virtualized environments. In that case, there are times when you need to write code that is infrastructure dependent.
For example, if you need to implement istio distributed tracing, You will write code to propagate HTTP headers inside your application.
However, if you write like this, your application will depend to istio.
If using java agent, infrastructure dependent logic can be managed at the infrastructure level. And independence and reusability increase, because it is injected at the infrastructure layer.
easy-agent helps you develop java agent easily.
🚀
Feature
Fast
easy-agent uses ASM, it is low-level library. ASM provide high performance.
Easy
You don't need to know bytecode transform. You can easily inject a proxy with simple java code.
Productivity
Productivity is improved by placing infrastructure-dependent code at the infrastructure layer.
You don't have to think about infrastructure when developing and deploying applications. Because the infrastructure-dependent logic is injected by the agent.
Extension
easy-agent provides a easy-agent-api that can be easily extended. You can easily develop reusable plugins.
You can see more info in plugin wiki page.
Documentation
We try to give you the most detailed and friendly documentation possible. If there is any room for improvement in the document, please make a suggestion.
🚀
Extend via plugin
You can make reusable easy-agent plugin. it is very simple. See more details
🚀
Quick start
Just follow 6 simple steps.
(1) Add maven dependency to pom.xml
<dependency>
<groupId>software.fitz</groupId>
<artifactId>easy-agent-core</artifactId>
<version>0.4.0-RELEASE</version>
</dependency>
(2) Implements AroundInterceptor
Override only necessary methods.
public class YourInterceptor implements AroundInterceptor {
@Override
public Object[] before(Object target, Method targetMethod, Object[] args) {
// your proxy code
if (args[0] instanceof String) {
args[0] = args[0] + " hi"; // possible replace to target method arguments
}
return args;
}
@Override
public Object after(Object target, Method targetMethod, Object returnedValue, Object[] args) {
// your proxy code
return returnedValue; // possible replace to return value
}
@Override
public void thrown(Object target, Method targetMethod, Throwable t, Object[] args) {
// your proxy code
}
}
(3) Define your plugin & Register interceptor to your target class
public class YourPlugin implements Plugin {
@Override
public void setup(TransformerRegistry transformerRegistry) {
transformerRegistry.register(
TransformDefinition.builder()
// "+" means applies to all classes that extend this class
.transformStrategy(TransformStrategy.className("package.Class+"))
.matchArgs(MethodDefinition.all("targetMethodName"))
.addInterceptor(YourInterceptor.class)
.build()
);
}
}
(4) Define premain class & Register your plugin
public class PremainClass {
public static void premain(String agentArgs, Instrumentation instrumentation) {
EasyAgentBootstrap.initialize(agentArgs, instrumentation)
.addPlugin(new YourPlugin())
.start();
}
}
(5) Add maven plugin to your pom.xml
- Replace
{your-jar-name}with the name of the jar you want. - Replace
{package.to.premain-class}with a class that implements thepremainmethod.
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.2</version>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
<configuration>
<finalName>{your-jar-name}</finalName>
<appendAssemblyId>false</appendAssemblyId>
<archive>
<manifest>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
<addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
</manifest>
<manifestEntries>
<Premain-Class>{package.to.premain-class}</Premain-Class>
<Can-Retransform-Classes>true</Can-Retransform-Classes>
<Can-Redefine-Classes>true</Can-Redefine-Classes>
<Boot-Class-Path>{your-jar-name}.jar</Boot-Class-Path>
</manifestEntries>
</archive>
<descriptorRefs>
<descriptorRef>jar-with-dependencies</descriptorRef>
</descriptorRefs>
</configuration>
</execution>
</executions>
</plugin>
(6) Run with your application
Specify your agent jar in the -javaagent argument.
java -javaagent:/path/{your-agent}.jar -jar target-application.jar
🚀
Example
Example of replacing method arguments.
You can see more examples in wiki page.
AroundInterceptor
public class YourInterceptor implements AroundInterceptor {
@Override
public Object[] before(Object target, Method targetMethod, Object[] args) {
if (args[0] != null && args[0] instanceof String) {
args[0] = args[0] + " Hi!";
}
return args;
}
}
Plugin
The process of registering the module was omitted.
public class YourPlugin implements Plugin {
@Override
public void setup(TransformerRegistry transformerRegistry) {
transformerRegistry.register(
TransformDefinition.builder()
.transformStrategy(TransformStrategy.className("package.TargetClass"))
.addTargetMethod(matchArgs("printName", String.class))
.addInterceptor(YourInterceptor.class)
.build()
);
}
}
Target class & Main class
public class TargetClass {
public void printName(String name) {
System.out.println(name);
}
public static void main(String[] args) {
new TargetClass().printName("joongsoo");
}
}
Execute result
joongsoo Hi!