Conditional Bean Activation in CDI

[otaviojava]

Is your feature request related to a problem? Please describe.

Enterprise applications often require enabling or disabling beans according to deployment-specific conditions.

Examples include:

• Activating a tax calculation implementation based on country.
• Enabling integrations only in specific environments.
• Switching between providers based on configuration.
• Enabling feature-flagged functionality.

Today, CDI applications typically solve these scenarios using producer methods, extensions, or custom framework-specific solutions:

@Produces
public TaxCalculator taxCalculator(Config config) {
    return "BR".equals(config.country())
            ? new BrazilTaxCalculator()
            : new PortugalTaxCalculator();
}

Although effective, this approach adds boilerplate and separates activation logic from the bean definition.

Describe the solution you'd like

Introduce a standard CDI mechanism to support conditional bean activation.

For example:

@Conditional(CountryCondition.class)
@ApplicationScoped
public class BrazilTaxCalculator implements TaxCalculator {
}

This approach would make bean activation declarative, enhance readability, and reduce reliance on producer-based workarounds.

Describe alternatives you've considered

Currently, similar functionality can be achieved using:

• Producer methods
• Portable Extensions
• Build Compatible Extensions
• Custom framework-specific solutions

Other frameworks offer similar capabilities:

• Apache DeltaSpike: @Exclude
• Spring: @Conditional
• Spring: @Profile
• Spring Boot: @ConditionalOnProperty

Example:

@Conditional(MyCondition.class)
@Component
class MyService {
}

These examples demonstrate that conditional bean activation is a common requirement across dependency injection frameworks.

Additional context

A standard solution would simplify enterprise use cases such as multi-country deployments, feature flags, environment-specific integrations, and provider selection.

It would also offer a portable alternative to custom extensions and framework-specific annotations, while keeping activation logic close to the bean definition.

[Ladicek]

I would like to note that what you're after is clearly activation based on a runtime condition, which is directly incompatible with build-time oriented implementations. This could possibly go only into CDI Full, I don't mind.

But also, if you could go into some level of detail, that would be great. Here are some questions that immediately popped into my head:

1. How does the @Conditional annotation look like? Since the condition implementation needs some kind of context, I assume the value of @Conditional identifies a bean, but there's really no good way of identifying a bean using an annotation. A Class-valued member can identify a class type and you can use a trick to also support parameterized types (we recently used this trick for @Registration, so there's a precedent), but there's no way of adding qualifiers.
2. When is the condition evaluated? If the value of @Conditional indeed identifies a bean (that probably implements some kind of interface with one method that returns a boolean), the condition cannot be evaluated during bean discovery, and so you cannot really enable/disable beans using this approach (note that an enabled / disabled bean is a well-defined term in the CDI specification). If @Conditional doesn't identify a bean but a simple class that cannot do injection (or CDI.current() or any other way of accessing CDI!), it probably could run during bean discovery, but where would it get the context from? A lot less options are available.

[graemerocher]

this idea seems directly taken from what Micronaut and Spring support today. Documentation https://docs.micronaut.io/5.0.2/guide/#conditionalBeans

In Micronaut it is written @Requires(condition=SomeCondition.class) https://docs.micronaut.io/5.0.2/api/io/micronaut/context/annotation/Requires.html#condition()

[graemerocher]

FWIW we at build time have logic that splits conditions that require runtime evaluation for those that require build time evaluation. For example the following:

@Requires(classes=Foo.class)

Is considered safe for build time evaluation

[otaviojava]

https://docs.micronaut.io/5.0.2/guide/#conditionalBeans

Yep, I usually use the same terminology that we already have in the Java industry.

I am considering Micronaut and Spring as reference for sure.

[otaviojava]

I would like to note that what you're after is clearly activation based on a runtime condition, which is directly incompatible with build-time oriented implementations. This could possibly go only into CDI Full, I don't mind.

I fine with it as well.

How does the @conditional annotation look like?

This proposal builds on existing market solutions, so it is important to review how other frameworks address this issue.

• Spring provides @Conditional, @Profile, and @ConditionalOnProperty.
• Micronaut provides @Requires, including support for custom conditions.
• Apache DeltaSpike provides @Exclude and project-stage-based activation.

In both Spring and Micronaut, the condition is not a bean but rather a class that implements a specific contract that the container evaluates.

For example:

@Conditional(CountryCondition.class)
@ApplicationScoped
public class BrazilTaxCalculator implements TaxCalculator {
}
public class CountryCondition implements Condition {

    @Override
    public boolean matches(ConditionContext context) {
        return "BR".equals(context.getProperty("country"));
    }
}

A CDI solution should take a similar approach, using a dedicated SPI rather than a CDI bean.

When is the condition evaluated?

I prefer to handle this during bean discovery or application initialization, rather than during injection resolution.

The goal is to determine whether the bean should participate in the application at all. This is similar to how Spring, Micronaut, and DeltaSpike activate or deactivate beans based on configuration, environment, project stage, classpath contents, available beans, or custom conditions.

This approach aligns better with build-time-oriented implementations, as conditions can be evaluated using metadata and deployment configuration instead of requiring runtime bean selection.

The main objective is to provide a standard, declarative way to activate or deactivate beans, without relying on producers, extensions, or framework-specific solutions, rather than enabling runtime switching between implementations.

[hantsy]

@otaviojava I have filed an issue about this topic before, #869

[Ladicek]

How about you guys @hantsy @otaviojava build a Portable Extension that does what you imagine? Then come back to the specification project with a prototype, instead of a rather shallowly explored idea?

Clearly this is useful, but we need someone to do the actual work, and filing issues is just not a good way to achieve that.

[otaviojava]

How about you guys @hantsy @otaviojava build a Portable Extension that does what you imagine? Then come back to the specification project with a prototype, instead of a rather shallowly explored idea?

Yeap, I can explore it this weekend.

[otaviojava]

@Ladicek could you check this one, please?

https://github.com/soujava/conditional-cdi

[otaviojava]

@hantsy about the API could you check it and create issues about points to improve it?

[Ladicek]

OK, this is interesting. First off, using ProcessBeanAttributes means conditional activation doesn't apply to synthetic beans. I guess this is because using ProcessBeanAttributes is easiest, but maybe it is intentional? I'm not sure. This is something that needs to be clarified.

Other than that, I think I agree with the decisions you made in that prototype.

I think there's a small number of conditions we might want to support initially:

• presence/absence/value of system properties, environment variables, maybe configuration in general (too bad there's no spec we could rely on...)
• presence/absence of a class
• presence/absence of a bean (I guess identified by a type and set of qualifiers?)
• presence/absence of a classpath resource probably? (I don't think it makes sense to decide based on presence of a file, certainly not at application build time)

The bare minimum API I can think of for this would be:

• annotation @Requires that specifies the condition class; this should probably be repeatable, because if we allow stereotyping (which I think we should), multiple requirements occur anyway

• interface Condition with a single method that accepts a ConditionContext and returns a boolean

• interface ConditionContext with bare minimum access to the CDI container; something like

  public interface ConditionContext {
      <T> boolean hasBean(Class<T> type, Annotation... qualifiers);
  
      <T> boolean hasBean(TypeLiteral<T> type, Annotation... qualifiers);
  
      <T> boolean hasClass(Class<T> clazz);
  
      boolean hasClasspathResource(String path);
  }

The Condition interface would document that the implementations may only access the CDI container through the ConditionContext. What the hasBean methods do seems obvious; it is not entirely clear what hasClass and hasClasspathResource mean, specifically whether they only represent the knowledge of the CDI container, or whether they can access the whole application. CDI implementations may differ in their capabilities of accessing "the whole application".

I'm not entirely sure about the hasClass method, because to be able to pass the argument, the class has to be present. This might make more sense directly on an annotation... We could possibly have hasClass(String) though.

I guess this would even allow build-time implementations, but I didn't spend too much time thinking about that.

[hantsy]

@otaviojava see: soujava/conditional-cdi#1

[hantsy]

interface Condition with a single method that accepts a ConditionContext and returns a boolean

Similar to Micronaut, Condition can be extended from Predicate<ConditionContext>, in ConditionContext, it is possible to access the bean context(to test the condition).

[otaviojava]

OK, this is interesting. First off, using ProcessBeanAttributes means conditional activation doesn't apply to synthetic beans. I guess this is because using ProcessBeanAttributes is easiest, but maybe it is intentional? I'm not sure. This is something that needs to be clarified.

That was a prototype choice; I've updated it.

presence/absence/value of system properties, environment variables, maybe configuration in general (too bad there's no spec we could rely on...)

Enterprise applications use it all the time; that is part of the Twelve Factor App. I would love to have the Jakarta Config as soon as possible; in the meantime, we could let the vendor decide how to handle it and how to read those properties or System Env; that is how we are working on another specification.

cc/ @arjantijms @ivargrimstad @OndroMih another possible block: not having Jakarta Configuration ready.

interface Condition with a single method that accepts a ConditionContext and returns a boolean

When I was implementing, I had the same feeling. The ConditionContext sounds a great ideia.

<T> boolean hasClass(Class<T> clazz);

Can we agree on using type instead of clazz?

I guess this would even allow build-time implementations, but I didn't spend too much time thinking about that.

As @graemerocher said, they have it on Micronaunt, thus, we can assume that it is possible.