Mechanisms

Deep Dive into ActivityContext Building Process

ActivityContext, the core IoC/DI container of an Aspectran application, is not instantiated directly at runtime. Instead, it is systematically assembled through the rigorous and disciplined pipeline of ActivityContextBuilder.

The build process goes far beyond simple configuration parsing: it is a comprehensive engineering workflow encompassing dedicated classloader isolation, environment profile resolution, XML/APON/annotation hybrid parsing, bean reference integrity inspection (BeanReferenceInspector), AOP proxy pre-analysis (BeanRuleAnalyzer), aspect validation (AspectRuleValidator), and real-time reloading monitor timer binding.

The entire build process is orchestrated by the HybridActivityContextBuilder class.

1. End-to-End Build Pipeline Architecture

The construction of an ActivityContext progresses through five deterministic, sequential phases.

sequenceDiagram
    autonumber
    participant Svc as CoreService / Host App
    participant Builder as HybridActivityContextBuilder
    participant Loader as SiblingClassLoader
    participant Context as RuleParsingContext
    participant Parser as HybridActivityContextRuleParser
    participant Validator as BeanReferenceInspector & AspectRuleValidator
    participant AC as DefaultActivityContext

    Svc->>Builder: build() invoked

    rect rgba(0, 122, 255, 0.15)
    Note over Builder,Loader: Phase 1: Infrastructure Provisioning
    Builder->>Loader: createSiblingClassLoader() (Create isolated classloader)
    Builder->>Builder: createEnvironmentProfiles() (Determine active profiles)
    Builder->>Context: new RuleParsingContext(classLoader, adapter, profiles)
    end

    rect rgba(40, 167, 69, 0.15)
    Note over Builder,Parser: Phase 2: Declarative Rule Parsing & Component Scanning
    Builder->>Context: beanRuleRegistry.scanConfigurableBeans(basePackages)
    Builder->>Parser: parse(contextRules / parameters)
    Parser->>Context: Register BeanRule, AspectRule, TransletRule
    Parser-->>Builder: Collect monitored files (appendedRuleFiles)
    end

    rect rgba(245, 158, 11, 0.15)
    Note over Builder,Validator: Phase 3: Static Analysis & Strict Validation
    Builder->>Validator: beanReferenceInspector.inspect(beanRuleRegistry)
    Note over Validator: Verify bean reference integrity & prevent circular dependencies
    Builder->>Validator: BeanRuleAnalyzer.determineProxyBean() (Pre-determine AOP proxies)
    Builder->>Validator: aspectRuleValidator.validate(ruleParsingContext)
    end

    rect rgba(239, 68, 68, 0.15)
    Note over Builder,AC: Phase 4: Context Assembly & Instantiation
    Builder->>AC: new DefaultActivityContext(...)
    Builder->>AC: setEnvironment(ActivityEnvironment)
    Builder->>AC: Inject 5 Subsystem Registries & TemplateRenderer
    end

    rect rgba(139, 92, 246, 0.15)
    Note over Builder,Svc: Phase 5: Initialization & Lifecycle Binding
    alt MasterService Present (Standard Runtime)
        Builder->>Builder: startContextReloadingTimer(appendedRuleFiles)
        Builder-->>Svc: Return ActivityContext (Service calls initialize in doStart)
    else Standalone Environment
        Builder->>AC: component.initialize() invoked immediately
        Builder->>Builder: registerDestroyTask() (Register JVM ShutdownHook)
        Builder-->>Svc: Return fully initialized ActivityContext
    end
    end

2. Phase 1: Builder Configuration and Infrastructure Provisioning

The first phase isolates and configures the physical resources and runtime environment required for context execution.

1) ClassLoader Isolation (createSiblingClassLoader)

  • Instantiates a dedicated SiblingClassLoader isolated from the host application’s system classloader.
  • Dynamically binds external directories or JAR paths configured in <resourceLocations> to the classpath, facilitating clean teardown and regeneration of classloader hierarchies during dynamic hot-reloading.

2) Environment Profile Resolution (createEnvironmentProfiles)

  • Evaluates system properties, environment variables, and configuration settings to determine activeProfiles and defaultProfiles, instantiating an EnvironmentProfiles descriptor.
  • Subsequent component definitions and property blocks are activated only if they satisfy these profile predicates.

3) Rule Parsing Context Initialization (RuleParsingContext)

  • Instantiates and prepares (prepare()) a dedicated parsing session object, RuleParsingContext, to stage parsed intermediate rule objects (*Rule) and establish inter-rule relationships.

3. Phase 2: Declarative Rule Parsing and Component Scanning

In this phase, component metadata from diverse sources (Java annotations, XML, APON) is collected and transformed into a unified rule object tree.

1) Annotation-Based Component Scanning

  • Scans package paths designated in basePackages to identify classes annotated with @Component, @Bean, @Aspect, @Service, or @Controller.
  • Discovered classes are converted into equivalent BeanRule and AspectRule definitions and registered into RuleParsingContext.

2) XML / APON Hybrid Parsing (HybridActivityContextRuleParser)

  • Automatically selects the appropriate parser engine based on file extensions and configurations:
  • External configuration files imported during parsing via <append file="..." /> are captured dynamically by RuleFileAppendedListener and registered into the file monitoring set (appendedRuleFiles) for automatic reloading.

4. Phase 3: Static Analysis and Strict Validation

To guarantee that parsed rules operate seamlessly at runtime without unexpected failures, the builder conducts rigorous static analysis and validation.

1) Post-Processing (BeanRuleRegistry.postProcess)

  • Resolves aliases, evaluates parent bean inheritance hierarchies, and sets autowiring candidate flags to ensure complete metadata resolution.

2) Bean Reference Integrity and Circular Dependency Inspection (BeanReferenceInspector)

  • Verifies that target bean IDs and types referenced in constructor arguments, field injections, and property setters actually exist.
  • When running under a parent service, links lookups into the parent context’s bean registry.
  • Circular Dependency Prevention: Identifies cyclic constructor references between beans and raises explicit errors during bootstrapping, fundamentally preventing runtime deadlocks and stack overflows.

3) AOP Proxy Pre-Determination (BeanRuleAnalyzer.determineProxyBean)

  • Analyzes pointcut expressions declared across all AspectRule definitions against candidate bean method signatures.
  • Pre-determines whether a bean is advisable at build time and marks its BeanRule accordingly, completely eliminating the runtime overhead of inspecting AOP applicability on every invocation.

4) Aspect Rule Validation (AspectRuleValidator.validate)

  • Rigorously validates that advice beans and advice methods referenced in aspect rules exist and that method signatures comply with advice specifications.

5. Phase 4: ActivityContext Assembly and Instantiation

Validated rule definitions are converted into operational service registry instances and assembled into a DefaultActivityContext.

graph LR
    RPC[RuleParsingContext<br/>Parsed & Validated] --> Build{AbstractActivityContextBuilder<br/>createActivityContext}

    Build --> AC[DefaultActivityContext]
    Build --> ENV[ActivityEnvironment]
    Build --> BR[DefaultBeanRegistry]
    Build --> AR[AspectRuleRegistry]
    Build --> SR[ScheduleRuleRegistry]
    Build --> TR[DefaultTemplateRenderer]
    Build --> TLR[TransletRuleRegistry]
    Build --> ATE[SimpleAsyncTaskExecutor]

    ENV --> AC
    BR --> AC
    AR --> AC
    SR --> AC
    TR --> AC
    TLR --> AC
    ATE --> AC
  1. DefaultActivityContext Instantiation: Establishes the context skeleton with the dedicated classloader, application adapter, and master service reference.
  2. ActivityEnvironment Construction: Aggregates active profiles and declared <properties>, interpolating system environment variables and evaluating encrypted values.
  3. Assembly of 5 Core Subsystem Registries:
    • DefaultBeanRegistry: Bean instantiation pool created from BeanRuleRegistry metadata.
    • AspectRuleRegistry: Pre-compiled pointcut rule lookup indexes.
    • ScheduleRuleRegistry: Scheduled task configurations.
    • DefaultTemplateRenderer: Template rule registry.
    • TransletRuleRegistry: Translet routing tree.
  4. Asynchronous Task Executor Configuration: If contextConfig.asyncConfig.enabled is active, instantiates and binds SimpleAsyncTaskExecutor equipped with a dedicated thread pool.

6. Phase 5: Initialization and Lifecycle Binding

The assembled context undergoes distinct initialization and lifecycle management workflows depending on host environment configuration:

1) Master Service Integrated Environment (Standard Web, Daemon, Shell, etc.)

  • The builder defers invoking ActivityContext.initialize(), returning the assembled context instance to the master service (DefaultCoreService).
  • In the master service’s doStart() lifecycle hook, component.initialize() is called to trigger singleton instantiation and dependency injection.
  • Context Reloading Timer Startup: Registers all tracked configuration files (appendedRuleFiles) and launches ContextReloadingTimer for zero-downtime hot-reloading.

2) Standalone Builder Execution Environment

  • When the builder is used independently without a master service (e.g., unit tests or standalone utilities):
    • The builder immediately calls ((Component)activityContext).initialize() to fully activate the context.
    • Registers a JVM shutdown hook via ShutdownHook.Manager to ensure graceful teardown upon process termination.

🔍 Related Detailed Mechanisms

7. Next Steps: Exploring Detailed Mechanisms

To examine how dynamic configuration properties, active profiles, and encrypted variables are evaluated within the context, proceed to the ActivityEnvironment Architecture guide.

To inspect how all mechanisms and packages interconnect across the entire framework, refer to the Aspectran Detailed Mechanisms Index.