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
SiblingClassLoaderisolated 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
activeProfilesanddefaultProfiles, instantiating anEnvironmentProfilesdescriptor. - 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
basePackagesto identify classes annotated with@Component,@Bean,@Aspect,@Service, or@Controller. - Discovered classes are converted into equivalent
BeanRuleandAspectRuledefinitions and registered intoRuleParsingContext.
2) XML / APON Hybrid Parsing and Appender Processing (HybridActivityContextRuleParser)
Declarative configuration files are processed through a unified hybrid parser pipeline according to their formats (XML or APON) and delivery mechanisms (file path, classpath resource, or parameter object):
- Parser Hierarchy and Role Separation:
ActivityContextRuleParser: Defines the top-level parser contract (AutoCloseable) for reading configuration rules and populating aRuleParsingContext.AbstractActivityContextRuleParser: Manages theRuleParsingContext, character encoding (encoding), XML-to-APON conversion flag (useXmlToApon), and debug mode (debugMode), providing the coreresolveAppender()logic to determine and instantiate the appropriateRuleAppenderfrom resource paths.HybridActivityContextRuleParser: The concrete hybrid parser implementation accommodating both XML and APON formats, delegating actual parsing and nested rule file handling to an internalHybridRuleAppendHandler.
- Resource Resolution and Appender Determination (
resolveAppender):- Generates the appropriate
RuleAppenderbased on the configuration path prefix:classpath:prefix: UsesResourceRuleAppenderto load resources via the isolated class loader (SiblingClassLoader).file:prefix: UsesFileRuleAppenderfor absolute filesystem paths.- Relative paths without prefix: Uses
FileRuleAppenderresolved relative toruleParsingContext.getBasePath().
- Determines the file format: sets
AppendableFileFormatType.APONif the file extension is.apon(case-insensitive); otherwise defaults toAppendableFileFormatType.XML.
- Generates the appropriate
- Format-Specific Parsing Execution (
HybridRuleAppendHandler):HybridRuleAppendHandlerdynamically routes parsing depending on theRuleAppendertype and configuration format:- XML Configuration (Default - Nodelet High-Speed XML Parsing): Bypasses intermediate model conversions and directly invokes
AspectranNodeParserto stream XML nodes via Nodelet-based SAX parsing, immediately creating and registering rule objects (BeanRule,TransletRule,AspectRule, etc.) intoRuleParsingContext. - XML Configuration (Alternative & Cross-Validation - with
useXmlToAponenabled): Converts XML documents into intermediateRootParametersviaXmlToParameters, then transforms them into rule objects usingParametersToRules. This path serves as an independent cross-validation reference against the direct Nodelet parser to verify parsing fidelity, guarantee rule mapping consistency across engines, and isolate potential defects during debugging. - APON Configuration (
.aponfiles): Reads APON documents intoRootParametersvia a Reader, which are subsequently converted into rule objects usingParametersToRules. - Programmatic Parameters (
AspectranParameters): When configuration is passed directly in memory as anAspectranParametersinstance (AppenderType.PARAMETERS),ParametersToRulesassembles it directly into the context rule tree.
- XML Configuration (Default - Nodelet High-Speed XML Parsing): Bypasses intermediate model conversions and directly invokes
- External Configuration Imports (
<append>) and Dynamic File Tracking:- External configuration files imported during parsing via
<append file="..." />(XML) orappend: { file: "..." }(APON) are processed recursively byHybridRuleAppendHandler.handle(appender). - Whenever a filesystem-based appender (
FileRuleAppender) is processed, theRuleFileAppendedListenercallback registered by the builder is triggered in real time, appending physicalFilehandles into theappendedRuleFilescollection without duplicates. This list is subsequently supplied toContextReloadingTimerfor hot reloading.
- External configuration files imported during parsing via
- Scope Isolation and Scoped Overrides:
- Protects nested parsing scopes by backing up and restoring
RuleParsingScopebefore and after appending child configurations. - When child rules (
childRules) are explicitly specified inside an<append>block (applyScopedOverrides), the handler precisely overrides beans (BeanRule), properties (EnvironmentRule), type aliases (TypeAliasRule), translets (TransletRule), aspects (AspectRule), schedules (ScheduleRule), and templates (TemplateRule) declared within the appended scope.
- Protects nested parsing scopes by backing up and restoring
- Debug Mode Support (XML to APON):
- When
debugModeis enabled during XML parsing, an equivalent.aponfile (e.g.,app-config.xml.apon) is automatically dumped alongside the XML file, allowing easy verification and migration of XML configurations into APON syntax.
- When
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
AspectRuledefinitions against candidate bean method signatures. - Pre-determines whether a bean is advisable at build time and marks its
BeanRuleaccordingly, 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
DefaultActivityContextInstantiation: Establishes the context skeleton with the dedicated classloader, application adapter, and master service reference.ActivityEnvironmentConstruction: Aggregates active profiles and declared<properties>, interpolating system environment variables and evaluating encrypted values.- Assembly of 5 Core Subsystem Registries:
DefaultBeanRegistry: Bean instantiation pool created fromBeanRuleRegistrymetadata.AspectRuleRegistry: Pre-compiled pointcut rule lookup indexes.ScheduleRuleRegistry: Scheduled task configurations.DefaultTemplateRenderer: Template rule registry.TransletRuleRegistry: Translet routing tree.
- Asynchronous Task Executor Configuration: If
contextConfig.asyncConfig.enabledis active, instantiates and bindsSimpleAsyncTaskExecutorequipped 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 launchesContextReloadingTimerfor 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.Managerto ensure graceful teardown upon process termination.
- The builder immediately calls
🔍 Related Detailed Mechanisms
- For the runtime architecture and operational mechanics of the assembled context, see ActivityContext: The Heart of the Aspectran Container.
- For how configuration changes trigger zero-downtime reloads, see Aspectran Reloading Mechanism.
- For environment profile resolution and property evaluation rules, see ActivityEnvironment Architecture.
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.