ErrorPages class

Central registry and manager for error page pods in the Jetleaf framework.

Overview

The ErrorPages class serves as the unified container for all error page configurations in a Jetleaf application. It manages both application-defined error pages and framework-provided default error pages, providing a comprehensive error handling solution with proper prioritization and conflict resolution.

Key Responsibilities

  • Error Page Management: Maintains separate collections for application and framework error pages
  • Automatic Discovery: Scans for @Pod annotated error page instances
  • Registrar Integration: Supports modular error page configuration via ErrorPageRegistrar
  • Conflict Resolution: Handles duplicate error pages with application pages taking precedence
  • Ordering: Applies proper sorting for consistent error page selection

Error Page Resolution Strategy

When resolving error pages for a specific HTTP status:

  1. Application Pages First: Application-defined pages take precedence
  2. Framework Fallbacks: Framework pages fill gaps without application overrides
  3. Status-Based Mapping: Pages are mapped by HTTP status code for efficient lookup
  4. Duplicate Prevention: Only one page per status code in final resolution

Framework vs Application Pages

  • Framework Pages: Identified by special path prefixes or attributes, provide default error handling
  • Application Pages: Custom error pages defined by application developers, override framework defaults

Initialization Process

During onReady:

  1. Direct Pod Discovery: Finds all ErrorPage pods in the application context
  2. Registrar Discovery: Locates all ErrorPageRegistrar pods for modular configuration
  3. Ordering Application: Sorts pages using package and annotation-aware comparators
  4. Registration: Adds discovered pages to appropriate collections

Usage Example

@Service()
class ErrorConfiguration {
  @Pod()
  ErrorPage getNotFoundPage() => ErrorPage('/errors/404')..setStatus(HttpStatus.NOT_FOUND);

  @Pod()  
  ErrorPage getServerErrorPage() => ErrorPage('/errors/500')..setStatus(HttpStatus.INTERNAL_SERVER_ERROR);
}

@Component()
class CustomErrorRegistrar implements ErrorPageRegistrar {
  @override
  void configure(ErrorPageRegistry registry) {
    registry.addPage('/custom/400', HttpStatus.BAD_REQUEST);
  }
}

Integration Points

  • Used by error handling components to resolve appropriate error pages
  • Integrated with exception resolvers for unified error response generation
  • Supports both programmatic and declarative error page configuration
  • Works with template engines for dynamic error page rendering

Performance Considerations

  • Pages are resolved once during initialization for runtime efficiency
  • Unmodifiable views prevent accidental modification after initialization
  • Status-based mapping enables O(1) lookups during error handling

Thread Safety

  • Collections are populated during initialization and become effectively immutable
  • Unmodifiable list views prevent external modification
  • Safe for concurrent read access after initialization

Summary

The ErrorPages class provides a robust, hierarchical error page management system that balances application flexibility with framework-provided defaults, ensuring comprehensive error handling across all HTTP status scenarios.

Implemented types

Constructors

ErrorPages()
Central registry and manager for error page pods in the Jetleaf framework.

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

add(ErrorPage page) → void
Adds a pre-constructed ErrorPage instance to the registry.
override
addPage(String path, HttpStatus status) → void
Convenience method to add an error page by specifying the path and status directly.
override
findPossibleErrorPage(HttpStatus? status) → ErrorPage?
Finds a suitable ErrorPage for a given status.
getApplicationPages() → List<ErrorPage>
Returns all application-defined error page pods.
getFrameworkPages() → List<ErrorPage>
Returns all framework-provided error page pods.
getPackageName() → String
Represents an abstraction for identifying the package that an object, resource, or service belongs to.
getResolvedPages() → List<ErrorPage>
Returns the final resolved list of error pages with application precedence.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onReady() → Future<void>
Interface to be implemented by pods that require initialization logic after their properties have been set by the container.
setApplicationContext(ApplicationContext applicationContext) → void
Sets the ApplicationContext that this component runs in.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited