Often, when I hear people discussing what programming language is the “best” or what to choose for their brand-new backend, Java comes up as an obvious candidate. Yet I also often hear it described as “too complicated”, “bloated”, and “too magical”. But is that really fair? With a little bit of “magic”, some of your work can be much simplified — that’s the whole point! Have you ever wondered if you could use some of this magic yourself? Well, I think it’s probably easier than you think!
As an example, I will use Quarkus, as its extensions provide a well-structured and somewhat documented framework to do that, though of course, nothing prevents you from using any other library like ByteBuddy to do all the transformations manually in the runtime.
I will do a quick introduction of what Quarkus and its extensions are, along with a couple of examples of extensions that I would consider quite interesting.
What are Quarkus extensions?
The main selling point of Quarkus is its faster startup and lower footprint compared to other Java frameworks, and it achieves that by moving all the work that Spring and others do during runtime to its own “build” phase. And all that work that happens is done by Quarkus extensions.
At their core, Quarkus extensions contain BuildSteps that consume and produce BuildItems. That’s it! Quarkus will automatically resolve the dependencies between them and run the build steps in the correct order. Some of these build items are quite magical; for example, to create a new bean, all we need to do is produce a GeneratedBeanBuildItem, and there also exists bytecode recording, that seems to be used mostly for runtime initialization of the extension, but we won’t need that for our purposes.
I won’t dig too deep into the details. This is mostly a practical article from a point of view of someone who tried to write a couple of Quarkus extensions of my own to get rid of some boilerplate, and wants to share the less-obvious things with the internet. If you want to learn more about Quarkus, please enjoy the additional links section below.
Creating a Quarkus extension
It is very simple to create a Quarkus extension, we can just use the provided maven script to help us get started:
mvn io.quarkus.platform:quarkus-maven-plugin:3.17.6:create-extension -N \
-DgroupId=org.acme -DextensionId=quarkus-extension-playgroundCode language: Shell Session (shell)The “Building my first extension” guide tells us to disable test generation as well, but we will see that we actually want them soon. This will generate an additional integration-tests maven module, where we will able to use and test our extension as if it were used by its end user. For some reason, this module isn’t included in the parent pom.xml by default, so let’s do just that.
<modules>
<module>deployment</module>
<module>runtime</module>
+ <module>integration-tests</module>
</modules>Code language: Diff (diff)Also, you might notice that the extension has two modules: deployment and runtime. Short explanation for that is that “runtime” module contains everything that will be available directly to the user of your extension, and “deployment” module contains build-time only code (such as the mentioned BuildSteps).
Generating interface implementations
Let’s start with a basic “Hello world”! We will create an interface that should return a greeting with a provided name, and create an implementation of that interface in a Quarkus extension.
First, let’s create this interface. It has to be in the “runtime” module, as the end user will have to use it when specifying an injection point.
package org.acme.quarkus.extension.playground.runtime;
// Imports omitted
public interface HelloGenerator {
String generate(String name);
}
Code language: Java (java)Now, in build-time, we should create a bean implementing our interface, that has a method that takes two strings and concatenates them, and let Quarkus CDI know about it. It shouldn’t be anything groundbreaking, as creation of beans is already well described in the Extensions & CDI Quarkus FAQ, with a couple of method calls using Gizmo.
Note that we’re not really writing Java code, but using Quarkus’ Gizmo library to generate JVM bytecode directly, so the syntax is more verbose than simply writing "Hello " + name. But with the help of the provided documentation, the resulting code looks rather straightforward: in our deployment module, we need to create a BuildStep that will generate a GeneratedBeanBuildItem, containing our implementation.
package org.acme.quarkus.extension.playground.deployment;
// Imports omitted
public class HelloGeneratorProcessor {
@BuildStep
void generateImplementation(BuildProducer<GeneratedBeanBuildItem> generatedBean) {
var gizmoAdapter = new GeneratedBeanGizmoAdaptor(generatedBean);
try (ClassCreator classCreator = ClassCreator.builder()
.className("org.acme.quarkus.extension.playground.deployment.HelloGeneratorImpl")
.interfaces(HelloGenerator.class)
.classOutput(gizmoAdapter)
.build()) {
// Can also be ApplicationScope
classCreator.addAnnotation(Singleton.class);
// Implement our method
try (MethodCreator methodCreator = classCreator.getMethodCreator("generate", String.class, String.class)) {
// Manually concatenate the strings using the String.concat method
// Gizmo's StringBuilderGenerator could also be used
var method = MethodDescriptor.ofMethod(String.class, "concat", String.class, String.class);
var name = methodCreator.getMethodParam(0);
var prefix = methodCreator.load("Hello ");
var concatenated = methodCreator.invokeVirtualMethod(method, prefix, name);
methodCreator.returnValue(concatenated);
}
}
}
}
Code language: Java (java)Another limitation of what we’re doing here is that we can’t really use anything we create directly from our Java code — if we want to run our code, it has to implement some existing interface; we can’t import our dynamically generated code. For some purposes, this might not be enough — one option to create “real” Java code would be to use annotation processors instead.
Then, let’s write a simple test that this thing actually works in our integration-tests module:
package org.acme.quarkus.extension.playground.it;
// Imports omitted
@QuarkusTest
public class HelloWorldTest {
@Inject
HelloGenerator helloGenerator;
@Test
void testHello() {
String hello = helloGenerator.generate("World");
Assertions.assertEquals("Hello World", hello);
}
}
Code language: Java (java)Running the tests via Maven, or your favorite IDE, all of our tests should be green. (Though in my experience, IntelliJ has been quite finicky with this; the most sure way to run it for me has been the test target of the top-level pom.)
Generating generic interface implementations
If we want even more fun, we can also try generating implementations of parametrized interfaces for specific types. For example, this can be a de/serializer, and in this relatively simple example, we are going to write something that looks like a rather useless serializer.
Like before, let’s first create an interface:
package org.acme.quarkus.extension.playground.runtime;
// Imports omitted
public interface HelloGeneratorGeneric<T> {
String generate(T name);
}
Code language: Java (java)But how are we going to generate the generic implementations? Or, even before that, for what are we going to generate the implementations? For an answer to this question, let’s create a marker annotation and generate implementations for all the annotated classes.
package org.acme.quarkus.extension.playground.runtime;
@Retention(RetentionPolicy.CLASS)
public @interface HelloTarget {
}
Code language: Java (java)Then, we need to find all the annotated classes in our code. This can be done with the help of the ApplicationIndexBuildItem. Let’s write a build step that will find everything, do some preprocessing on the found classes, and then make another BuildItem with all the information required to generate an implementation.
package org.acme.quarkus.extension.playground.deployment;
// Imports omitted
public final class HelloGenericTypeBuildItem extends MultiBuildItem {
public final ClassInfo klass;
public HelloGenericTypeBuildItem(ClassInfo klass) {
this.klass = klass;
}
}
Code language: Java (java)And then, the required processing. Which is not much.
@BuildStep
void findAnnotations(ApplicationIndexBuildItem jandex, BuildProducer<HelloGenericTypeBuildItem> producer) {
var annot = jandex.getIndex().getAnnotations(HelloTarget.class);
for (var a : annot) {
if (a.target().kind() != AnnotationTarget.Kind.CLASS) {
continue;
}
producer.produce(new HelloGenericTypeBuildItem(a.target().asClass()));
}
}
Code language: Java (java)And, of course, actually generate the implementations. Let’s make a really bad “serializer” of the object: create a string with all the fields of the object and their values.
@BuildStep
void generateImplementations(BuildProducer<GeneratedBeanBuildItem> generatedBeans, List<HelloGenericTypeBuildItem> types) {
for (var type : types) {
var gizmoAdapter = new GeneratedBeanGizmoAdaptor(generatedBeans);
var targetType = Type.classType(type.klass.name());
var implType = Type.ParameterizedType.parameterizedType(
Type.classType(HelloGeneratorGeneric.class),
targetType);
try (ClassCreator classCreator = ClassCreator.builder()
.className("org.acme.quarkus.extension.playground.deployment." + type.klass.simpleName() + "GeneratorImpl")
// TODO: How to tell the JVM we are implementing a generic interface?
.classOutput(gizmoAdapter)
.setFinal(true)
.build()) {
classCreator.addAnnotation(Singleton.class);
try (var methodCreator = classCreator.getMethodCreator("generate", String.class, Object.class)) {
var arg = methodCreator.getMethodParam(0);
var sb = Gizmo.newStringBuilder(methodCreator);
sb.append(methodCreator.load("Hello,"));
for (var field : type.klass.fields()) {
var fieldVal = methodCreator.readInstanceField(field, arg);
sb.append(methodCreator.load("\n" + field.name() + ": "));
sb.append(fieldVal);
}
methodCreator.returnValue(sb.callToString());
}
}
}
}
Code language: Java (java)The tricky thing here is to ensure all types have correct… types and we don’t lose or break everything when converting between different types of types! There can be three! java.lang.reflect.Type, io.quarkus.gizmo.Type, and org.jboss.jandex.Type. And, of course, their slightly different ParametrizedType friends. Also, note that due to type erasure, we’re implementing a method that takes an Object as its argument, not our “real” type.
Yet there is one problem left: how do we tell the JVM that our class is an implementation of a generic interface? Let’s try to make our own implementation and see what bytecode javac generates:
package org.acme.quarkus.extension.playground;
// Imports omitted
public class HelloWorldImplementationManual implements HelloGeneratorGeneric<DataType> {
@Override
public String generate(DataType name) {
return "Hello " + name.name;
}
}
Code language: Java (java)Then, we can print the compiled classfile contents using javap -v
# javap -v org.acme.quarkus.extension.playground.HelloWorldImplementationManual
...
public class org.acme.quarkus.extension.playground.HelloWorldImplementationManual extends java.lang.Object implements org.acme.quarkus.extension.playground.runtime.HelloGeneratorGeneric<org.acme.quarkus.extension.playground.DataType>
{
...Code language: Shell Session (shell)So, we see that the generic information is, indeed, contained in the classfile, but how? We can get a hint right at the end of the output.
...
}
Signature: #34 // Ljava/lang/Object;Lorg/acme/quarkus/extension/playground/runtime/HelloGeneratorGeneric<Lorg/acme/quarkus/extension/playground/DataType;>;
...Code language: Shell Session (shell)It seems that the generic information is contained in some kind of signature, but not just some “signature” as in “something that defines the inputs and outputs of a function, subroutine or method”. Because our class isn’t a function, right? This is “signature” as in “something that encodes declarations written in the Java programming language that use types outside the type system of the Java Virtual Machine”. Which in that case, means the fact that this class implements a parametrized interface.
Yet it is still not quite obvious how to generate this information with Gizmo. After much trial and error, I’ve found out that it can be generated with aptly named SignatureBuilder with the provided correct ParametrizedType.
Complete code of HelloGenericGeneratorProcessor
package org.acme.quarkus.extension.playground.deployment;
// Imports omitted
public class HelloGenericGeneratorProcessor {
@BuildStep
void findAnnotations(ApplicationIndexBuildItem jandex, BuildProducer<HelloGenericTypeBuildItem> producer) {
var annot = jandex.getIndex().getAnnotations(HelloTarget.class);
for (var a : annot) {
if (a.target().kind() != AnnotationTarget.Kind.CLASS) {
continue;
}
producer.produce(new HelloGenericTypeBuildItem(a.target().asClass()));
}
}
@BuildStep
void generateImplementations(BuildProducer<GeneratedBeanBuildItem> generatedBeans, List<HelloGenericTypeBuildItem> types) {
for (var type : types) {
var gizmoAdapter = new GeneratedBeanGizmoAdaptor(generatedBeans);
var targetType = Type.classType(type.klass.name());
var implType = Type.ParameterizedType.parameterizedType(
Type.classType(HelloGeneratorGeneric.class),
targetType);
try (ClassCreator classCreator = ClassCreator.builder()
.className("org.acme.quarkus.extension.playground.deployment." + type.klass.simpleName() + "GeneratorImpl")
.signature(SignatureBuilder.forClass().addInterface(implType))
.classOutput(gizmoAdapter)
.setFinal(true)
.build()) {
classCreator.addAnnotation(Singleton.class);
try (var methodCreator = classCreator.getMethodCreator("generate", String.class, Object.class)) {
var arg = methodCreator.getMethodParam(0);
var sb = Gizmo.newStringBuilder(methodCreator);
sb.append(methodCreator.load("Hello,"));
for (var field : type.klass.fields()) {
var fieldVal = methodCreator.readInstanceField(field, arg);
sb.append(methodCreator.load("\n" + field.name() + ": "));
sb.append(fieldVal);
}
methodCreator.returnValue(sb.callToString());
}
}
}
}
}
Code language: Java (java)And, of course, a simple test that the above code doesn’t do anything crazy.
@Inject
HelloGeneratorGeneric<DataType> helloGeneratorGeneric;
@Test
void testHelloGeneric() {
DataType dataType = new DataType();
dataType.name = "World";
String hello = helloGeneratorGeneric.generate(dataType);
Assertions.assertEquals("Hello,\nname: World", hello);
}
Code language: Java (java)Modifying bytecode using Gizmo
Sometimes we might also want to modify the existing bytecode of some method. For example, starting, committing, and rolling back a transaction — boilerplate code, that would certainly be quite nice to not write every single time! For this exact purpose, the @Transactional annotation exists, which… At least for me, doesn’t do what I at first expected from it! In Spring, by default, this annotation does not change the bytecode of the method, but only changes the behavior of the bean’s proxy. So if you call a method annotated with @Transactional from within the bean itself, nothing will happen! Apparently, Quarkus still supports it, though this is not defined behavior according to the CDI standard, and so does Spring when using the “AspectJ mode” of annotation-driven transaction management.
So let’s try to make our own implementation that works as we expect it to! All we need to do is to wrap the annotated method body with a try/catch block, and call a couple of methods there. Something like this:
T wrapperFn() {
tx.start();
try {
T ret = originalFn();
tx.commit();
return ret;
} catch (Exception e) {
tx.rollback();
throw e;
}
}Code language: Java (java)First, let’s see what the documentation says about what we want to do. Apparently, to modify class bytecode, we need to produce a BytecodeTransformerBuildItem, containing an ASM ClassVisitor and Quarkus will handle the rest. It also links to a simple example on how we can filter methods from classes, but we want something more advanced! Unfortunately the straightforward idea of literally wrapping the method body has a not-so-straightforward implementation. I have not found an easy way of telling ASM to “emit original method body”. How the original method body appears in the rewritten bytecode can be found in ASM’s ClassReader.readMethod:
public class ClassReader {
private int readMethod(
final ClassVisitor classVisitor, final Context context, final int methodInfoOffset) {
// ...
// Visit the Code attribute.
if (codeOffset != 0) {
methodVisitor.visitCode();
readCode(methodVisitor, context, codeOffset);
}
// Visit the end of the method.
methodVisitor.visitEnd();
}
Code language: Java (java)As you can see, first it calls our visitCode visitor, then actually reads the bytecode contents (the readCode function reads the original bytecode and “copies” it to our method visitor). Importantly, at the end of readCode there is a call to methodVisitor.visitMaxs to set the correct number for max stack/local variables in the method. Quarkus configures the ClassWriter to compute them, which for us means that the method’s bytecode must be well formed at the end of readCode, therefore we can’t just put “first half” of try/catch in our visitCode visitor, and second half in visitEnd visitor. Besides that, we would also have to somehow handle saving function return value and transaction commit.
ClassTransformingBuildStep.transformClass source in Quarkus 3.17.6
private byte[] transformClass(String className, List<BiFunction<String, ClassVisitor, ClassVisitor>> visitors,
byte[] classData, List<BiFunction<String, byte[], byte[]>> preVisitFunctions, int classReaderOptions) {
for (BiFunction<String, byte[], byte[]> i : preVisitFunctions) {
classData = i.apply(className, classData);
if (classData == null) {
return null;
}
}
byte[] data;
if (!visitors.isEmpty()) {
ClassReader cr = new ClassReader(classData);
ClassWriter writer = new QuarkusClassWriter(cr,
ClassWriter.COMPUTE_FRAMES | ClassWriter.COMPUTE_MAXS);
ClassVisitor visitor = writer;
for (BiFunction<String, ClassVisitor, ClassVisitor> i : visitors) {
visitor = i.apply(className, visitor);
if (visitor instanceof QuarkusClassVisitor) {
((QuarkusClassVisitor) visitor).setOriginalClassReaderOptions(classReaderOptions);
}
}
cr.accept(visitor, classReaderOptions);
data = writer.toByteArray();
} else {
data = classData;
}
if (BootstrapDebug.DEBUG_TRANSFORMED_CLASSES_DIR != null) {
File debugPath = new File(BootstrapDebug.DEBUG_TRANSFORMED_CLASSES_DIR);
if (!debugPath.exists()) {
debugPath.mkdir();
}
File classFile = new File(debugPath, fromClassNameToResourceName(className));
classFile.getParentFile().mkdirs();
try (FileOutputStream classWriter = new FileOutputStream(classFile)) {
classWriter.write(data);
} catch (Exception e) {
log.errorf(e, "Failed to write transformed class %s", className);
}
log.infof("Wrote transformed class to %s", classFile.getAbsolutePath());
}
return data;
}
Code language: Java (java)Thankfully, there is a much easier solution! If we look at the proposed pseudocode of “what we want to do”, we see a nice, simple function call to originalFn(). Could we do literally that? We can, and there’s even an example in Quarkus’ Gizmo documentation on how to do it!
In short, we rename the original method to something like <name>$original and then create a method with the same signature as the original, except that it just wraps the copied original method. And that’s it! We still need to forward the arguments to this function, but this isn’t too hard as Gizmo’s invocation methods take arguments as their vararg argument, which is just syntactic sugar for arrays. So we can just “load” the arguments into an array and pass the handles there. Similarly, for return values, we just take the result of the invocation and return it. No need to handle any special cases — it just works!
So, let’s get to work implementing this!
First, let’s create a marker interface @Wrapped, which we could put on methods that we want to wrap.
package org.acme.quarkus.extension.playground.runtime;
// Imports omitted
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.METHOD)
public @interface Wrapped {
}
Code language: Java (java)Then, for simplicity, let’s create Wrapper and WrapperStatic classes, containing the functions we will call from the modified bytecode.
package org.acme.quarkus.extension.playground.runtime;
// Imports omitted
public class WrapperStatic {
public static void start() {
CDI.current().select(Wrapper.class).get().start();
}
public static void commit() {
CDI.current().select(Wrapper.class).get().commit();
}
public static void revert() {
CDI.current().select(Wrapper.class).get().revert();
}
}
Code language: Java (java)package org.acme.quarkus.extension.playground.runtime;
// Imports omitted
@ApplicationScoped
@Unremovable
public class Wrapper {
public void start() {
Log.info("Start called");
}
public void commit() {
Log.info("Commit called");
}
public void revert() {
Log.info("Revert called");
}
}
Code language: Java (java)We could also modify the holder of @Wrapped method, adding an injected Wrapper instance, but for simplicity I’ve chosen this approach.
Also note the @Unremovable annotation for the Wrapper class, as otherwise Quarkus would remove it from our application, as it wouldn’t be able to find any places where it’s injected: programmatic lookup doesn’t count! We also will need to make Quarkus index our runtime module for beans, for example by creating an empty META-INF/beans.xml file inside of its resources folder.
With all the preparation done, we can finally write the proccesor itself:
package org.acme.quarkus.extension.playground.deployment;
// Imports omitted
public class WrapperProcessor {
@BuildStep
void transform(ApplicationIndexBuildItem jandex, BuildProducer<BytecodeTransformerBuildItem> bytecodeTransformers) {
var annot = jandex.getIndex().getAnnotations(Wrapped.class);
for (var a : annot) {
var target = a.target().asMethod();
var targetClass = target.declaringClass();
ClassTransformer ct = new ClassTransformer(targetClass.name().toString());
// Rename original method
ct.modifyMethod(MethodDescriptor.of(target)).rename(target.name() + "$original");
// Create a wrapper method in place of the original one
try (var methodCreator = ct.addMethod(MethodDescriptor.of(target))) {
methodCreator.invokeStaticMethod(MethodDescriptor.ofMethod(WrapperStatic.class, "start", void.class));
var tryBlock = methodCreator.tryBlock();
// Wrap original method parameters
var passedArgs = new ResultHandle[target.parameters().size()];
for (int i = 0; i < target.parameters().size(); i++) {
passedArgs[i] = tryBlock.getMethodParam(i);
}
var originalDescriptor = MethodDescriptor.ofMethod(targetClass.name().toString(),
target.name() + "$original", target.returnType().name().toString());
// Call the original method
var returned = tryBlock.invokeVirtualMethod(originalDescriptor, tryBlock.getThis(), passedArgs);
tryBlock.invokeStaticMethod(MethodDescriptor.ofMethod(WrapperStatic.class, "commit", void.class));
tryBlock.returnValue(returned);
var catchBlock = tryBlock.addCatch(Throwable.class);
catchBlock.invokeStaticMethod(MethodDescriptor.ofMethod(WrapperStatic.class, "revert", void.class));
catchBlock.throwException(catchBlock.getCaughtException());
}
bytecodeTransformers.produce(new BytecodeTransformerBuildItem.Builder()
.setClassToTransform(target.declaringClass().toString())
.setVisitorFunction((ignored, visitor) -> ct.applyTo(visitor))
.build());
}
}
}
Code language: Java (java)And, of course, test it in our integration-tests module.
Let’s create some example methods:
package org.acme.quarkus.extension.playground;
// Imports omitted
@ApplicationScoped
public class DemoWrappedClass {
@Wrapped
public void empty() {
}
@Wrapped
public String returnString() {
return "Hello";
}
@Wrapped
public void throwException() {
throw new RuntimeException("Exception");
}
}
Code language: Java (java)And the test itself:
package org.acme.quarkus.extension.playground.it;
// Imports omitted
@QuarkusTest
public class WrappedTest {
@Inject
DemoWrappedClass demoWrappedClass;
@InjectMock
Wrapper wrapper;
@Test
void testReturn() {
Assertions.assertEquals("Hello", demoWrappedClass.returnString());
Mockito.verify(wrapper, Mockito.times(1)).start();
Mockito.verify(wrapper, Mockito.times(1)).commit();
Mockito.verify(wrapper, Mockito.times(0)).revert();
}
@Test
void testEmpty() {
demoWrappedClass.empty();
Mockito.verify(wrapper, Mockito.times(1)).start();
Mockito.verify(wrapper, Mockito.times(1)).commit();
Mockito.verify(wrapper, Mockito.times(0)).revert();
}
@Test
void testException() {
Assertions.assertThrows(RuntimeException.class, () -> demoWrappedClass.throwException());
Mockito.verify(wrapper, Mockito.times(1)).start();
Mockito.verify(wrapper, Mockito.times(0)).commit();
Mockito.verify(wrapper, Mockito.times(1)).revert();
}
}
Code language: Java (java)If everything is correct, the tests should be green, and we can be happy and enjoy the results of our hard work!
Wrap-up
I hope this post was both useful and interesting for you! The complete source code for everything discussed is available here. And, of course, if something isn’t clear, or you see some inaccuracies or other possible improvement, please leave a comment below!
Additional links
Even more useful resources about Quarkus extensions!
- Quarkus documentation: Building my first extension
- Quarkus documentation: Writing Your Own Extension
- Quarkus documentation: CDI Integration Guide
- Quarkus Gizmo manual
- Developing a Quarkus Extension – matheuscruz.dev
- Solving problems with Quarkus extensions (1/n)
- Leveraging Quarkus build-time metaprogramming capabilities to improve Jackson’s serialization performance
- Resources for Writing Quarkus Extensions
Leave a Reply