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/Development/JPA 2.0/metamodel api
JPA 2.0: MetaModel API
| Date | Committer(s) | Description |
|---|---|---|
| March 3, 2009 | gyorke | Initial feature template |
| March 3, 2009 | mobrien | Start analysis |
Note: this document is in progress as of 20090304 for the next 3-5 weeks, therefore the content is in flux.
Summary
In JPA 2.0 the specification has defined standard APIs for representing the structure of a persistence unit model. This is referred to at the MetaModel APIs. There are two main aspects to providing this functionality. The first is the runtime model accessed from EntityManagerFactory.getMetaModel() and the second is the APT generated meta model classes. Our first goal is to provide functionality for runtime access.
For details see section 5.2 and 5.3 of Proposed Final Draft.
Work Estimate
- Investigate EclipseLink Metamodel
- approx 3 days
- Develop implementations of MetaModel or refactor current metamodel
- approx 10 days
- APT investigation and prototype
- approx 5 days
- APT tooling/testing
- approx 10 days
Analysis
Concepts
Metamodel?
- In the context of EclipseLink a metamodel is an abstract view of the managed classes in the persistence unit - we already have one of these that we construct in memory surrounding the class MetadataProcessor - we must transition or refactor this.
- We use the metamodel to construct a runtime query structure that is "object-based".
Relation to JPQL?
Functional Requirements
Requirements and constraints have traceability down to their associated use cases.
Requirements Table
| Req# | A# | Use Cases# | Description |
|---|---|---|---|
| R1 | - | - | Support runtime Metamodel APIs |
| R1.1 | - | - | Develop, leverage or refactor current Metamodel processor |
| R1.2 | - | - | - |
| R2 | A1 | - | Support APT generation of Canonical Metamodel classes |
| R2.1 | - | - | No extra runtime paramenters are required beyond existing -javaagent runtime flag |
Assumptions Table
| A# | Req# | Use Cases# | Description |
|---|---|---|---|
| A1 | - | - | Java 5 is the minimum compile target we support (unchanged) |
| A2 | - | - | Runtime environment for metamodel construction is SE and compilation time only |
Constraints Table
| C# | A# | Use Cases# | Description |
|---|---|---|---|
| C1 | - | - | Dependency on the APT tool specific to the SUN JDK 1.5.0? Yes (tools.jar)
Determine if we are ok running on the IBM J9 JVM and WLS JRockit JVM in SE mode - Yes both have tools.jar. |
Metamodel Interface Class Structure
The criteria API runs on top of the metamodel API and expects that classes of the form X_ exist. It is the resposibility of the metamodel to create and compile these enhanced classes. We will start this investigation by using the ATP tool.
Running APT to create AnnotationProcessorFactory classes
APT Static Usage
- Start with the following APT tutorial by SUN that shows how to list class names
- Create an SE JPA project - remember to include the provider resource \jpa\org.eclipse.persistence.jpa\resource\META-INF\services\javax.persistence.spi.PersistenceProvider
- Add the EclipseLink classpath variable TOOLS_LIB = tools.jar so we can import com.sun.mirror
- Create an AnnotationProcessorFactory class
- Create a pointer to this class
- Create a UTF8 no extension text file com.sun.mirror.apt.AnnotationProcessorFactory with the content org.eclipse.persistence.apt.MetamodelAnnotationProcessorFactory
- Delete the 3 chars upside down ?.. before the same - so we do not get Illegal provider-class name: ?org
- Place this class into META-INF/services
- Run APT in this project
- Verify the following classes were created
- MetamodelAnnotationProcessorFactory$ListClassAp$ListClassVisitor.class
- MetamodelAnnotationProcessorFactory$ListClassAp.class
- Verify the following classes were created
APT Dynamic Usage
Design
API
Metamodel and Criteria packages interfaces API
The following static UML class diagram that illustrates the relationship between the Criteria and Metamodel API's will serve as a basis for the metamodel API part of this work.
Public API
Internal API
Annotation Processors
We require a design time annotation processing tool to create metamodel class files X_. The APT tool that has shipped since JDK 1.5 will be used to process and create our annotation factories.
APT
APT is the annotation processing tool that has been shipped since Java 5.
Design Criteria
Security
Concurrency
Performance
Configuration
Dependencies
- We have a compile time dependency on tools.jar for the com.sun.mirror packages.
Use Cases
Use cases have traceability back to their requirements and constraints via their id# and have a 1-1 correspondence with test cases.
| Use Case ID# | Assumptions# | Requirements# | Description |
|---|---|---|---|
| UC1 | - | - | Construct object-based query definition object |
Concrete Use Cases
Details on each use case.
UC1:
- Preconditions
- Postconditions
- Path
- Exceptions
Variant Use Cases
Details on each variant (negative test) use case.
Implementation
Module Reuse
How much of the existing JPA annotation processor will be used or transitioned?
Modified Modules
New Modules
Testing
Example Code
Test Results
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 |
|---|---|---|
| I1 20090304 | mobrien | compile time dependency on tools.jar for com.sun.mirror packages |
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 |
|---|---|---|
Documentation
Wiki and formal documentation links here.
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.