Difference between revisions of "EclipseLink/Release/2.4.0/JAXB RI Extensions/Namespace Prefix Mapper"

From Eclipsepedia

Jump to: navigation, search
Line 16: Line 16:
 
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:
 
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:700px">
+
<div style="width:800px">
 
<source lang="java">
 
<source lang="java">
 
marshaller.setProperty(MarshallerProperties.NAMESPACE_PREFIX_MAPPER, new MyPrefixMapper());
 
marshaller.setProperty(MarshallerProperties.NAMESPACE_PREFIX_MAPPER, new MyPrefixMapper());
Line 38: Line 38:
 
* Returns any namespace prefix/uri pairs that should be used in the document, but not declared in the root of the XML document.  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.
 
* Returns any namespace prefix/uri pairs that should be used in the document, but not declared in the root of the XML document.  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", ... }
 
* 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.
  
  

Revision as of 13:19, 5 June 2012

Design Documentation: NamespacePrefixMapper

ER 357266

In the current JAXB RI, developed by Sun, there are a series of "proprietary" JAXB extensions that are available to provide advanced JAXB functionality outside of the JAXB spec (these extension classes 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 implementing the NamespacePrefixMapper interface and setting an instance on the Marshaller, the user can control how prefixes are assigned.

This document will outline the design for an EclipseLink equivalent to this extension.


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:

marshaller.setProperty(MarshallerProperties.NAMESPACE_PREFIX_MAPPER, new MyPrefixMapper());

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

public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) (required)

  • Returns a namespace prefix for the given namespaceUri

public String[] getPreDeclaredNamespaceUris() (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", ... }

public String[] getPreDeclaredNamespaceUris2() (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", ... }

public String[] getContextualNamespaceDecls() (optional)

  • Returns any namespace prefix/uri pairs that should be used in the document, but not declared in the root of the XML document. 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.


Requirements

  • Provide an interface/abstract class the user can implement to provide custom namespaces.
  • Provide the following callback methods:
    • getPreferredPrefix - Whenever creating a prefix for a specific namespace uri, the PrefixMapper should be called to determine what prefix to use.
    • getPreDeclaredNamespaceUris - Returns a list of prefix/namespace uri mappings that should be declared at the top of this xml document.
    • getContextualNamespaceDeclarations - Returns a list of namespace declarations that will exist higher up in the document (in the case of marshalling into a SOAP message or something similar) and don't need to be re-declared.