Understanding Generics in Quarkus

Oct 13, 2025 by wbrum.org 90 views

Introduction

Quarkus is a modern Java framework that allows developers to build high-performance, container-friendly applications. One of the key features of Quarkus is its ability to create synthetic beans, which are beans that are created at build time rather than runtime. However, when trying to use generics in synthetic bean creation, developers may encounter issues. In this article, we will explore the problem of using generics in a Quarkus build step when creating a synthetic bean.

The Problem

When trying to create a synthetic bean that uses generics, the following code may be used:

syntheticBeanProducer.produce(
    SyntheticBeanBuildItem.configure(List.class)
        .name("my-list")
        .beanClass(List.class)
        .beanDefinition(
            BeanDefinition.create(List.class)
                .addConstructorArg(new ConstructorArgumentDefinition(List.class, new TypeLiteral<List<Class<?>>>(){})
        )
);

However, this code may not work as expected, resulting in a java.lang.ClassCastException at runtime. The issue lies in the way that Quarkus handles generics in synthetic bean creation.

Understanding Generics in Quarkus

In Quarkus, generics are handled using a feature called "type literals." Type literals are used to represent generic types at compile time, allowing Quarkus to create synthetic beans that are type-safe. However, when creating a synthetic bean that uses generics, Quarkus may not be able to infer the correct type literal, leading to issues.

The Issue with Type Literals

The issue with type literals in Quarkus is that they are not always correctly inferred. When creating a synthetic bean that uses generics, Quarkus may not be able to determine the correct type literal, resulting in a java.lang.ClassCastException at runtime.

Workaround: Using a Raw Type

One workaround for this issue is to use a raw type instead of a generic type. A raw type is a type that is not parameterized, and it can be used to create a synthetic bean that is not type-safe. However, this approach is not recommended, as it can lead to issues at runtime.

Example: Using a Raw Type

Here is an example of how to use a raw type to create a synthetic bean:

syntheticBeanProducer.produce(
    SyntheticBeanBuildItem.configure(List.class)
        .name("my-list")
        .beanClass(List.class)
        .beanDefinition(
            BeanDefinition.create(List.class)
                .addConstructorArg(new ConstructorArgumentDefinition(List.class, new Object[]{new ArrayList()}))
        )
);

In this example, we are using a raw type List.class instead of a generic type List<Class<?>>. This approach is not recommended, as it can lead to issues at runtime.

Best Practice: Using a TypeLiteral

The best practice for creating a synthetic bean that uses generics is to use a TypeLiteral. A TypeLiteral is a class that represents a generic type at compile time, allowing Quarkus to create a synthetic bean that is type-safe.

Example: Using a TypeLiteral

Here is an example of how to use a TypeLiteral to create a synthetic bean:

syntheticBeanProducer.produce(
    SyntheticBeanBuildItem.configure(List.class)
        .name("my-list")
        .beanClass(List.class)
        .beanDefinition(
            BeanDefinition.create(List.class)
                .addConstructorArg(new ConstructorArgumentDefinition(List.class, new TypeLiteral<List<Class<?>>>(){})
        )
);

In this example, we are using a TypeLiteral to represent the generic type List<Class<?>>. This approach is recommended, as it allows Quarkus to create a synthetic bean that is type-safe.

Conclusion

In conclusion, using generics in a Quarkus build step when creating a synthetic bean can be challenging. However, by understanding the issue with type literals and using a TypeLiteral instead, developers can create synthetic beans that are type-safe. The best practice for creating a synthetic bean that uses generics is to use a TypeLiteral, as it allows Quarkus to create a synthetic bean that is type-safe.

Recommendations

Use a TypeLiteral to represent generic types at compile time.
Avoid using raw types, as they can lead to issues at runtime.
Use a TypeLiteral to create a synthetic bean that is type-safe.

Additional Resources

Quarkus documentation: https://quarkus.io/guides/
Quarkus GitHub repository: https://github.com/quarkusio/quarkus

FAQs

Q: What is the issue with type literals in Quarkus? A: The issue with type literals in Quarkus is that they are not always correctly inferred, leading to issues at runtime.
Q: How can I create a synthetic bean that uses generics in Quarkus? A: You can create a synthetic bean that uses generics in Quarkus by using a TypeLiteral to represent the generic type at compile time.
Q: What is the best practice for creating a synthetic bean that uses generics in Quarkus? A: The best practice for creating a synthetic bean that uses generics in Quarkus is to use a TypeLiteral to represent the generic type at compile time.
Quarkus Synthetic Bean Generics FAQ =====================================

Introduction

Quarkus is a modern Java framework that allows developers to build high-performance, container-friendly applications. One of the key features of Quarkus is its ability to create synthetic beans, which are beans that are created at build time rather than runtime. However, when trying to use generics in synthetic bean creation, developers may encounter issues. In this article, we will answer some frequently asked questions about using generics in Quarkus synthetic bean creation.

Q: What is the issue with type literals in Quarkus?

A: The issue with type literals in Quarkus is that they are not always correctly inferred, leading to issues at runtime. When creating a synthetic bean that uses generics, Quarkus may not be able to determine the correct type literal, resulting in a java.lang.ClassCastException at runtime.

Q: How can I create a synthetic bean that uses generics in Quarkus?

A: You can create a synthetic bean that uses generics in Quarkus by using a TypeLiteral to represent the generic type at compile time. A TypeLiteral is a class that represents a generic type at compile time, allowing Quarkus to create a synthetic bean that is type-safe.

Q: What is the best practice for creating a synthetic bean that uses generics in Quarkus?

A: The best practice for creating a synthetic bean that uses generics in Quarkus is to use a TypeLiteral to represent the generic type at compile time. This approach allows Quarkus to create a synthetic bean that is type-safe and avoids the issues associated with type literals.

Q: Can I use a raw type instead of a generic type in a synthetic bean?

A: Yes, you can use a raw type instead of a generic type in a synthetic bean. However, this approach is not recommended, as it can lead to issues at runtime. A raw type is a type that is not parameterized, and it can be used to create a synthetic bean that is not type-safe.

Q: What is the difference between a `TypeLiteral` and a raw type?

A: A TypeLiteral is a class that represents a generic type at compile time, while a raw type is a type that is not parameterized. A TypeLiteral is used to create a synthetic bean that is type-safe, while a raw type is used to create a synthetic bean that is not type-safe.

Q: Can I use a `TypeLiteral` with a raw type?

A: No, you cannot use a TypeLiteral with a raw type. A TypeLiteral is used to represent a generic type at compile time, while a raw type is a type that is not parameterized. Using a TypeLiteral with a raw type would be inconsistent and could lead to issues at runtime.

Q: How can I troubleshoot issues with synthetic bean creation in Quarkus?

A: To troubleshoot issues with synthetic bean creation in Quarkus, you can use the Quarkus debug mode to inspect the synthetic beans that are being created. You can also use the Quarkus logging feature to log the creation of synthetic beans and any errors that may occur during creation.

Q: Can I use a `TypeLiteral` with a generic type that has multiple type parameters?

A: Yes, you can use a TypeLiteral with a generic type that has multiple type parameters. For example, you can use a TypeLiteral to represent a type like List<List<String>>.

Q: How can I create a synthetic bean that uses a generic type with multiple type parameters in Quarkus?

A: To create a synthetic bean that uses a generic type with multiple type parameters in Quarkus, you can use a TypeLiteral to represent the generic type at compile time. For example, you can use the following code to create a synthetic bean that uses a type like List<List<String>>:

syntheticBeanProducer.produce(
    SyntheticBeanBuildItem.configure(List.class)
        .name("my-list")
        .beanClass(List.class)
        .beanDefinition(
            BeanDefinition.create(List.class)
                .addConstructorArg(new ConstructorArgumentDefinition(List.class, new TypeLiteral<List<List<String>>>(){})
        )
);

In this example, we are using a TypeLiteral to represent the generic type List<List<String>> at compile time. This allows Quarkus to create a synthetic bean that is type-safe and avoids the issues associated with type literals.