View source for EclipseLink/Release/2.4.0/JAXB RI Extensions/Namespace Prefix Mapper

<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>

= Namespace Prefix Mapper =

In the current JAXB RI, developed by Sun, there is a series of "proprietary" JAXB extensions which provide advanced functionality outside of the JAXB specification (these extension classes and properties reside in the '''com.sun.xml.bind''' package).

The '''NamespacePrefixMapper''' is one of these extensions - it allows the user to customize the namespaces and namespace prefixes used by a given Marshaller. By subclassing the abstract '''NamespacePrefixMapper''' class and setting an instance on the Marshaller, the user can control how prefixes are assigned. 


= Configuration =

To use this feature, the user must create a subclass of the '''org.eclipse.persistence.oxm.NamespacePrefixMapper''' class, and then provide an instance of this subclass to the JAXB Marshaller:

<div style="width:800px">
<source lang="java">
marshaller.setProperty(MarshallerProperties.NAMESPACE_PREFIX_MAPPER, new MyPrefixMapper());
</source>
</div>


'''NamespacePrefixMapper''' contains the following methods that can be overridden in the subclass:

'''<code>public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix)</code>''' (required)
* Returns a namespace prefix for the given namespaceUri

'''<code>public String[] getPreDeclaredNamespaceUris()</code>''' (optional)
* Returns any namespaces that should be declared in the document, even if they are not used.  Namespaces returned will be assigned a generated prefix (i.e. "ns1", "ns2", etc)
* Returned String[] is in the format { "namespace1", "namespace2", ... }

'''<code>public String[] getPreDeclaredNamespaceUris2()</code>''' (optional)
* Returns any namespace prefix/uri pairs that should be declared in the document, even if they are not used.
* Returned String[] is in the format { "prefix1", "namespace1", "prefix2", "namespace2", ... }

'''<code>public String[] getContextualNamespaceDecls()</code>''' (optional)
* Returns any namespace prefix/uri pairs that should be used in the document, but not actually declared in the root of the XML.  This is useful if the XML being marshalled is part of a larger document, which would have these namespaces declared higher up in the document.
* Returned String[] is in the format { "prefix1", "namespace1", "prefix2", "namespace2", ... }


''Note'': EclipseLink also supports the Sun RI's equivalents: subclasses of '''com.sun.xml.bind.marshaller.NamespacePrefixMapper''' can also be set on a Marshaller, using the '''com.sun.xml.bind.namespacePrefixMapper''' property name.


EclipseLink also supports a simplified way to provide preferred namespace prefixes; instead of a '''NamespacePrefixMapper''' instance, you can pass the Marshaller a '''Map''' of uris/prefixes to use when marshalling:

<div style="width:800px">
<source lang="java">
Map<String, String> urisToPrefixes = new HashMap<String, String>();
urisToPrefixes.put("http://uri1.example.com", "prefix1");
urisToPrefixes.put("http://uri2.example.com", "prefix2");        

marshaller.setProperty(MarshallerProperties.NAMESPACE_PREFIX_MAPPER, urisToPrefixes);
</source>
</div>


= Example 1 =

This example will use the following object model:

<div style="width:800px">
<source lang="java">
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(namespace="http://www.root.com")
public class TestObject {

    @XmlElement(namespace="http://www.acme.com")
    public String name;
    
    @XmlElement(namespace="http://sub.root.com")
    public SubObject subObject;
    
}
</source>
</div>
<div style="width:800px">
<source lang="java">
public class SubObject {

    public String description;
    
}
</source>
</div>

Next, a subclass of '''NamespacePrefixMapper''' is implemented:

<div style="width:800px">
<source lang="java">
import org.eclipse.persistence.oxm.NamespacePrefixMapper;

public class MyPrefixMapper extends NamespacePrefixMapper {
    
    @Override
    public String getPreferredPrefix(String uri, String suggestion, boolean requirePrefix) {
        if (uri.equals("http://www.root.com")) {
            return "rootNS";
        }
        if (uri.equals("http://sub.root.com")) {
            return "subNS";
        }
        return suggestion;
    }

    @Override
    public String[] getContextualNamespaceDecls() {
        return new String[] { "acmeNS", "http://www.acme.com" };
    }

    @Override
    public String[] getPreDeclaredNamespaceUris() {
        return new String[] { "fooNS", "barNS" };
    }

    @Override
    public String[] getPreDeclaredNamespaceUris2() {
        return new String[] { "altNS", "http://alternate.root.com" };
    }

}
</source>
</div>

An instance of this '''NamespacePrefixMapper''' is then passed to the JAXB Marshaller:

<div style="width:800px">
<source lang="java">
JAXBContext ctx = JAXBContext.newInstance(new Class[] { TestObject.class, SubObject.class });
Marshaller m = ctx.createMarshaller();
m.setProperty(MarshallerProperties.NAMESPACE_PREFIX_MAPPER, new MyPrefixMapper());
</source>
</div>

Now, when a TestObject is marshalled, it will contain the following namespace information:

<div style="width:800px">
<source lang="text">
<?xml version="1.0" encoding="UTF-8"?>
<rootNS:testObject 
    xmlns:subNS="http://sub.root.com" 
    xmlns:rootNS="http://www.root.com" 
    xmlns:ns5="fooNS" 
    xmlns:ns6="barNS" 
    xmlns:altNS="http://alternate.root.com">
    <acmeNS:name>FOO</acmeNS:name>
    <subNS:subObject>
        <description>Sub</description>
    </subNS:subObject>
</rootNS:testObject>
</source>
</div>

For comparison, without using a custom '''NamespacePrefixMapper''', the same object would marshal as follows:

<div style="width:800px">
<source lang="text">
<?xml version="1.0" encoding="UTF-8"?>
<ns4:testObject
    xmlns:ns2="http://www.acme.com"
    xmlns:ns3="http://sub.root.com"
    xmlns:ns4="http://www.root.com">
    <ns2:name>FOO</ns2:name>
    <ns3:subObject>
        <description>Sub</description>
    </ns3:subObject>
</ns4:testObject>
</source>
</div>


= Example 2 =

Using the same object model as above, you could instead provide your list of namespaces and preferred prefixes to the Marshaller in a simple Map:

<div style="width:800px">
<source lang="java">
JAXBContext ctx = JAXBContext.newInstance(new Class[] { TestObject.class, SubObject.class });

Map<String, String> urisToPrefixes = new HashMap<String, String>();
urisToPrefixes.put("http://www.root.com", "rootNS");
urisToPrefixes.put("http://sub.root.com", "subNS");        

Marshaller m = ctx.createMarshaller();
m.setProperty(MarshallerProperties.NAMESPACE_PREFIX_MAPPER, prefixesToUris);
</source>
</div>

Using this approach, the marshalled document would look like this:

<div style="width:800px">
<source lang="text">
<?xml version="1.0" encoding="UTF-8"?>
<rootNS:testObject 
   xmlns:ns1="http://www.acme.com" 
   xmlns:subNS="http://sub.root.com" 
   xmlns:rootNS="http://www.root.com">
   <ns1:name>FOO</ns1:name>
   <subNS:subObject>
      <description>Sub</description>
   </subNS:subObject>
</rootNS:testObject>
</source>
</div>

As this is a simplified API, there is no support for the "Contextual" or "PreDeclared" namespace functionality provided by the '''NamespacePrefixMapper''' class.