org.eclipse.persistence.oxm
Class XMLContext

java.lang.Object
  org.eclipse.persistence.oxm.XMLContext

public class XMLContext
extends java.lang.Object

An XMLContext is created based on EclipseLink sessions or projects and can then used to create instances of XMLMarshaller, XMLUnmarshaller and XMLValidator.

There are constructors to create an XMLContext with a single EclipseLink project or with a String which is a single EclipseLink session name or a ':' separated list of EclipseLink session names.

Code Sample
XMLContext context = new XMLContext("mySessionName");
XMLMarshaller marshaller = context.createMarshaller();
XMLUnmarshaller unmarshaller = context.createUnmarshaller();
XMLValidator validator = context.createValidator();


The XMLContext is thread-safe. If multiple threads accessing the same XMLContext object request an XMLMarshaller, each will receive their own instance of XMLMarshaller, so any state that the XMLMarshaller maintains will be unique to that process. The same is true of instances of XMLUnmarshaller and XMLValidator.

See Also:

XMLMarshaller, XMLUnmarshaller, XMLValidator

Nested Class Summary

static class

XMLContext.XMLContextState

Constructor Summary

XMLContext(java.util.Collection projects)

XMLContext(java.util.Collection projects, java.lang.ClassLoader classLoader)

XMLContext(Project project)
Create a new XMLContext based on the specified project

XMLContext(Project project, java.lang.ClassLoader classLoader)
Create a new XMLContext based on the specified Project and ClassLoader.

XMLContext(Project project, java.lang.ClassLoader classLoader, SessionEventListener sessionEventListener)
Create a new XMLContext based on the specified Project and ClassLoader.

XMLContext(java.lang.String sessionNames)
Create a new XMLContext based on the specified session name or list of session names

XMLContext(java.lang.String sessionNames, java.lang.ClassLoader classLoader)
Create a new XMLContext based on the specified session name or list of session names

XMLContext(java.lang.String sessionNames, java.lang.ClassLoader classLoader, java.lang.String xmlResource)
Create a new XMLContext based on passed in session names, classloader and session meta XML.

XMLContext(java.lang.String sessionNames, java.lang.String xmlResource)
Create a new XMLContext based on passed in session names and session meta XML.

Method Summary

void	addDescriptorByQName(javax.xml.namespace.QName qName, XMLDescriptor descriptor)
void	addSession(DatabaseSession sessionToAdd) INTERNAL: Add and initialize a new session to the list of sessions associated with this XMLContext.
void	applyORMMetadata(org.eclipse.persistence.internal.sessions.AbstractSession ormSession) ADVANCED: Adjust the OXM metadata to take into account ORM mapping metadata,
XMLBinder	createBinder() Create a new XMLBinder
java.lang.Object	createByQualifiedName(java.lang.String namespace, java.lang.String typeName, boolean isGlobalType) Create a new object instance for a given XML namespace and name.
<T> T	createByXPath(java.lang.Object parentObject, java.lang.String xPath, NamespaceResolver namespaceResolver, java.lang.Class<T> returnType) Create a new object instance for a given XPath, relative to the parentObject.
XMLMarshaller	createMarshaller() Create a new XMLMarshaller
XMLUnmarshaller	createUnmarshaller() Create a new XMLUnmarshaller
XMLUnmarshaller	createUnmarshaller(java.util.Map<java.lang.String,java.lang.Boolean> parserFeatures) Create a new XMLUnmarshaller Map parserFeatures = new HashMap(1); parserFeatures.put("http://apache.org/xml/features/validation/schema/normalized-value", false); XMLUnmarshaller unmarshaller = xmlContext.createUnmarshaller(parserFeatures);
XMLValidator	createValidator() Create a new XMLValidator
XMLDescriptor	getDescriptor(javax.xml.namespace.QName qName) INTERNAL: Return the XMLDescriptor with the default root mapping matching the QName parameter.
XMLDescriptor	getDescriptorByGlobalType(org.eclipse.persistence.internal.oxm.XPathFragment xPathFragment) INTERNAL: Return the XMLDescriptor mapped to the global type matching the XPathFragment parameter.
DocumentPreservationPolicy	getDocumentPreservationPolicy(org.eclipse.persistence.internal.sessions.AbstractSession session) INTERNAL: Return the DocumentPreservationPolicy associated with this session
org.eclipse.persistence.internal.sessions.AbstractSession	getReadSession(java.lang.Class clazz) INTERNAL: Return the session corresponding to this class.
org.eclipse.persistence.internal.sessions.AbstractSession	getReadSession(java.lang.Object object) INTERNAL: Return the session corresponding to this object.
org.eclipse.persistence.internal.sessions.AbstractSession	getReadSession(XMLDescriptor xmlDescriptor) INTERNAL: Return the session corresponding to this XMLDescriptor.
org.eclipse.persistence.internal.sessions.AbstractSession	getSession(java.lang.Class clazz) INTERNAL: Return the session corresponding to this class.
DatabaseSession	getSession(int index) INTERNAL: XMLContext xmlContext = new XMLContext("path0:path1"); DatabaseSession session = xmlContext.getSession(0); // returns session for path0
org.eclipse.persistence.internal.sessions.AbstractSession	getSession(java.lang.Object object) INTERNAL: Return the session corresponding to this object.
org.eclipse.persistence.internal.sessions.AbstractSession	getSession(XMLDescriptor xmlDescriptor) INTERNAL: Return the session corresponding to this XMLDescriptor.
java.util.List	getSessions() INTERNAL: Return the EclipseLink session used to marshal.
<T> T	getValueByXPath(java.lang.Object object, java.lang.String xPath, NamespaceResolver namespaceResolver, java.lang.Class<T> returnType) Query the object model based on the corresponding XML document.
XMLContext.XMLContextState	getXMLContextState() INTERNAL: Return the XMLContextState that represents the XMLContexts stateful information.
boolean	hasDocumentPreservation() INTERNAL: Return true if any session held onto by this context has a document preservation policy that requires unmarshalling from a Node.
void	setupDocumentPreservationPolicy(DatabaseSession session)
void	setValueByXPath(java.lang.Object object, java.lang.String xPath, NamespaceResolver namespaceResolver, java.lang.Object value) Set values in the object model based on the corresponding XML document.
void	setXMLContextState(XMLContext.XMLContextState xcs) INTERNAL: Set the stateful information for this XMLContext.
void	storeXMLDescriptorByQName(XMLDescriptor xmlDescriptor) INTERNAL:

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMLContext

public XMLContext(java.lang.String sessionNames)

Create a new XMLContext based on the specified session name or list of session names

Parameters:

sessionNames - A single session name or multiple session names separated by a :

XMLContext

public XMLContext(java.lang.String sessionNames,
                  java.lang.ClassLoader classLoader)

Create a new XMLContext based on the specified session name or list of session names

Parameters:

sessionNames - A single session name or multiple session names separated by a :

classLoader - classloader for loading sessions.xml

XMLContext

public XMLContext(java.lang.String sessionNames,
                  java.lang.String xmlResource)

Create a new XMLContext based on passed in session names and session meta XML.

Parameters:

sessionNames - A single session name or multiple session names separated by a:

xmlResource - path to XML file containing session meta data to initialize and load sessions.

XMLContext

public XMLContext(java.lang.String sessionNames,
                  java.lang.ClassLoader classLoader,
                  java.lang.String xmlResource)

Create a new XMLContext based on passed in session names, classloader and session meta XML.

Parameters:

sessionNames - A single session name or multiple session names separated by a :

classLoader - classloader for loading sessions.xml

xmlResource - path to XML file containing session meta data to initialize and load sessions.

XMLContext

public XMLContext(Project project)

Create a new XMLContext based on the specified project

Parameters:

project - An EclipseLink project

XMLContext

public XMLContext(Project project,
                  java.lang.ClassLoader classLoader)

Create a new XMLContext based on the specified Project and ClassLoader.

Parameters:

project - An EclipseLink project

classLoader - The ClassLoader to be used

XMLContext

public XMLContext(Project project,
                  java.lang.ClassLoader classLoader,
                  SessionEventListener sessionEventListener)

Create a new XMLContext based on the specified Project and ClassLoader.

Parameters:

project - An EclipseLink project

classLoader - The ClassLoader to be used

sessionEventListener - If non-null, this listener will be registered with the SessionEventManager

See Also:

SessionEventListener, SessionEventManager

XMLContext

public XMLContext(java.util.Collection projects)

XMLContext

public XMLContext(java.util.Collection projects,
                  java.lang.ClassLoader classLoader)

Method Detail

getXMLContextState

public XMLContext.XMLContextState getXMLContextState()

INTERNAL: Return the XMLContextState that represents the XMLContexts stateful information. This method is provided for the benefits of layers that build on top of the core OXM layer such as MOXy's JAXB implementation.

setXMLContextState

public void setXMLContextState(XMLContext.XMLContextState xcs)

INTERNAL: Set the stateful information for this XMLContext. Once the new state has been set, OXM operations (marshal, unmarshal, etc) will be based on this new state. This method is provided for the benefit of layers that build on top of the core OXM layer such as MOXy's JAXB

addSession

public void addSession(DatabaseSession sessionToAdd)

INTERNAL: Add and initialize a new session to the list of sessions associated with this XMLContext.

createUnmarshaller

public XMLUnmarshaller createUnmarshaller()

Create a new XMLUnmarshaller

Returns:

An XMLUnmarshaller based on this XMLContext

createUnmarshaller

public XMLUnmarshaller createUnmarshaller(java.util.Map<java.lang.String,java.lang.Boolean> parserFeatures)

Create a new XMLUnmarshaller

 Map parserFeatures = new HashMap(1);
 parserFeatures.put("http://apache.org/xml/features/validation/schema/normalized-value", false);
 XMLUnmarshaller unmarshaller = xmlContext.createUnmarshaller(parserFeatures);
 

Returns:

An XMLUnmarshaller based on this XMLContext, the underlying parser will use the passed in parser features.

createBinder

public XMLBinder createBinder()

Create a new XMLBinder

Returns:

an XMLBinder based on this XMLContext

createMarshaller

public XMLMarshaller createMarshaller()

Create a new XMLMarshaller

Returns:

An XMLMarshaller based on this XMLContext

createValidator

public XMLValidator createValidator()

Create a new XMLValidator

Returns:

An XMLValidator based on this XMLContext

getReadSession

public org.eclipse.persistence.internal.sessions.AbstractSession getReadSession(java.lang.Object object)

INTERNAL: Return the session corresponding to this object. Since the object may be mapped by more that one of the projects used to create the XML Context, this method will return the first match. The session will be a unit of work if document preservation is not enabled. This method will typically be used for unmarshalling when a non-shared cache is desired.

getReadSession

public org.eclipse.persistence.internal.sessions.AbstractSession getReadSession(java.lang.Class clazz)

INTERNAL: Return the session corresponding to this class. Since the class may be mapped by more that one of the projects used to create the XML Context, this method will return the first match. The session will be a unit of work if document preservation is not enabled. This method will typically be used for unmarshalling when a non-shared cache is desired.

getReadSession

public org.eclipse.persistence.internal.sessions.AbstractSession getReadSession(XMLDescriptor xmlDescriptor)

INTERNAL: Return the session corresponding to this XMLDescriptor. Since the class may be mapped by more that one of the projects used to create the XML Context, this method will return the first match. The session will be a unit of work if document preservation is not enabled. This method will typically be used for unmarshalling when a non-shared cache is desired.

getSessions

public java.util.List getSessions()

INTERNAL: Return the EclipseLink session used to marshal.

getSession

public DatabaseSession getSession(int index)

INTERNAL: XMLContext xmlContext = new XMLContext("path0:path1");
DatabaseSession session = xmlContext.getSession(0); // returns session for path0


getSession

public org.eclipse.persistence.internal.sessions.AbstractSession getSession(java.lang.Object object)

INTERNAL: Return the session corresponding to this object. Since the object may be mapped by more that one of the projects used to create the XML Context, this method will return the first match.

getSession

public org.eclipse.persistence.internal.sessions.AbstractSession getSession(java.lang.Class clazz)

INTERNAL: Return the session corresponding to this class. Since the class may be mapped by more that one of the projects used to create the XML Context, this method will return the first match.

getSession

public org.eclipse.persistence.internal.sessions.AbstractSession getSession(XMLDescriptor xmlDescriptor)

INTERNAL: Return the session corresponding to this XMLDescriptor. Since the class may be mapped by more that one of the projects used to create the XML Context, this method will return the first match.

storeXMLDescriptorByQName

public void storeXMLDescriptorByQName(XMLDescriptor xmlDescriptor)

INTERNAL:

getDescriptor

public XMLDescriptor getDescriptor(javax.xml.namespace.QName qName)

INTERNAL: Return the XMLDescriptor with the default root mapping matching the QName parameter.

addDescriptorByQName

public void addDescriptorByQName(javax.xml.namespace.QName qName,
                                 XMLDescriptor descriptor)

getDescriptorByGlobalType

public XMLDescriptor getDescriptorByGlobalType(org.eclipse.persistence.internal.oxm.XPathFragment xPathFragment)

INTERNAL: Return the XMLDescriptor mapped to the global type matching the XPathFragment parameter.

getDocumentPreservationPolicy

public DocumentPreservationPolicy getDocumentPreservationPolicy(org.eclipse.persistence.internal.sessions.AbstractSession session)

INTERNAL: Return the DocumentPreservationPolicy associated with this session

Parameters:

session -

Returns:

setupDocumentPreservationPolicy

public void setupDocumentPreservationPolicy(DatabaseSession session)

hasDocumentPreservation

public boolean hasDocumentPreservation()

INTERNAL: Return true if any session held onto by this context has a document preservation policy that requires unmarshalling from a Node.

applyORMMetadata

public void applyORMMetadata(org.eclipse.persistence.internal.sessions.AbstractSession ormSession)

ADVANCED: Adjust the OXM metadata to take into account ORM mapping metadata,

getValueByXPath

public <T> T getValueByXPath(java.lang.Object object,
                             java.lang.String xPath,
                             NamespaceResolver namespaceResolver,
                             java.lang.Class<T> returnType)

Query the object model based on the corresponding XML document. The following pairings are equivalent:

Return the Customer's ID

 Integer id = xmlContext.getValueByXPath(customer, "@id", null, Integer.class);
 Integer id = customer.getId();

Return the Customer's Name

 String name = xmlContext.getValueByXPath(customer, "ns:personal-info/ns:name/text()", null, String.class);
 String name = customer.getName();

Return the Customer's Address

 Address address = xmlContext.getValueByXPath(customer, "ns:contact-info/ns:address", aNamespaceResolver, Address.class);
 Address address = customer.getAddress();

Return all the Customer's PhoneNumbers

 List phoneNumbers = xmlContext.getValueByXPath(customer, "ns:contact-info/ns:phone-number", aNamespaceResolver, List.class);
 List phoneNumbers = customer.getPhoneNumbers();

Return the Customer's second PhoneNumber

 PhoneNumber phoneNumber = xmlContext.getValueByXPath(customer, "ns:contact-info/ns:phone-number[2]", aNamespaceResolver, PhoneNumber.class);
 PhoneNumber phoneNumber = customer.getPhoneNumbers().get(1);

Return the base object

 Customer customer = xmlContext.getValueByXPath(customer, ".", aNamespaceResolver, Customer.class);
 Customer customer = customer;
 

Type Parameters:

T - The return type of this method corresponds to the returnType parameter.

Parameters:

object - The XPath will be executed relative to this object.

xPath - The XPath statement

namespaceResolver - A NamespaceResolver containing the prefix/URI pairings from the XPath statement.

returnType - The return type.

Returns:

The object corresponding to the XPath or null if no result was found.

setValueByXPath

public void setValueByXPath(java.lang.Object object,
                            java.lang.String xPath,
                            NamespaceResolver namespaceResolver,
                            java.lang.Object value)

Set values in the object model based on the corresponding XML document. The following pairings are equivalent:

Set the Customer's ID

 xmlContext.setValueByXPath(customer, "@id", null, new Integer(123));
 customer.setId(new Integer(123));

Set the Customer's Name

 xmlContext.setValueByXPath(customer, "ns:personal-info/ns:name/text()", aNamespaceResolver, "Jane Doe");
 customer.setName("Jane Doe");

Set the Customer's Address

 xmlContext.setValueByXPath(customer, "ns:contact-info/ns:address", aNamespaceResolver, anAddress);
 customer.setAddress(anAddress);

Set the Customer's PhoneNumbers

 xmlContext.setValueByXPath(customer, "ns:contact-info/ns:phone-number", aNamespaceResolver, phoneNumbers);
 customer.setPhoneNumbers(phoneNumbers);

Set the Customer's second PhoneNumber

 xmlContext.setValueByXPath(customer, "ns:contact-info/ns:phone-number[2]", aNamespaceResolver, aPhoneNumber);
 customer.getPhoneNumbers().get(1);

Parameters:

object - The XPath will be executed relative to this object.

xPath - The XPath statement

namespaceResolver - A NamespaceResolver containing the prefix/URI pairings from the XPath statement.

value - The value to be set.

createByQualifiedName

public java.lang.Object createByQualifiedName(java.lang.String namespace,
                                              java.lang.String typeName,
                                              boolean isGlobalType)
                                       throws java.lang.IllegalArgumentException

Create a new object instance for a given XML namespace and name.

Parameters:

namespace - The namespace of the complex type to create a new Java instance of.

typeName - The XML type name to create a new Java instance of.

isGlobalType - True if the object to be created represents a global type, false if it represents a global element.

Returns:

An instance of the Java class mapped to the indicated XML type, or null if no result was found.

Throws:

java.lang.IllegalArgumentException

createByXPath

public <T> T createByXPath(java.lang.Object parentObject,
                           java.lang.String xPath,
                           NamespaceResolver namespaceResolver,
                           java.lang.Class<T> returnType)

Create a new object instance for a given XPath, relative to the parentObject.

Type Parameters:

T - The return type of this method corresponds to the returnType parameter.

Parameters:

parentObject - The XPath will be executed relative to this object.

xPath - The XPath statement.

namespaceResolver - A NamespaceResolver containing the prefix/URI pairings from the XPath statement.

returnType - The return type.

Returns:

An instance of the Java class mapped to the supplied XML type, or null if no result was found.