OnExpressionCondition class

A Condition implementation that dynamically evaluates an expression to determine whether a component, configuration, or pod should be activated.

OnExpressionCondition works in conjunction with the ConditionalOnExpression annotation to enable or disable annotated elements based on the result of an evaluated expression. This allows developers to declaratively define logical or contextual conditions that control configuration activation.

Purpose

This condition is especially useful for scenarios where simple presence-based conditions (e.g., OnClassCondition, OnPropertyCondition) are not sufficient. It enables fine-grained activation logic using dynamic expressions that can reference pods, scopes, or runtime environment properties.

Expressions are evaluated using JetLeaf’s PodExpressionResolver, which supports structured resolution against the active PodFactory and optionally within a Scope.

Behavior

• If a ConditionalOnExpression annotation is present on the Annotation:
  • The annotation’s expression field defines the condition to evaluate.
  • The expression is resolved in the context of the current PodFactory.
  • If a Scope annotation is also present, the expression is evaluated within that scope’s registered pod namespace.
  • The condition passes (true) if the expression evaluates successfully and produces a non-null result.
  • The condition fails (false) if the evaluation returns null, throws an error, or the expression cannot be resolved.
• If no ConditionalOnExpression annotation is present, the condition passes automatically.
• If expression resolution is unavailable (no PodExpressionResolver), evaluation defaults to false for safety.

Example

// Activates only if a specific property evaluates to true
@ConditionalOnExpression("env['jetleaf.enableFeatureX'] == true")
class FeatureXPod {}

// Scoped expression example
@Scope('web')
@ConditionalOnExpression("pods.contains('httpServer')")
class WebServerPod {}

Evaluation Flow

1. The condition checks for the presence of a ConditionalOnExpression annotation on the Annotation.
2. If found, it retrieves the associated expression string.
3. It looks for a Scope annotation to determine the appropriate evaluation context.
4. It obtains a PodExpressionResolver from the PodFactory.
5. The resolver executes the expression inside a PodExpressionContext, passing in the PodFactory and the optional scope.
6. If the expression returns a non-null value, the condition passes; otherwise, it fails.
7. If no expression annotation is found, the condition passes by default.

Logging

When trace logging is enabled:

• Logs the start of evaluation for each annotated source.
• Logs the expression being evaluated and the target scope (if any).
• Emits ✅ when evaluation returns a non-null value.
• Emits ❌ when the result is null or evaluation fails.
• Captures all intermediate evaluation details to aid conditional debugging.

Related Components

• ConditionalOnExpression: Declares the expression that determines activation.
• PodExpressionResolver: Executes the expression logic within the context.
• PodExpressionContext: Provides access to pods and scoped runtime state.
• Scope: Defines the contextual scope in which the expression is evaluated.
• PodFactory: Provides registered pods and access to the resolver.
• ConditionalContext: Supplies the overall evaluation environment.
• Annotation: Represents the annotated class or method being processed.