Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Dali/Indigo/JAXB 2.x/ProjectContent
Contents
Functional Specification: JAXB Project Content
[enter bug location here]
Document History
| Date | Author | Version Description & Notes |
|---|---|---|
| 10-5-2010 | Paul Fullbright | Draft |
Feature overview
This feature is about determining the content of Dali JAXB projects.
Goals:
- Add JAXB annotated classes to project content
- Add JAXB annotated packages to project content
- Add statically referenced classes to project content
- Add support for jaxb.index
- Add support for ObjectFactory classes
- Add user specified default annotated packages and classes to project content
- Add external packages and classes to project content
Concepts
Unlike JPA, the context of a JAXB 'project' (the JAXBContext) is determined dynamically at runtime, not dev-time. The user determines what is included when he creates the JAXBContext object. In addition, JAXB classes and packages do not have to be annotated - defaults abound! - so determining what classes are intended for JAXB use without having that information is tricky.
A user may pass in a list of packages, or a list of classes, or a combination. In addition to those packages and classes, any statically referenced classes are also brought in. (e.g. If Foo has a mapping to Bar, then Bar is also brought in, but if Foo is only extended by Bar, then it is not; it has no actual reference to Bar.)
When a package is passed in, a jaxb.index or ObjectFactory is used to determine the specific classes that are to be brought in. The jaxb.index is a return-separated list of classes. Any classes statically referenced by the ObjectFactory are also brought in.
References
Requirements / Functionality
JAXB annotated classes
In the simplest scenario, we could simply add only those classes that have JAXB annotations to the project content. But this is also the least flexible.
JAXB annotated packages
Any package with a JAXB annotated package-info.java would be added to the project content. Such a package would require either a jaxb.index file or an ObjectFactory class, but we could instead simply add all classes in the package. This has the potentiality to be inaccurate, as some non-JAXB classes may be in the package and would be validated as though they were JAXB classes.
Statically referenced classes
Any classes that are statically referenced by existing JAXB classes' supertypes or JAXB fields or properties or by an ObjectFactory's create# methods are automatically brought in as JAXB classes (except for java.*/javax.*/org.w3c.* classes). This is more complete than only including annotated classes/packages, but it is more complicated. It also still might miss unannotated classes that are not directly referenced by any other JAXB class.
The EclipseLink implementation of this is in org.eclipse.persistence.jaxb.compiler.AnnotationProcessor
jaxb.index
A jaxb.index file is a return-separated list of classes found in a package to be included in a JAXB context. Supporting this would require supporting an additional file type.
ObjectFactory
An "ObjectFactory" class is a special class in a package. It is any class annotated with the @XmlRegistry annotation, but is usually named "ObjectFactory", and is usually only present when java classes are generated from a schema. Any such class brings in any classes referenced by its create# methods to the JAXB context. Supporting this would require treating some classes differently from standard JAXB classes. It would also require support for statically referenced classes, as described above. Supporting it also allows additional validation, and may actually be necessary to analyze @XmlElementDecl annotations.
@XmlElementDecl annotations are used on specific create methods to map an XML schema element declaration to a method that creates a JAXBElement that represents that element.
User specified packages/classes
A user would specify which classes/packages were to act as the context 'seed' of the project, to be stored in a dali-specific metadata file. This would add the burden of maintaining an additional metadata file, but it is probably the most complete/natural way to determine the user's intended project content.
External packages/classes
Any JAXB class may statically reference a class external to an eclipse project, whether it is binary (e.g. jar file) or in a separate project. Support for these would be similar to existing support for external classes in JPA.