EclipseLink/Development/333601

Design Specification: Enhancement: Customizable Name Mangling Algorithm

ER 333601

A mechanism should be provided to allow the customization of how our JAXB implementation converts Java class and field names to xml types, elements and attributes.

Requirements

1. Default behavior must continue to be JAXB spec compliant

Interface

The following interface is being proposed. The methods take in the Java name but could be modified to additionally take in additional information such as the type of the field.

package org.eclipse.persistence.oxm;
 
public interface XMLNameTransformer {
	/**
	 * Method called when creating a simpletype or complextype from a class
	 * @param name - The fully qualified class name
	 */
	public String transformTypeName(String name);
 
	/**
	 * Method called when creating an element from a Java field or method
	 * @param name - unmodified field name or if this was from a getter or setter 
	 * method the "get" or "set" will be automatically removed and the first 
	 * letter will be made lowercase
	 * Example: if the method getFirstName was annotated with @XmlElement the name 
         * passed into this method would be "firstName"
	 */
	public String transformElementName(String name);
 
	/**
         * Method called when creating an attribute from a Java field
	 * @param name - attribute name from the class
	 */
	public String transformAttributeName(String name);
 
	/**
	 * Method called when creating a simpletype or complextype from a class
	 * @param name - The fully qualified class name
	 */
	public String transformRootElementName(String name);	
 
}

Configuration

The following Annotation will be added and initially will only be allowed at the package level

package org.eclipse.persistence.oxm.annotations;
 
@Target({ElementType.PACKAGE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlNameTransformer {
 
    /**
     * (Required) Defines the name of the XML name transformer that should be 
     * applied to names.
     */	
	Class <? extends XMLNameTransformer> value();
}

Alternatively this could be set in the xml bindings file The following attribute will be added to the xml-bindings element in eclipselink_oxm_2_3.xsd

....
            <xs:attribute name="xml-name-transformer" type="xs:string" />
....

Implementation

org.eclipse.persistence.jaxb.DefaultXMLNameTransformer will be added and will provide our default Java to XML name transformations and will provide JAXB compliant conversions.

Examples

Package level annotation (package-info.java)

@XmlNameTransformer(testing.MyLowerTransformer.class)
package org.eclipse.persistence.testing.jaxb.externalizedmetadata.xmlnametransformer;
import javax.xml.bind.annotation.*;
import org.eclipse.persistence.oxm.annotations.XmlNameTransformer;

xml bindings file

  <?xml version='1.0' encoding='UTF-8'?>
    <xml-bindings xmlns='http://www.eclipse.org/eclipselink/xsds/persistence/oxm' 
        xml-name-transformer='testing.MyUpperTransformer'>
    <xml-schema namespace='myuri'/>
    <java-types/>
  </xml-bindings>

Future Consideration

1. Also allow the annotation at the class level
2. Considering allowing the users to specify an instantiated class at runtime instead of just a class name that we instantiate.