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.
Difference between revisions of "EclipseLink/DesignDocs/277920"
Line 1: | Line 1: | ||
− | <div style=" | + | <div style="border: 1px solid rgb(0, 0, 0); margin: 5px; padding: 5px; float: right;">__TOC__</div> |
− | = Design Specification: OXM XSD = | + | = Design Specification: OXM XSD = |
− | [http://bugs.eclipse.org/277920 ER 277920] | + | [http://bugs.eclipse.org/277920 ER 277920] |
− | == Document History == | + | == Document History == |
− | {| | + | |
− | |- | + | {| |
− | ! Date | + | |- |
− | ! Author | + | ! Date |
− | ! Version Description & Notes | + | ! Author |
− | |- | + | ! Version Description & Notes |
− | | 2009/05/26 | + | |- |
− | | Blaise Doughan | + | | 2009/05/26 |
+ | | Blaise Doughan | ||
| Skeleton | | Skeleton | ||
− | |- | + | |- |
− | | 2009/11/09 | + | | 2009/11/09 |
− | | David McCann | + | | David McCann |
− | | Added information pertaining to JAXB annotation support design phases. | + | | Added information pertaining to JAXB annotation support design phases. Moving phases 6 - 10, WebService support and OXM mapping support to design document for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=293925 ER 293925] |
|} | |} | ||
− | == Project overview == | + | == Project overview == |
− | Goals: | + | Goals: |
− | + | ||
− | + | *Support a limited number JAXB 2.1 annotations via XML external metadata | |
− | + | == Concepts == | |
− | + | None to mention. | |
− | + | == Requirements == | |
− | + | The following sections will expand the goals of this project into more concrete requirements. | |
− | == | + | == Design Constraints == |
− | + | === JAXB Annotations === | |
− | + | The XML should have the same feel as the JAXB annotations. | |
− | + | [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/package-summary.html javax.xml.bind.annotation Javadoc] | |
− | + | === EclipseLink JPA Metadata === | |
− | + | The XML should have the same feel as the equivalent XML for EclipseLink JPA | |
− | + | [http://wiki.eclipse.org/EclipseLink/Development/1.0/ER-200040_DS_M4 EclipseLink JPA XSD] | |
− | + | === EclipseLink MOXy Metadata === | |
− | + | The metadata that will be available in EclipseLink 2.0 is outlined below. | |
− | == | + | == Design Phases == |
− | + | === JAXB 2.1 annotation support via XML external metadata === | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | This support will be added as outlined in the following phases: | |
− | + | *[http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase1 Phase #1 – Bootstrapping] | |
+ | **Use EclipseLink external metadata file to provide list of classes | ||
+ | **Allow basic schema to be generated | ||
+ | *[http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase2 Phase #2 – High Level Metadata] | ||
+ | **Provide core type metadata | ||
+ | *[http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase3 Phase #3 – Containment Mappings] | ||
+ | **Provide support for nested data. The the following MOXy mappings will be utilized: | ||
+ | ***Direct | ||
+ | ***Direct Collection | ||
+ | ***Composite Object | ||
+ | ***Composite Collection | ||
+ | *[http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase4 Phase #4 – Any/Choice Content] | ||
+ | **Provide support for wild card data. The the following MOXy mappings will be utilized: | ||
+ | ***Any | ||
+ | ***Any Collection | ||
+ | ***Any Attribute | ||
+ | *[http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase5 Phase #5 – Reference Mappings] | ||
+ | **Provide support for key based mappings. The the following MOXy mappings will be utilized: | ||
+ | ***Object Reference | ||
+ | ***Collection Reference | ||
− | == | + | == Design / Functionality == |
− | + | === XML Schema === | |
− | ==== | + | ==== Naming Convention ==== |
− | The | + | The XML names are based directly on the corresponding annotation name. The annotation name is lower cased, and hyphens ('-') are used as separators between each word in the name. For example, the annotation <code>XmlJavaTypeAdapter</code> would correspond to <code>xml-java-type-adapter</code> in XML. |
− | + | ==== Annotations to XML ==== | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
+ | The following table outlines the annotations that map to global elements: | ||
+ | |||
+ | {| | ||
+ | |- | ||
+ | ! Annotation | ||
+ | ! XML | ||
+ | ! Global Element | ||
+ | ! Global Attribute | ||
+ | ! Local Element | ||
+ | ! Local Attribute | ||
+ | ! Enum | ||
+ | |- | ||
+ | | XmlAccessorOrder | ||
+ | | xml-accessor-order | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlAccessorType | ||
+ | | xml-accessor-type | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlAnyAttribute | ||
+ | | xml-any-attribute | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlAnyElement | ||
+ | | xml-any-element | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlAttribute | ||
+ | | xml-attribute | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlBidirectional (MOXy) | ||
+ | | xml-bidirectional | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlElement | ||
+ | | xml-element | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlElementWrapper | ||
+ | | xml-element-wrapper | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlID | ||
+ | | xml-id | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlIDREF | ||
+ | | xml-idref | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlJavaTypeAdapter | ||
+ | | xml-java-type-adapter | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlJavaTypeAdapters | ||
+ | | xml-java-type-adapters | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlList | ||
+ | | xml-List | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlMixed | ||
+ | | xml-mixed | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlNs | ||
+ | | xml-ns | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlRootElement | ||
+ | | xml-root-element | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlSchema | ||
+ | | xml-schema | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlSeeAlso | ||
+ | | xml-see-also | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlTransient | ||
+ | | xml-transient | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlType | ||
+ | | xml-type | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |- | ||
+ | | XmlValue | ||
+ | | xml-value | ||
+ | | align="center" | X | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | | align="center" | | ||
+ | |} | ||
− | The following table outlines the Java Enums that map to XML Enums | + | <br> The following table outlines the Java Enums that map to XML Enums |
− | {| | + | {| |
− | |- | + | |- |
− | ! Java Enum | + | ! Java Enum |
! XML Enum | ! XML Enum | ||
− | |- | + | |- |
− | | XmlAccessOrder | + | | XmlAccessOrder |
| xml-access-order | | xml-access-order | ||
− | |- | + | |- |
− | | XmlAccessType | + | | XmlAccessType |
| xml-access-type | | xml-access-type | ||
− | |- | + | |- |
− | | XmlNsForm | + | | XmlNsForm |
| xml-ns-form | | xml-ns-form | ||
|} | |} | ||
+ | <br> | ||
− | ==== all vs. sequence ==== | + | ==== all vs. sequence ==== |
− | Where applicable xs:all is used instead of xs:sequence, such that specific ordering is not required. | + | Where applicable xs:all is used instead of xs:sequence, such that specific ordering is not required. This is done to avoid placing an unnecessary requirement on the user. |
− | ==== Schema file ==== | + | ==== Schema file ==== |
− | The XML schema that will be supported in EclipseLink 2.0 follows: | + | The XML schema that will be supported in EclipseLink 2.0 follows: |
<source lang="xml"> | <source lang="xml"> | ||
Line 336: | Line 467: | ||
</xs:element> | </xs:element> | ||
<xs:element name="xml-any-element" substitutionGroup="java-attribute"> | <xs:element name="xml-any-element" substitutionGroup="java-attribute"> | ||
− | <xs:complexType> | + | <xs:complexType>fckLR <xs:complexContent> |
− | + | ||
<xs:extension base="java-attribute"> | <xs:extension base="java-attribute"> | ||
<xs:all> | <xs:all> | ||
Line 392: | Line 522: | ||
</xs:element> | </xs:element> | ||
</xs:schema> | </xs:schema> | ||
− | </source> | + | </source> |
− | ==== XML Bindings ==== | + | ==== XML Bindings ==== |
− | A given XML metadata bindings file will correspond to a single package. | + | A given XML metadata bindings file will correspond to a single package. This association is made by using the package name for the key in the properties map that is passed in to the JAXBContext. See [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920#Boot_Strapping below] for information on boot strapping the JAXBContext. The bindings file may contain information that applies to the entire package, as well as class-specific information. The <code>java-type</code> element is used for a java class. Each <code>java-type</code> may have a number of attributes and sub-elements set (refer to the [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920#Schema_file XML Schema] above for more information) as well as zero or more <code>java-attributes</code>. A <code>java-attribute</code> corresponds to a property (field/method). In order to handle various settings applicable to a given property, a number of <code>java-attribute</code> extensions exist: |
− | * xml-java-type-adapter | + | *xml-java-type-adapter |
− | * xml-transient | + | *xml-transient |
− | * xml-any-attribute | + | *xml-any-attribute |
− | * xml-attribute | + | *xml-attribute |
− | * xml-any-element | + | *xml-any-element |
− | * xml-element | + | *xml-element |
− | * xml-value | + | *xml-value |
− | ===== Example ===== | + | ===== Example ===== |
− | Following is a simple example showing <code>java-attribute</code> use in a bindings file. | + | Following is a simple example showing <code>java-attribute</code> use in a bindings file. Here, the 'id' property is set as an attribute and made required, the 'name' property is renamed 'employee-name', and the 'thing' property is set transient. Note that the 'java-attribute' attribute in each corresponds to the field name or method name (for methods, is/set/get is stripped off and the first letter is lower cased). |
− | ====== org.example.Employee.java ====== | + | ====== org.example.Employee.java ====== |
<source lang="java"> | <source lang="java"> | ||
Line 427: | Line 557: | ||
} | } | ||
} | } | ||
− | </source> | + | </source> |
− | ====== eclipselink-oxm.xml ====== | + | ====== eclipselink-oxm.xml ====== |
<source lang="xml"> | <source lang="xml"> | ||
Line 444: | Line 574: | ||
</java-types> | </java-types> | ||
</xml-bindings> | </xml-bindings> | ||
− | </source> | + | </source> |
− | === Boot Strapping === | + | === Boot Strapping === |
− | ==== Specifying the Externalized Metadata File ==== | + | ==== Specifying the Externalized Metadata File ==== |
− | The externalized metadata file (one per package) can be passed in through a property when creating the JAXBContext. | + | The externalized metadata file (one per package) can be passed in through a property when creating the JAXBContext. |
<source lang="java"> | <source lang="java"> | ||
Line 466: | Line 596: | ||
JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties); | JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties); | ||
− | </source> | + | </source> |
− | Following is an example of how to pass in the property when creating the JAXBContext based on an array of classes: | + | Following is an example of how to pass in the property when creating the JAXBContext based on an array of classes: |
<source lang="java"> | <source lang="java"> | ||
Line 475: | Line 605: | ||
classes[1] = Employee.class; | classes[1] = Employee.class; | ||
JAXBContext.newInstance(classes, properties); | JAXBContext.newInstance(classes, properties); | ||
− | </source> | + | </source> |
− | == Testing == | + | == Testing == |
− | == API == | + | == API == |
− | == GUI == | + | == GUI == |
− | == Config files == | + | == Config files == |
− | == Documentation == | + | == Documentation == |
− | == Open Issues == | + | == Open Issues == |
− | This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements. | + | This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements. |
− | {| | + | {| |
− | |- | + | |- |
− | ! Issue # | + | ! Issue # |
− | ! Owner | + | ! Owner |
! Description / Notes | ! Description / Notes | ||
− | |- | + | |- |
− | | | + | | |
− | | | + | | |
− | | | + | | |
|} | |} | ||
− | == Decisions == | + | == 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. | + | 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 # | + | ! Issue # |
− | ! Description / Notes | + | ! Description / Notes |
! Decision | ! Decision | ||
− | |- | + | |- |
− | | | + | | |
− | | | + | | |
− | | | + | | |
|} | |} | ||
− | == Future Considerations == | + | == 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. | 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. |
Revision as of 10:11, 12 November 2009
Contents
Design Specification: OXM XSD
Document History
Date | Author | Version Description & Notes |
---|---|---|
2009/05/26 | Blaise Doughan | Skeleton |
2009/11/09 | David McCann | Added information pertaining to JAXB annotation support design phases. Moving phases 6 - 10, WebService support and OXM mapping support to design document for ER 293925 |
Project overview
Goals:
- Support a limited number JAXB 2.1 annotations via XML external metadata
Concepts
None to mention.
Requirements
The following sections will expand the goals of this project into more concrete requirements.
Design Constraints
JAXB Annotations
The XML should have the same feel as the JAXB annotations.
javax.xml.bind.annotation Javadoc
EclipseLink JPA Metadata
The XML should have the same feel as the equivalent XML for EclipseLink JPA
EclipseLink MOXy Metadata
The metadata that will be available in EclipseLink 2.0 is outlined below.
Design Phases
JAXB 2.1 annotation support via XML external metadata
This support will be added as outlined in the following phases:
- Phase #1 – Bootstrapping
- Use EclipseLink external metadata file to provide list of classes
- Allow basic schema to be generated
- Phase #2 – High Level Metadata
- Provide core type metadata
- Phase #3 – Containment Mappings
- Provide support for nested data. The the following MOXy mappings will be utilized:
- Direct
- Direct Collection
- Composite Object
- Composite Collection
- Provide support for nested data. The the following MOXy mappings will be utilized:
- Phase #4 – Any/Choice Content
- Provide support for wild card data. The the following MOXy mappings will be utilized:
- Any
- Any Collection
- Any Attribute
- Provide support for wild card data. The the following MOXy mappings will be utilized:
- Phase #5 – Reference Mappings
- Provide support for key based mappings. The the following MOXy mappings will be utilized:
- Object Reference
- Collection Reference
- Provide support for key based mappings. The the following MOXy mappings will be utilized:
Design / Functionality
XML Schema
Naming Convention
The XML names are based directly on the corresponding annotation name. The annotation name is lower cased, and hyphens ('-') are used as separators between each word in the name. For example, the annotation XmlJavaTypeAdapter
would correspond to xml-java-type-adapter
in XML.
Annotations to XML
The following table outlines the annotations that map to global elements:
Annotation | XML | Global Element | Global Attribute | Local Element | Local Attribute | Enum |
---|---|---|---|---|---|---|
XmlAccessorOrder | xml-accessor-order | X | ||||
XmlAccessorType | xml-accessor-type | X | ||||
XmlAnyAttribute | xml-any-attribute | X | ||||
XmlAnyElement | xml-any-element | X | ||||
XmlAttribute | xml-attribute | X | ||||
XmlBidirectional (MOXy) | xml-bidirectional | X | ||||
XmlElement | xml-element | X | ||||
XmlElementWrapper | xml-element-wrapper | X | ||||
XmlID | xml-id | X | ||||
XmlIDREF | xml-idref | X | ||||
XmlJavaTypeAdapter | xml-java-type-adapter | X | ||||
XmlJavaTypeAdapters | xml-java-type-adapters | X | ||||
XmlList | xml-List | X | ||||
XmlMixed | xml-mixed | X | ||||
XmlNs | xml-ns | X | ||||
XmlRootElement | xml-root-element | X | ||||
XmlSchema | xml-schema | X | ||||
XmlSeeAlso | xml-see-also | X | ||||
XmlTransient | xml-transient | X | ||||
XmlType | xml-type | X | ||||
XmlValue | xml-value | X |
The following table outlines the Java Enums that map to XML Enums
Java Enum | XML Enum |
---|---|
XmlAccessOrder | xml-access-order |
XmlAccessType | xml-access-type |
XmlNsForm | xml-ns-form |
all vs. sequence
Where applicable xs:all is used instead of xs:sequence, such that specific ordering is not required. This is done to avoid placing an unnecessary requirement on the user.
Schema file
The XML schema that will be supported in EclipseLink 2.0 follows:
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" targetNamespace="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="xml-bindings"> <xs:complexType> <xs:all> <xs:element ref="xml-schema" /> <xs:element ref="xml-java-type-adapters" /> <xs:element name="java-types"> <xs:complexType> <xs:sequence> <xs:element ref="java-type" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> </xs:all> <xs:attribute name="xml-accessor-type" type="xml-access-type" default="PUBLIC_MEMBER" /> <xs:attribute name="xml-accessor-order" type="xml-access-order" default="UNDEFINED" /> </xs:complexType> </xs:element> <xs:element name="java-type"> <xs:complexType> <xs:all> <xs:element ref="xml-type" /> <xs:element ref="xml-root-element" /> <xs:element ref="xml-see-also" /> <xs:element ref="xml-java-type-adapter" /> <xs:element name="java-attributes"> <xs:complexType> <xs:sequence> <xs:element ref="java-attribute" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> </xs:all> <xs:attribute name="name" type="xs:string" /> <xs:attribute name="xml-transient" type="xs:boolean" default="false" /> <xs:attribute name="xml-customizer" type="xs:string" /> <xs:attribute name="xml-accessor-type" type="xml-access-type" default="PUBLIC_MEMBER" /> <xs:attribute name="xml-accessor-order" type="xml-access-order" default="UNDEFINED" /> </xs:complexType> </xs:element> <xs:element name="java-attribute" type="java-attribute" /> <xs:complexType name="java-attribute" abstract="true"> <xs:attribute name="java-attribute" type="xs:string" /> </xs:complexType> <!-- Enums --> <xs:simpleType name="xml-access-order"> <xs:restriction base="xs:string"> <xs:enumeration value="ALPHABETICAL" /> <xs:enumeration value="UNDEFINED" /> </xs:restriction> </xs:simpleType> <xs:simpleType name="xml-access-type"> <xs:restriction base="xs:string"> <xs:enumeration value="FIELD" /> <xs:enumeration value="NONE" /> <xs:enumeration value="PROPERTY" /> <xs:enumeration value="PUBLIC_MEMBER" /> </xs:restriction> </xs:simpleType> <xs:simpleType name="xml-ns-form"> <xs:restriction base="xs:string"> <xs:enumeration value="UNQUALIFIED" /> <xs:enumeration value="QUALIFIED" /> <xs:enumeration value="UNSET" /> </xs:restriction> </xs:simpleType> <!-- @Target(value=PACKAGE) --> <xs:element name="xml-schema"> <xs:complexType> <xs:sequence> <xs:element name="xml-ns" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:attribute name="namespace-uri" type="xs:string" /> <xs:attribute name="prefix" type="xs:string" /> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="attribute-form-default" type="xml-ns-form" default="UNSET" /> <xs:attribute name="element-form-default" type="xml-ns-form" default="UNSET" /> <xs:attribute name="location" type="xs:string" /> <xs:attribute name="namespace" type="xs:string" /> </xs:complexType> </xs:element> <xs:element name="xml-java-type-adapters"> <xs:complexType> <xs:sequence> <xs:element ref="xml-java-type-adapter" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> <!-- @Target(value={PACKAGE,FIELD,METHOD,TYPE,PARAMETER}) --> <xs:element name="xml-java-type-adapter" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:attribute name="value" type="xs:string" /> <xs:attribute name="type" type="xs:string" default="javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter.DEFAULT" /> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <!-- @Target(value={FIELD,METHOD,TYPE}) --> <xs:element name="xml-transient" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute" /> </xs:complexContent> </xs:complexType> </xs:element> <!-- @Target(value=TYPE) --> <xs:element name="xml-type"> <xs:complexType> <xs:attribute name="name" type="xs:string" default="##default" /> <xs:attribute name="namespace" type="xs:string" default="##default" /> <xs:attribute name="prop-order"> <xs:simpleType> <xs:list itemType="xs:string" /> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> <xs:element name="xml-root-element"> <xs:complexType> <xs:attribute name="name" type="xs:string" default="##default" /> <xs:attribute name="namespace" type="xs:string" default="##default" /> </xs:complexType> </xs:element> <xs:element name="xml-see-also"> <xs:simpleType> <xs:list itemType="xs:string" /> </xs:simpleType> </xs:element> <!-- @Target(value={FIELD,METHOD}) --> <xs:element name="xml-any-attribute" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-attribute" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element ref="xml-java-type-adapter" /> <xs:element ref="xml-bidirectional" /> </xs:all> <xs:attribute name="name" type="xs:string" default="##default" /> <xs:attribute name="namespace" type="xs:string" default="##default" /> <xs:attribute name="required" type="xs:boolean" default="false" /> <xs:attribute name="xml-id" type="xs:boolean" default="false" /> <xs:attribute name="xml-idref" type="xs:boolean" default="false" /> <xs:attribute name="xml-list" type="xs:boolean" default="false" /> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-any-element" substitutionGroup="java-attribute"> <xs:complexType>fckLR <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element ref="xml-java-type-adapter" /> </xs:all> <xs:attribute name="xml-mixed" type="xs:boolean" default="false" /> <xs:attribute name="lax" type="xs:boolean" default="false" /> <xs:attribute name="dom-handler" type="xs:string" default="javax.xml.bind.annotation.W3CDomHandler" /> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-element" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element ref="xml-element-wrapper" /> <xs:element ref="xml-java-type-adapter" /> <xs:element ref="xml-bidirectional" /> </xs:all> <xs:attribute name="name" type="xs:string" default="##default" /> <xs:attribute name="namespace" type="xs:string" default="##default" /> <xs:attribute name="default-value" type="xs:string" /> <xs:attribute name="nillable" type="xs:boolean" default="false" /> <xs:attribute name="required" type="xs:boolean" default="false" /> <xs:attribute name="type" type="xs:string" default="javax.xml.bind.annotation.XmlElement.DEFAULT" /> <xs:attribute name="xml-id" type="xs:boolean" default="false" /> <xs:attribute name="xml-idref" type="xs:boolean" default="false" /> <xs:attribute name="xml-list" type="xs:boolean" default="false" /> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-element-wrapper"> <xs:complexType> <xs:attribute name="name" type="xs:string" default="##default" /> <xs:attribute name="namespace" type="xs:string" default="##default" /> <xs:attribute name="nillable" type="xs:boolean" default="false" /> <xs:attribute name="required" type="xs:boolean" default="false" /> </xs:complexType> </xs:element> <xs:element name="xml-value" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-bidirectional"> <xs:complexType> <xs:attribute name="target-attribute" type="xs:string" /> </xs:complexType> </xs:element> </xs:schema>
XML Bindings
A given XML metadata bindings file will correspond to a single package. This association is made by using the package name for the key in the properties map that is passed in to the JAXBContext. See below for information on boot strapping the JAXBContext. The bindings file may contain information that applies to the entire package, as well as class-specific information. The java-type
element is used for a java class. Each java-type
may have a number of attributes and sub-elements set (refer to the XML Schema above for more information) as well as zero or more java-attributes
. A java-attribute
corresponds to a property (field/method). In order to handle various settings applicable to a given property, a number of java-attribute
extensions exist:
- xml-java-type-adapter
- xml-transient
- xml-any-attribute
- xml-attribute
- xml-any-element
- xml-element
- xml-value
Example
Following is a simple example showing java-attribute
use in a bindings file. Here, the 'id' property is set as an attribute and made required, the 'name' property is renamed 'employee-name', and the 'thing' property is set transient. Note that the 'java-attribute' attribute in each corresponds to the field name or method name (for methods, is/set/get is stripped off and the first letter is lower cased).
org.example.Employee.java
package org.example; public class Employee { public int id; public String name; private Object theThing; public void setThing(Object theThing) { this.theThing = theThing; } public Object getThing() { return theThing; } }
eclipselink-oxm.xml
<?xml version="1.0" encoding="US-ASCII"?> <xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"> <java-types> <java-type name="org.example.Employee"> <java-attributes> <xml-attribute java-attribute="id" required="true" /> <xml-element java-attribute="name" name="employee-name" /> <xml-transient java-attribute="thing" /> </java-attributes> </java-type> </java-types> </xml-bindings>
Boot Strapping
Specifying the Externalized Metadata File
The externalized metadata file (one per package) can be passed in through a property when creating the JAXBContext.
InputStream employeeExternalizedMetadata = aClassLoader.getResourceAsStream("org/example/employee/metadata.xml"; InputStream customerExternalizedMetadata = aClassLoader.getResourceAsStream("org/example/customer/metadata.xml"; HashMap<String, Source> metadataSourceMap = new HashMap<String, Source>(); metadataSourceMap.put("org.example.employee", new StreamSource(employeeExternalizedMetadata)); metadataSourceMap.put("org.example.customer", new StreamSource(customerExternalizedMetadata)); Map<String, Map<String, Source>> properties = new HashMap<String, Map<String, Source>>(); properties.put("eclipselink-oxm-xml", metadataSourceMap); JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties);
Following is an example of how to pass in the property when creating the JAXBContext based on an array of classes:
Class[] classes = new Class[2]; classes[0] = Customer.class; classes[1] = Employee.class; JAXBContext.newInstance(classes, properties);
Testing
API
GUI
Config files
Documentation
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.