EclipseLink/DesignDocs/293925/MOXyExtensions/XmlBinaryDataCollectionMapping

XMLBinaryDataCollectionMapping

Requirements

Provide support for XML binary data collection mapping configuration via XML metadata file.

The following should be configurable:

• Path-based mappings
• Positional mappings
• Read only
• Write only
• Get/set method names

Design

Basic XML binary data collection mapping support

We will extend our current xml-element and xml-attribute support to allow binary data collection mapping configuration. For example, the following XML metadata snippet would be used to setup a binary data collection mapping for 'bytes' (where bytes is a List<byte[]> in the object model):

<xml-element java-attribute="bytes" />

The same thing mapped with a grouping element:

<xml-element java-attribute="bytes" xml-path="mybytes/bytes" />

Equivalent annotations

@javax.xml.bind.annotation.XmlElement
@org.eclipse.persistence.oxm.annotations.XmlPath("mybytes/bytes")
public List<byte[]> bytes;

Example:

The following example will demonstrate how to configure XML binary data collection mappings via XML metadata by using xml-element and xml-attribute.

org.example.MyData.java

package org.example;
 
public class MyData {
    public List<byte[]> bytes;
    public List<byte[]> readOnlyBytes;
    public List<byte[]> writeOnlyBytes;
 
    public List<byte[]> getBytes() {
        return bytes;
    }
 
    public void setBytes(List<byte[]> bytes) {
        this.bytes = bytes;
    }
}

Deployment XML

<class-mapping-descriptor xsi:type="xml-class-mapping-descriptor">
  <class>org.example.MyData</class>
  <alias>MyData</alias>
  <attribute-mappings>
    <attribute-mapping xsi:type="xml-binary-data-collection-mapping">
      <attribute-name>bytes</attribute-name>
      <get-method>getBytes</get-method>
      <set-method>setBytes</set-method>
      <field name="@mybytes" xsi:type="node"/>
      <container xsi:type="list-container-policy">
        <collection-type>java.util.Vector</collection-type>
      </container>
      <is-swa-ref>false</is-swa-ref>
      <should-inline-data>false</should-inline-data>
    </attribute-mapping>
  <attribute-mapping xsi:type="xml-binary-data-collection-mapping">
    <attribute-name>readOnlyBytes</attribute-name>
    <read-only>true</read-only>
    <field name="@my-read-only-bytes" xsi:type="node"/>
    <container xsi:type="list-container-policy">
      <collection-type>java.util.Vector</collection-type>
    </container>
    <is-swa-ref>false</is-swa-ref>
    <should-inline-data>false</should-inline-data>
  </attribute-mapping>
  <attribute-mapping xsi:type="xml-binary-data-collection-mapping">
    <attribute-name>writeOnlyBytes</attribute-name>
    <field name="@my-write-only-bytes" xsi:type="node"/>
    <container xsi:type="list-container-policy">
      <collection-type>java.util.Vector</collection-type>
    </container>
    <is-swa-ref>false</is-swa-ref>
    <should-inline-data>false</should-inline-data>
  </attribute-mapping>
  </attribute-mappings>
  <default-root-element>my-data</default-root-element>
  <default-root-element-field name="my-data"/>
</class-mapping-descriptor>

XML Instance Document (read)

<?xml version="1.0" encoding="UTF-8"?>
<my-data>
  <mybytes>
    <bytes>AAECAw==</bytes>
    <bytes>AQIDBA==</bytes>
    <read-only-bytes>
      <byte>AgMEBQ==</byte>
      <byte>AAECAw==</byte>
    </read-only-bytes>
  </mybytes>
  <write-only-bytes>AQIDBA==</write-only-bytes>
  <write-only-bytes>AgMEBQ==</write-only-bytes>
</my-data>

XML Instance Document (write)

<?xml version="1.0" encoding="UTF-8"?>
<my-data>
  <mybytes>
    <bytes>AAECAw==</bytes>
    <bytes>AQIDBA==</bytes>
  </mybytes>
  <write-only-bytes>AQIDBA==</write-only-bytes>
  <write-only-bytes>AgMEBQ==</write-only-bytes>
</my-data>

org/example/eclipselink-oxm.xml

This XML file demonstrates configuring XML binary data collection mappings on the "org.example.MyData" class.

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <java-types>
        <java-type name="org.example.MyData">
            <xml-root-element name="my-data" />
            <java-attributes>
                <xml-element java-attribute="bytes" xml-path="mybytes/bytes">
                    <xml-access-methods get-method="getBytes" set-method="setBytes" />
                </xml-element>
                <xml-element java-attribute="readOnlyBytes" xml-path="mybytes/read-only-bytes/byte" read-only="true" />
                <xml-element java-attribute="writeOnlyBytes" name="write-only-bytes" write-only="true" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

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