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/317962/Phase1"
(→Annotations) |
(→XmlIsSetNullPolicy) |
||
(26 intermediate revisions by the same user not shown) | |||
Line 8: | Line 8: | ||
The following annotations will be targeted in this phase: | The following annotations will be targeted in this phase: | ||
− | {| | + | {|{{BMTableStyle}} |
− | |- | + | |-{{BMTHStyle}} |
! Annotation | ! Annotation | ||
! XML Metadata Tag | ! XML Metadata Tag | ||
Line 17: | Line 17: | ||
! Method | ! Method | ||
|- | |- | ||
− | | XmlReadOnly | + | | XmlReadOnly |
− | | read-only | + | | read-only |
+ | | align="center" | | ||
| align="center" | | | align="center" | | ||
− | + | | align="center" | X | |
− | | align="center" | X | + | |
| align="center" | X | | align="center" | X | ||
|- | |- | ||
− | | XmlWriteOnly | + | | XmlWriteOnly |
− | | write-only | + | | write-only |
− | | align="center" | | + | | align="center" | |
− | | align="center" | | + | | align="center" | |
− | | align="center" | X | + | | align="center" | X |
| align="center" | X | | align="center" | X | ||
|- | |- | ||
− | | XmlCDATA | + | | XmlCDATA |
− | | cdata | + | | cdata |
+ | | align="center" | | ||
| align="center" | | | align="center" | | ||
− | + | | align="center" | X | |
− | | align="center" | X | + | |
| align="center" | X | | align="center" | X | ||
|- | |- | ||
Line 85: | Line 85: | ||
The following example will demonstrate how the XmlReadOnly annotation can be applied: | The following example will demonstrate how the XmlReadOnly annotation can be applied: | ||
− | A property can be configured to be read-only via XML metadata as follows: | + | === read-only === |
+ | A property can be configured to be read-only via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] as follows: | ||
<source lang="xml"> | <source lang="xml"> | ||
<xml-attribute java-attribute="salary" read-only="true" /> | <xml-attribute java-attribute="salary" read-only="true" /> | ||
</source> | </source> | ||
+ | === XmlReadOnly === | ||
The equivalent configured via annotations would look like: | The equivalent configured via annotations would look like: | ||
<source lang="java"> | <source lang="java"> | ||
Line 107: | Line 109: | ||
@Target({ElementType.FIELD, ElementType.METHOD}) | @Target({ElementType.FIELD, ElementType.METHOD}) | ||
@Retention(RetentionPolicy.RUNTIME) | @Retention(RetentionPolicy.RUNTIME) | ||
− | public @interface XmlReadOnly { | + | public @interface XmlReadOnly {} |
− | + | ||
− | } | + | |
</source> | </source> | ||
Line 116: | Line 116: | ||
The following example will demonstrate how the XmlWriteOnly annotation can be applied: | The following example will demonstrate how the XmlWriteOnly annotation can be applied: | ||
− | A property can be configured to be write-only via XML metadata as follows: | + | === write-only === |
+ | A property can be configured to be write-only via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] as follows: | ||
<source lang="xml"> | <source lang="xml"> | ||
− | <xml-attribute java-attribute=" | + | <xml-attribute java-attribute="privateData" write-only="true" /> |
</source> | </source> | ||
+ | === XmlWriteOnly === | ||
The equivalent configured via annotations would look like: | The equivalent configured via annotations would look like: | ||
<source lang="java"> | <source lang="java"> | ||
Line 128: | Line 130: | ||
@javax.xml.bind.annotation.XmlAttribute | @javax.xml.bind.annotation.XmlAttribute | ||
@org.eclipse.persistence.oxm.annotations.XmlWriteOnly | @org.eclipse.persistence.oxm.annotations.XmlWriteOnly | ||
− | public String | + | public String privateData; |
} | } | ||
</source> | </source> | ||
Line 138: | Line 140: | ||
@Target({ElementType.FIELD, ElementType.METHOD}) | @Target({ElementType.FIELD, ElementType.METHOD}) | ||
@Retention(RetentionPolicy.RUNTIME) | @Retention(RetentionPolicy.RUNTIME) | ||
− | public @interface XmlWriteOnly { | + | public @interface XmlWriteOnly {} |
− | Boolean value(); | + | </source> |
+ | |||
+ | == Example: XmlCDATA annotation == | ||
+ | |||
+ | The following example will demonstrate how the XmlCDATA annotation can be applied: | ||
+ | |||
+ | === cdata === | ||
+ | A property can be configured as CDATA (character data) via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] as follows: | ||
+ | <source lang="xml"> | ||
+ | <xml-element java-attribute="characterData" cdata="true" /> | ||
+ | </source> | ||
+ | |||
+ | === XmlCData === | ||
+ | The equivalent configured via annotations would look like: | ||
+ | <source lang="java"> | ||
+ | package org.example; | ||
+ | |||
+ | public class Employee { | ||
+ | @javax.xml.bind.annotation.XmlElement | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlCDATA | ||
+ | public String characterData; | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | Following is the proposed XmlCDATA annotation: | ||
+ | <source lang="java"> | ||
+ | package org.eclipse.persistence.oxm.annotations; | ||
+ | |||
+ | @Target({ElementType.FIELD, ElementType.METHOD}) | ||
+ | @Retention(RetentionPolicy.RUNTIME) | ||
+ | public @interface XmlCDATA {} | ||
+ | </source> | ||
+ | |||
+ | == Example: XmlAccessMethods annotation == | ||
+ | |||
+ | The following example will demonstrate how the XmlAccessMethods annotation can be applied: | ||
+ | |||
+ | === xml-access-methods === | ||
+ | A property's accessor methods can be configured via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] as follows: | ||
+ | <source lang="xml"> | ||
+ | <xml-element java-attribute="firstName"> | ||
+ | <xml-access-methods get-method="getFirstName" set-method="setFirstName" /> | ||
+ | </xml-element> | ||
+ | </source> | ||
+ | |||
+ | === XmlAccessMethods === | ||
+ | The equivalent configured via annotations would look like: | ||
+ | <source lang="java"> | ||
+ | package org.example; | ||
+ | |||
+ | public class Employee { | ||
+ | @javax.xml.bind.annotation.XmlElement | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlAccessMethods(getMethodName="getFirstName", setMethodName="setFirstName") | ||
+ | public String firstName; | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | Following is the proposed XmlAccessMethods annotation: | ||
+ | <source lang="java"> | ||
+ | package org.eclipse.persistence.oxm.annotations; | ||
+ | |||
+ | @Target({ElementType.FIELD, ElementType.METHOD}) | ||
+ | @Retention(RetentionPolicy.RUNTIME) | ||
+ | public @interface XmlAccessMethods { | ||
+ | String getMethodName() default ""; | ||
+ | String setMethodName() default ""; | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | == Example: XmlPaths annotation == | ||
+ | |||
+ | The following example will demonstrate how the XmlPaths annotation can be applied: | ||
+ | |||
+ | === xml-path === | ||
+ | Path-based mappings on <code>xml-element</code> entries within an <code>xml-elements</code> structure can be configured via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] as follows: | ||
+ | <source lang="xml"> | ||
+ | <xml-elements java-attribute="things"> | ||
+ | <xml-access-methods get-method="getThings" set-method="setThings" /> | ||
+ | <xml-element type="java.lang.Integer" xml-path="integers/my-integer/text()" /> | ||
+ | <xml-element type="java.lang.Float" xml-path="floats/my-float/text()" /> | ||
+ | </xml-elements> | ||
+ | </source> | ||
+ | |||
+ | === XmlPaths === | ||
+ | The equivalent configured via annotations would look like: | ||
+ | <source lang="java"> | ||
+ | @javax.xml.bind.annotation.XmlElements({ | ||
+ | @javax.xml.bind.annotation.XmlElement(type=java.lang.Integer.class), | ||
+ | @javax.xml.bind.annotation.XmlElement(type=java.lang.Float.class) | ||
+ | }) | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlPaths({ | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlPath("integers/my-integer"), | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlPath("floats/my-float") | ||
+ | }) | ||
+ | public List<Object> things; | ||
+ | </source> | ||
+ | |||
+ | Following is the proposed XmlPaths annotation: | ||
+ | <source lang="java"> | ||
+ | package org.eclipse.persistence.oxm.annotations; | ||
+ | |||
+ | @Target({ElementType.FIELD, ElementType.METHOD}) | ||
+ | @Retention(RetentionPolicy.RUNTIME) | ||
+ | public @interface XmlPaths { | ||
+ | XmlPath[] value(); | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | == Example: XmlNullPolicy annotation == | ||
+ | |||
+ | The following example will demonstrate how the XmlNullPolicy annotation can be applied: | ||
+ | |||
+ | === xml-null-policy === | ||
+ | A property's null policy can be configured via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] as follows: | ||
+ | <source lang="xml"> | ||
+ | <xml-element java-attribute="something"> | ||
+ | <xml-null-policy xsi-nil-represents-null="false" empty-node-represents-null="false" null-representation-for-xml="EMPTY_NODE" is-set-performed-for-absent-node="true" /> | ||
+ | </xml-element> | ||
+ | </source> | ||
+ | |||
+ | === XmlNullPolicy === | ||
+ | The equivalent configured via annotations would look like: | ||
+ | <source lang="java"> | ||
+ | @javax.xml.bind.annotation.XmlElement | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlNullPolicy(xsiNilRepresentNull="false", | ||
+ | emptyNodeRepresentsNull="false", nullRepresentationForXml=XmlMarshalNullRepresentation.EMPTY_NODE, | ||
+ | isSetPerformedForAbsentNode="true") | ||
+ | public Object something; | ||
+ | </source> | ||
+ | |||
+ | Following is the proposed XmlNullPolicy annotation: | ||
+ | <source lang="java"> | ||
+ | package org.eclipse.persistence.oxm.annotations; | ||
+ | |||
+ | @Target({ElementType.FIELD, ElementType.METHOD}) | ||
+ | @Retention(RetentionPolicy.RUNTIME) | ||
+ | public @interface XmlNullPolicy { | ||
+ | |||
+ | boolean xsiNilRepresentsNull() default false; | ||
+ | |||
+ | boolean emptyNodeRepresentsNull() default false; | ||
+ | |||
+ | boolean isSetPerformedForAbsentNode() default true; | ||
+ | |||
+ | XmlMarshalNullRepresentation nullRepresentationForXml() default org.eclipse.persistence.oxm.annotations.XmlMarshalNullRepresentation.ABSENT_NODE; | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | == Example: XmlIsSetNullPolicy annotation == | ||
+ | |||
+ | The following example will demonstrate how the XmlIsSetNullPolicy annotation can be applied: | ||
+ | |||
+ | === xml-is-set-null-policy === | ||
+ | A property's is set null policy can be configured via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] as follows: | ||
+ | <source lang="xml"> | ||
+ | <xml-element java-attribute="some-element" name="some-string"> | ||
+ | <xml-is-set-null-policy xsi-nil-represents-null="true" empty-node-represents-null="false" null-representation-for-xml="XSI_NIL" is-set-method-name="isSetSomeString"> | ||
+ | <is-set-parameter value="false" type="java.lang.Boolean" /> | ||
+ | </xml-is-set-null-policy> | ||
+ | </xml-element> | ||
+ | </source> | ||
+ | |||
+ | === XmlIsSetNullPolicy === | ||
+ | The equivalent configured via annotations would look like: | ||
+ | <source lang="java"> | ||
+ | @javax.xml.bind.annotation.XmlElement | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlIsSetNullPolicy(xsiNilRepresentsNull="true", | ||
+ | emptyNodeRepresentsNull="false", | ||
+ | nullRepresentationForXml=XmlMarshalNullRepresentation.XSI_NIL, | ||
+ | isSetMethodName="isSetSomething", | ||
+ | isSetParameters= { | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlParameter(value="somevalue", type=String.class), | ||
+ | @org.eclipse.persistence.oxm.annotations.XmlParameter(value="false", type=Boolean.class) | ||
+ | }) | ||
+ | public Object something; | ||
+ | </source> | ||
+ | |||
+ | Following is the proposed XmlIsSetNullPolicy annotation: | ||
+ | <source lang="java"> | ||
+ | package org.eclipse.persistence.oxm.annotations; | ||
+ | |||
+ | @Target({ElementType.FIELD, ElementType.METHOD}) | ||
+ | @Retention(RetentionPolicy.RUNTIME) | ||
+ | public @interface XmlIsSetNullPolicy { | ||
+ | boolean xsiNilRepresentsNull() default false; | ||
+ | |||
+ | boolean emptyNodeRepresentsNull() default false; | ||
+ | |||
+ | XmlMarshalNullRepresentation nullRepresentationForXml() default org.eclipse.persistence.oxm.annotations.XmlMarshalNullRepresentation.ABSENT_NODE; | ||
+ | |||
+ | String isSetMethodName(); | ||
+ | |||
+ | XmlParameter[] isSetParameters() default {}; | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | === XmlParameter === | ||
+ | Following is the proposed XmlParameter annotation: | ||
+ | <source lang="java"> | ||
+ | package org.eclipse.persistence.oxm.annotations; | ||
+ | |||
+ | @Retention(RetentionPolicy.RUNTIME) | ||
+ | public @interface XmlParameter { | ||
+ | String value(); | ||
+ | Class type(); | ||
} | } | ||
</source> | </source> |
Latest revision as of 14:18, 17 November 2010
Contents
- 1 Phase 1 - Provide MOXy annotation support equivalent to our XML metadata support
Phase 1 - Provide MOXy annotation support equivalent to our XML metadata support
This phase of development involves providing MOXy annotation support equivalent to the existing EclipseLink XML metadata support
Annotations
The following annotations will be targeted in this phase:
Annotation | XML Metadata Tag | Package | Type | Field | Method |
---|---|---|---|---|---|
XmlReadOnly | read-only | X | X | ||
XmlWriteOnly | write-only | X | X | ||
XmlCDATA | cdata | X | X | ||
XmlAccessMethods | xml-access-methods | X | X | ||
XmlPaths | xml-elements | X | X | ||
XmlNullPolicy | xml-null-policy | X | X | ||
XmlIsSetNullPolicy | xml-is-set-null-policy | X | X | ||
XmlIsSetParameters | n/a | X | X | ||
XmlIsSetParameter | is-set-parameter | X | X |
Example: XmlReadOnly annotation
The following example will demonstrate how the XmlReadOnly annotation can be applied:
read-only
A property can be configured to be read-only via EclipseLink XML metadata as follows:
<xml-attribute java-attribute="salary" read-only="true" />
XmlReadOnly
The equivalent configured via annotations would look like:
package org.example; public class Employee { @javax.xml.bind.annotation.XmlAttribute @org.eclipse.persistence.oxm.annotations.XmlReadOnly public String salary; }
Following is the proposed XmlReadOnly annotation:
package org.eclipse.persistence.oxm.annotations; @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface XmlReadOnly {}
Example: XmlWriteOnly annotation
The following example will demonstrate how the XmlWriteOnly annotation can be applied:
write-only
A property can be configured to be write-only via EclipseLink XML metadata as follows:
<xml-attribute java-attribute="privateData" write-only="true" />
XmlWriteOnly
The equivalent configured via annotations would look like:
package org.example; public class Employee { @javax.xml.bind.annotation.XmlAttribute @org.eclipse.persistence.oxm.annotations.XmlWriteOnly public String privateData; }
Following is the proposed XmlWriteOnly annotation:
package org.eclipse.persistence.oxm.annotations; @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface XmlWriteOnly {}
Example: XmlCDATA annotation
The following example will demonstrate how the XmlCDATA annotation can be applied:
cdata
A property can be configured as CDATA (character data) via EclipseLink XML metadata as follows:
<xml-element java-attribute="characterData" cdata="true" />
XmlCData
The equivalent configured via annotations would look like:
package org.example; public class Employee { @javax.xml.bind.annotation.XmlElement @org.eclipse.persistence.oxm.annotations.XmlCDATA public String characterData; }
Following is the proposed XmlCDATA annotation:
package org.eclipse.persistence.oxm.annotations; @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface XmlCDATA {}
Example: XmlAccessMethods annotation
The following example will demonstrate how the XmlAccessMethods annotation can be applied:
xml-access-methods
A property's accessor methods can be configured via EclipseLink XML metadata as follows:
<xml-element java-attribute="firstName"> <xml-access-methods get-method="getFirstName" set-method="setFirstName" /> </xml-element>
XmlAccessMethods
The equivalent configured via annotations would look like:
package org.example; public class Employee { @javax.xml.bind.annotation.XmlElement @org.eclipse.persistence.oxm.annotations.XmlAccessMethods(getMethodName="getFirstName", setMethodName="setFirstName") public String firstName; }
Following is the proposed XmlAccessMethods annotation:
package org.eclipse.persistence.oxm.annotations; @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface XmlAccessMethods { String getMethodName() default ""; String setMethodName() default ""; }
Example: XmlPaths annotation
The following example will demonstrate how the XmlPaths annotation can be applied:
xml-path
Path-based mappings on xml-element
entries within an xml-elements
structure can be configured via EclipseLink XML metadata as follows:
<xml-elements java-attribute="things"> <xml-access-methods get-method="getThings" set-method="setThings" /> <xml-element type="java.lang.Integer" xml-path="integers/my-integer/text()" /> <xml-element type="java.lang.Float" xml-path="floats/my-float/text()" /> </xml-elements>
XmlPaths
The equivalent configured via annotations would look like:
@javax.xml.bind.annotation.XmlElements({ @javax.xml.bind.annotation.XmlElement(type=java.lang.Integer.class), @javax.xml.bind.annotation.XmlElement(type=java.lang.Float.class) }) @org.eclipse.persistence.oxm.annotations.XmlPaths({ @org.eclipse.persistence.oxm.annotations.XmlPath("integers/my-integer"), @org.eclipse.persistence.oxm.annotations.XmlPath("floats/my-float") }) public List<Object> things;
Following is the proposed XmlPaths annotation:
package org.eclipse.persistence.oxm.annotations; @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface XmlPaths { XmlPath[] value(); }
Example: XmlNullPolicy annotation
The following example will demonstrate how the XmlNullPolicy annotation can be applied:
xml-null-policy
A property's null policy can be configured via EclipseLink XML metadata as follows:
<xml-element java-attribute="something"> <xml-null-policy xsi-nil-represents-null="false" empty-node-represents-null="false" null-representation-for-xml="EMPTY_NODE" is-set-performed-for-absent-node="true" /> </xml-element>
XmlNullPolicy
The equivalent configured via annotations would look like:
@javax.xml.bind.annotation.XmlElement @org.eclipse.persistence.oxm.annotations.XmlNullPolicy(xsiNilRepresentNull="false", emptyNodeRepresentsNull="false", nullRepresentationForXml=XmlMarshalNullRepresentation.EMPTY_NODE, isSetPerformedForAbsentNode="true") public Object something;
Following is the proposed XmlNullPolicy annotation:
package org.eclipse.persistence.oxm.annotations; @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface XmlNullPolicy { boolean xsiNilRepresentsNull() default false; boolean emptyNodeRepresentsNull() default false; boolean isSetPerformedForAbsentNode() default true; XmlMarshalNullRepresentation nullRepresentationForXml() default org.eclipse.persistence.oxm.annotations.XmlMarshalNullRepresentation.ABSENT_NODE; }
Example: XmlIsSetNullPolicy annotation
The following example will demonstrate how the XmlIsSetNullPolicy annotation can be applied:
xml-is-set-null-policy
A property's is set null policy can be configured via EclipseLink XML metadata as follows:
<xml-element java-attribute="some-element" name="some-string"> <xml-is-set-null-policy xsi-nil-represents-null="true" empty-node-represents-null="false" null-representation-for-xml="XSI_NIL" is-set-method-name="isSetSomeString"> <is-set-parameter value="false" type="java.lang.Boolean" /> </xml-is-set-null-policy> </xml-element>
XmlIsSetNullPolicy
The equivalent configured via annotations would look like:
@javax.xml.bind.annotation.XmlElement @org.eclipse.persistence.oxm.annotations.XmlIsSetNullPolicy(xsiNilRepresentsNull="true", emptyNodeRepresentsNull="false", nullRepresentationForXml=XmlMarshalNullRepresentation.XSI_NIL, isSetMethodName="isSetSomething", isSetParameters= { @org.eclipse.persistence.oxm.annotations.XmlParameter(value="somevalue", type=String.class), @org.eclipse.persistence.oxm.annotations.XmlParameter(value="false", type=Boolean.class) }) public Object something;
Following is the proposed XmlIsSetNullPolicy annotation:
package org.eclipse.persistence.oxm.annotations; @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface XmlIsSetNullPolicy { boolean xsiNilRepresentsNull() default false; boolean emptyNodeRepresentsNull() default false; XmlMarshalNullRepresentation nullRepresentationForXml() default org.eclipse.persistence.oxm.annotations.XmlMarshalNullRepresentation.ABSENT_NODE; String isSetMethodName(); XmlParameter[] isSetParameters() default {}; }
XmlParameter
Following is the proposed XmlParameter annotation:
package org.eclipse.persistence.oxm.annotations; @Retention(RetentionPolicy.RUNTIME) public @interface XmlParameter { String value(); Class type(); }