Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseLink/DesignDocs/219683
Design Specification: Interceptors
Document History
| Date | Author | Version Description & Notes |
|---|---|---|
| 2008-02-21 | Gordon Yorke | Working Draft |
Project overview
This feature will introduce Interceptor "interfaces" that can be implemented by users to intercept certain internal EclipseLink component interactions. This will include cache access, query execution and others.
Goals:
- Provide extension points that intercept internal EcliseLink operations instead of the current options of responding to operations through events.
- Choose interception points that provide the best leverage.
Concepts
Interceptors
Within EclipseLink logical operations like cache access or database writes flow naturally through different components. If points of intercept were added at the logical points of delegation within the EclipseLink architecture these operations could be intercepted and augmented or redirected. Developing these interception points and Interceptor interfaces increases the extensibility of EclipseLink beyond the scope of our current extensibility.
Requirements
Produce configurable interception points and interfaces for interception. The configuration should be simple while providing flexability.
Functionality
Interceptors
The Cache Interceptor
If a developer wishes to intercept EclipseLink's cache access the org.eclipse.persistence.sessions.interceptors.CacheInterceptor class should be extended and those methods that should be intercepted implemented. The user's implementation class should be set on the descriptor that should be intercepted. For Inheritance only set the class on the root of the tree as EclipseLink will store all subclasses in the same Cache. Once set the provided class will receive all caching calls. The existing EclipseLink cache settings will still be used and any calls allowed to continue to the EclipseLink cache will execute against the configured cache.
Query Interceptors
For Query Interception the existing Query Redirectors will be leveraged but the configuration is being updated to allow for default Query Redirectors to be set on the ClassDescriptor. Users will be able to set a default redirector or a Query class specific default redirector (ReadObjectQuery Redirector, ReadAllQuery Redirector, ReportQuery Redirector, InsertObjectQuery Redirector, UpdateObjectQuery Redirector). If a user has set a default redirector then only the more precise redirector will be called. For example if the user was to set both a default redirector and a default ReadObjectQuery redirector then when executing a ReadObjectQuery only the ReadObjectQuery redirector would be called.
There is a helper class org.eclipse.persistence.queries.QueryRedirectorHelper that provides a method for allowing developers of Redirectors to have access to some EclipseLink behaviour like checking the shared cache. Query redirectors preempt the entire query so checking the shared cache would have to requested by the redirector.
Design Constraints
Keep the implementation as generic as possible.
Config files
Configuration is completed through Session or Descriptor customizers using the EclipseLink meta-data APIs. Annotations and XML configuration will be implemented at a later date.
Documentation
Design
Cache Interceptors
To eliminate any performance impact on users who are not using interceptors a design pattern where an Abstract class that conforms to the IdentityMap interface was created that could be subclassed by developers who wished to implement an Interceptor. When an interceptor is set on a descriptor EclipseLink will instantiate both the configured IdentityMap and the Interceptor setting the IdentityMap within the Interceptor. Without an Interceptor there are no cycles spent checking for an Inteceptor. This Abstract Class exposes all of the Java public methods of the IdentityMap.
Query Redirectors
No changes have been made to the operation of the Query Redirectors.
Open Issues
This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.
| Issue # | Owner | Description / Notes |
|---|---|---|
Decisions
This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.
| Issue # | Description / Notes | Decision |
|---|---|---|
Future Considerations
During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.