Aspectran 9.7 Release Notes

This release is a major architectural milestone that moves beyond the limitations of the traditional Jakarta Servlet ecosystem, introducing the aspectran-with-netty module for high-performance non-blocking networking combined with Java 21 Virtual Threads, and comprehensively refactoring the web module architecture into aspectran-web and aspectran-web-servlet.

Aspectran 9.7.0 delivers a servlet-less microservice and high-performance REST API runtime powered by Netty 4.2, True Multi-Context isolation on a single port, zero-dependency native multipart parsing (NettyMultipartFormDataParser), kernel-level zero-copy static resource serving (NettyResourceHandler), and native WebSocket (JSR-356) support. In addition, this release features a streamlined aspectran-web module free of third-party servlet dependencies alongside a dedicated aspectran-web-servlet module, declarative @Multipart annotations with Jakarta Servlet 3.0+ standard multipart support, an expanded FileParameter API, RFC 6265 Cookie builder utilities, modernized lifecycle management based on LifeCycle.State, ordered context lifecycle and graceful shutdown improvements for Undertow and Netty, and a wide array of enhancements in performance, security, and developer productivity.

🚀 New Features

• Servlet-less High-Performance Microservice Runtime Module (aspectran-with-netty)
  • Introduced the aspectran-with-netty module, providing an embedded web and WebSocket server engine powered by Netty 4.2 and modern MultiThreadIoEventLoopGroup.
  • Implemented a ‘Post-Reactive’ architecture: Netty’s non-blocking I/O event loops directly accept and process incoming client network sockets without heavyweight servlet containers, dispatching request execution to Java 21 Virtual Threads so that OS carrier threads are instantly yielded during blocking I/O operations.
  • True Multi-Context Support: Hosts multiple independent application contexts (e.g., /, /admin, /api) on a single server port (e.g., 8080) with completely isolated dependency injection containers (ActivityContext), session managers (NettySessionManager), static resource handlers, and WebSocket endpoints via NettyContextRouter.
  • Native Multipart Form Data Parser (NettyMultipartFormDataParser): Completely eliminated legacy commons-fileupload dependencies, leveraging Netty’s HttpPostRequestDecoder and direct memory buffers (ByteBuf) to handle large file uploads with high throughput and low memory footprint. Added overloaded string-based data size setters (setMaxHeaderSize, setMaxRequestSize, setMaxFileSize, etc.).
  • High-Performance Static Resource Handler (NettyResourceHandler): Delivers OS kernel-level zero-copy file transfer (FileRegion), chunked transfers, If-Modified-Since HTTP cache validation, automatic directory index resolution, and APON pattern-based protected directory access rules.
  • Native WebSocket (JSR-356) Support: Implemented NettyWebSocketServerContainerInitializer and NettyWebSocketSession to run standard WebSocket endpoints directly on Netty without a servlet container, including WebSocket session binding, session attribute isolation, and graceful connection closure mechanisms.
  • Server Metrics and Concurrency Tracking: Integrated TrackingExecutor for real-time monitoring of thread pools, event loop groups, active requests, and cumulative total requests, along with getPeakRequests() to track peak concurrent requests.
• Comprehensive Web Module Architecture Refactoring (aspectran-web / aspectran-web-servlet)
  • Refactored aspectran-web into a pure, lightweight web abstraction layer completely free of Jakarta Servlet API and external dependencies (commons-fileupload, commons-io).
  • Separated aspectran-web-servlet as a dedicated module for traditional WAS deployments, JSP view rendering, servlet filter/listener integration, servlet-based multipart parsers, and custom JSP tag libraries.
  • Guaranteed seamless interoperability across servlet-based runtimes (aspectran-with-undertow, aspectran-with-jetty, aspectran-web-servlet) and the servlet-less Netty runtime (aspectran-with-netty), allowing the exact same Translet rules (XML, APON, Java Config) and business logic to run without code changes.
• Declarative @Multipart Annotation and Standard Servlet Multipart Parser
  • Introduced the @Multipart annotation for action methods and classes to declaratively configure multipart request processing.
  • Added automatic detection and parsing of multipart requests when FileParameter or FileParameterMap method arguments are present in action methods (AnnotatedMethodInvoker).
  • Extended multipart form data parsing support to POST, PUT, and PATCH HTTP methods.
  • Enhanced WebRequestBodyParser with flexible parser bean resolution (explicit bean name, aspect setting, default bean, or unique type-based bean).
  • Added context-startup validation for configured multipart parser beans, reporting missing references clearly via RuleParsingContext and BeanReferenceInspector.
  • Introduced StandardServletMultipartFormDataParser and its factory bean (StandardServletMultipartFormDataParserFactoryBean), utilizing the standard Jakarta Servlet 3.0+ jakarta.servlet.http.Part API.
  • Added support for standard servlet MultipartConfig configurations on JettyServlet, JettyWebAppContext, and TowServlet.
• Enhanced FileParameter API and Automatic Parameter Binding
  • Added getSavedPath(), isSaved(), saveAs(File), and moveTo(File) methods to the FileParameter interface to provide intuitive, standardized file storage and manipulation capabilities.
  • Added support for FileParameter method argument binding in AnnotatedMethodInvoker, allowing uploaded files to be injected directly into controller action methods.
• RFC 6265 Standard Cookie Builder and Utility Enhancements
  • Implemented a fluent Cookie.builder() API and toHeaderValue() adhering to RFC 6265 standards (supporting SameSite, HttpOnly, Secure, Partitioned attributes).
  • Added overloaded helper methods WebUtils.setCookie() and WebUtils.removeCookie() accepting Translet and ResponseAdapter for convenient cookie manipulation.
• Unified Session Manager Provider and Interactive Shell Session Management Application
  • Introduced the SessionManagerProvider interface in the core component to unify session manager retrieval across diverse server implementations (Netty, Undertow, etc.).
  • Added SessionListenerRegistrationBean for declarative registration of web application session lifecycle listeners.
  • Added getRemainingInactiveInterval() to Session and ManagedSession to calculate the remaining time before session expiration.
  • Added an interactive session management sample application in Aspectran Shell for testing login, logout, and session inspection commands.

🚀 Improvements

• Unified Reverse Proxy Header Handling and Proxy Address Forwarding Refactoring
  • Consolidated proxyAddressForwarding configuration in WebConfig and aspectran-config.apon, ensuring X-Forwarded-* headers (scheme, host, port, remoteAddr) are honored only when explicitly enabled.
  • Propagated proxyAddressForwarding settings from WebService to ServletWebActivity and TowActivity.
  • Conditioned reverseContextPath parsing on isProxyAddressForwarding() in DefaultServletWebService, DefaultTowService, and DefaultNettyService.
  • Clarified ambiguous method names in WebUtils by renaming parseRemoteAddr() to parseForwardedFor() and getRemoteAddr(String, String) to resolveRemoteAddr().
  • Added UriUtils.makeAbsoluteUrl() overloaded helper methods, simplified redirect URL construction in ResponseAdapter implementations, and removed legacy proxyProtocolAware configurations and SendRedirectBasedOnXForwardedProtocol.
• Modernized LifeCycle Interface with LifeCycle.State and ReentrantLock
  • Replaced legacy string-based lifecycle states with the type-safe LifeCycle.State enum (STOPPED, STARTING, STARTED, STOPPING, FAILED).
  • Modernized AbstractLifeCycle using ReentrantLock, AutoCloseable, and functional listener notification patterns to enhance thread safety and concurrency control.
  • Updated CLI and daemon control commands (NettyCommand, TowCommand, JettyCommand) across Netty, Undertow, and Jetty to utilize the new LifeCycle.State enum.
• Ordered Context Lifecycle and Graceful Shutdown for Undertow and Netty
  • Added the order property and isRootContext() method to TowServletContext and NettyContext.
  • Guaranteed that the root context (order=0) starts first, with remaining contexts starting in ascending order of order.
  • Enforced safe shutdown order in reverse startup sequence (LIFO), stopping child contexts before the root context.
  • Reordered and documented Netty graceful shutdown steps to drain in-flight requests cleanly before stopping contexts.
• Refined Temporary Resident Session (isTempResident) and Promotion Logic
  • Fixed ManagedSession logic to ensure temporary resident sessions are properly promoted to resident sessions when maxInactiveInterval is explicitly configured.
  • Clarified isTempResident Javadoc in Session and improved SessionData handling of extraInactiveInterval and expiration time updates.
  • Consolidated ManagedSessionManagerTest and SessionManagerTest into DefaultSessionManagerTest for unified test coverage.
• Netty Resource Leak Prevention and Windows File Lock Mitigation
  • Enforced strict reference counting (release()) across Netty channel handlers to eliminate direct memory (ByteBuf) leaks.
  • Ensured safe release of EmbeddedChannel and resource handler channels in test suites to prevent file locking issues on Windows platforms.
• Extended DI Container and Bean Rule Registry Inspection
  • Extended containsBeanRule to verify dynamically configurable bean rules in configurableBeanRuleMap.
  • Enabled CoreServiceHolder to register and manage multiple service instances mapped to the same service class.
  • Ensured proper subservice withdrawal from CoreServiceHolder during NettyContext teardown.
• Improved Web Request Adapter Hierarchy
  • Refactored WebRequestAdapter class hierarchy and standardized constructor-based contextPath injection.
  • Unified web application attributes across services and refined Thymeleaf integration.

🐛 Bug Fixes

• Fixed NullPointerException during Undertow Shutdown
  • Added defensive guards for undeployed states and removed redundant deployment list iterations in ServletRequestHandlerFactory, resolving NPE errors during Undertow server shutdown.
• Ensured Null-Safety in TowSessionAdapter.getSession()
  • Added null checks when retrieving sessions in TowSessionAdapter to prevent potential NullPointerException occurrences.
• Fixed Original Activity Detection in AbstractActivity
  • Corrected conditional logic for detecting the initial root activity (original activity) in nested activity execution chains.
• Prevented IOException on Unauthorized WebSocket Closure and Handled Empty Close Frames
  • Fixed an issue where IOException was improperly thrown in AbstractEndpoint when closing unauthorized WebSocket sessions.
  • Safely handled empty close frames with missing status codes in Netty WebSocket handlers by defaulting to standard close codes.
  • Guarded against exposing WebSocket endpoints when WebSocket support is not explicitly configured.
• Improved Broken Bean Reference Diagnostics
  • Enhanced error reporting to clearly indicate missing bean names and expected types in BeanReferenceException and startup logs.

🛠️ Dependency Upgrades

• Networking & Web Servers
  • Netty: 4.2.18.Final (Newly introduced)
  • Jetty: 12.1.12 → 12.1.13
• Core Utilities & Terminal
  • JLine: 4.3.1 → 4.4.3
  • FreeMarker: 2.3.34 → 2.3.35
• Logging & Databases
  • SLF4J: 2.0.18 → 2.0.19
  • H2 Database: 2.4.240 → 2.5.250
  • Hibernate ORM: 7.4.5.Final → 7.4.7.Final
• Build & Plugins
  • Maven Compiler Plugin: 3.15.0 → 3.16.0
  • Maven Bundle Plugin: 6.1.0 → 6.1.2
  • Maven Surefire Plugin: 3.5.6 → 3.2.0
  • Central Publishing Maven Plugin: 0.11.0