@Xml(format) Annotation
The {@link oaj.xml.annotation.Xml#format() @Xml(format)} annotation can be used to tweak the XML format of a POJO. The value is set to an enum value of type {@link oaj.xml.annotation.XmlFormat}. This annotation can be applied to both classes and bean properties.
The {@link oaj.xml.annotation.XmlFormat#ATTR} format can be applied to bean properties to serialize them as XML attributes instead of elements. Note that this only supports properties of simple types (e.g. strings, numbers, booleans).
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: |
The {@link oaj.xml.annotation.XmlFormat#ATTRS} format can be applied to bean classes to force all bean properties to be serialized as XML attributes instead of child elements.
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: |
The {@link oaj.xml.annotation.XmlFormat#ELEMENT} format can be applied to bean properties to override the {@link oaj.xml.annotation.XmlFormat#ATTRS} format applied on the bean class.
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: |
The {@link oaj.xml.annotation.XmlFormat#ATTRS} format can be applied to a single bean
property of type Map<String,Object>
to denote arbitrary XML attribute values on the
element.
These can be mixed with other {@link oaj.xml.annotation.XmlFormat#ATTR} annotated
properties, but there must not be an overlap in bean property names and map keys.
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
|
The {@link oaj.xml.annotation.XmlFormat#COLLAPSED} format can be applied to bean properties of type array/Collection. This causes the child objects to be serialized directly inside the bean element. This format must be used in conjunction with {@link oaj.xml.annotation.Xml#childName() @Xml(childName)} to differentiate which collection the values came from if you plan on parsing the output back into beans. Note that child names must not conflict with other property names.
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: [ |
The {@link oaj.xml.annotation.XmlFormat#ELEMENTS} format can be applied to a single bean property of either a simple type or array/Collection. It allows free-form child elements to be formed. All other properties on the bean MUST be serialized as attributes.
Data type | JSON example | With annotation |
---|---|---|
|
{
a: |
|
|
{
a: |
The {@link oaj.xml.annotation.XmlFormat#MIXED} format is similar to {@link oaj.xml.annotation.XmlFormat#ELEMENTS} except elements names on primitive types (string/number/boolean/null) are stripped from the output. This format particularly useful when combined with bean dictionaries to produce mixed content. The bean dictionary isn't used during serialization, but it is needed during parsing to resolve bean types.
The {@link oaj.xml.annotation.XmlFormat#MIXED_PWS} format identical to {@link oaj.xml.annotation.XmlFormat#MIXED} except whitespace characters are preserved in the output.
Data type | JSON example | Without annotations | With annotations |
---|---|---|---|
|
{
a: [
|
Whitespace (tabs and newlines) are not added to MIXED child nodes in readable-output mode. This helps ensures strings in the serialized output can be losslessly parsed back into their original forms when they contain whitespace characters. If the {@link javax.xml.stream.XMLInputFactory#IS_REPLACING_ENTITY_REFERENCES} setting was not useless in Java, we could support lossless readable XML for MIXED content. But as of Java 8, it still does not work.
XML suffers from other deficiencies as well that affect MIXED content.
For example,
The examples below show how whitespace is handled under various circumstances:
Data type | XML |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It should be noted that when using
The {@link oaj.xml.annotation.XmlFormat#TEXT} format is similar to
{@link oaj.xml.annotation.XmlFormat#MIXED} except it's meant for solitary objects that
get serialized as simple child text nodes.
Any object that can be serialize to a String
can be used.
The {@link oaj.xml.annotation.XmlFormat#TEXT_PWS} is the same except whitespace is
preserved in the output.
Data type | JSON example | Without annotations | With annotations |
---|---|---|---|
|
{
a: |
The {@link oaj.xml.annotation.XmlFormat#XMLTEXT} format is similar to
{@link oaj.xml.annotation.XmlFormat#TEXT} except it's meant for strings containing XML
that should be serialized as-is to the document.
Any object that can be serialize to a String
can be used.
During parsing, the element content gets parsed with the rest of the document and then re-serialized to
XML before being set as the property value.
This process may not be perfect (e.g. double quotes may be replaced by single quotes, etc...).
Data type | JSON example | With TEXT annotation | With XMLTEXT annotation |
---|---|---|---|
|
{
a: |