< prev index next >
src/java.xml.bind/share/classes/javax/xml/bind/Unmarshaller.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 236,252 ****
* Additionally, when the root element of XML data has an <tt>xsi:type</tt> attribute and
* that attribute's value references a type definition that is mapped
* to a JAXB mapped class by {@link JAXBContext}, that the root
* element's <tt>xsi:type</tt> attribute takes
* precedence over the unmarshal methods <tt>declaredType</tt> parameter.
! * These methods always return a <tt>JAXBElement<declaredType></tt>
* instance. The table below shows how the properties of the returned JAXBElement
* instance are set.
*
* <a name="unmarshalDeclaredTypeReturn"></a>
! * <p>
! * <table border="2" rules="all" cellpadding="4">
* <thead>
* <tr>
* <th align="center" colspan="2">
* Unmarshal By Declared Type returned JAXBElement
* </tr>
--- 236,251 ----
* Additionally, when the root element of XML data has an <tt>xsi:type</tt> attribute and
* that attribute's value references a type definition that is mapped
* to a JAXB mapped class by {@link JAXBContext}, that the root
* element's <tt>xsi:type</tt> attribute takes
* precedence over the unmarshal methods <tt>declaredType</tt> parameter.
! * These methods always return a <tt>JAXBElement<declaredType></tt>
* instance. The table below shows how the properties of the returned JAXBElement
* instance are set.
*
* <a name="unmarshalDeclaredTypeReturn"></a>
! * <table summary="" border="2" rules="all" cellpadding="4">
* <thead>
* <tr>
* <th align="center" colspan="2">
* Unmarshal By Declared Type returned JAXBElement
* </tr>
*** 282,304 ****
* <p>
* Unmarshal by declaredType from a <tt>org.w3c.dom.Node</tt>:
* <blockquote>
* <pre>
* Schema fragment for example
! * <xs:schema>
! * <xs:complexType name="FooType">...<\xs:complexType>
! * <!-- global element declaration "PurchaseOrder" -->
! * <xs:element name="PurchaseOrder">
! * <xs:complexType>
! * <xs:sequence>
! * <!-- local element declaration "foo" -->
! * <xs:element name="foo" type="FooType"/>
* ...
! * </xs:sequence>
! * </xs:complexType>
! * </xs:element>
! * </xs:schema>
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
* Unmarshaller u = jc.createUnmarshaller();
*
* DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
--- 281,303 ----
* <p>
* Unmarshal by declaredType from a <tt>org.w3c.dom.Node</tt>:
* <blockquote>
* <pre>
* Schema fragment for example
! * <xs:schema>
! * <xs:complexType name="FooType">...<\xs:complexType>
! * <!-- global element declaration "PurchaseOrder" -->
! * <xs:element name="PurchaseOrder">
! * <xs:complexType>
! * <xs:sequence>
! * <!-- local element declaration "foo" -->
! * <xs:element name="foo" type="FooType"/>
* ...
! * </xs:sequence>
! * </xs:complexType>
! * </xs:element>
! * </xs:schema>
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
* Unmarshaller u = jc.createUnmarshaller();
*
* DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
*** 307,317 ****
* Document doc = db.parse(new File( "nosferatu.xml"));
* Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
* // local element declaration in schema.
*
* // FooType is the JAXB mapping of the type of local element declaration foo.
! * JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);
* </pre>
* </blockquote>
*
* <p>
* <b>Support for SAX2.0 Compliant Parsers</b><br>
--- 306,316 ----
* Document doc = db.parse(new File( "nosferatu.xml"));
* Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
* // local element declaration in schema.
*
* // FooType is the JAXB mapping of the type of local element declaration foo.
! * JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);
* </pre>
* </blockquote>
*
* <p>
* <b>Support for SAX2.0 Compliant Parsers</b><br>
*** 388,398 ****
* access to non-public methods and/or fields of the class.
* <p>
* The external listener callback mechanism enables the registration of a {@link Listener}
* instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events,
* allowing for more centralized processing than per class defined callback methods. The external listener
! * receives events when unmarshalling proces is marshalling to a JAXB element or to JAXB mapped class.
* <p>
* The 'class defined' and external listener event callback methods are independent of each other,
* both can be called for one event. The invocation ordering when both listener callback methods exist is
* defined in {@link Listener#beforeUnmarshal(Object, Object)} and {@link Listener#afterUnmarshal(Object, Object)}.
* <p>
--- 387,397 ----
* access to non-public methods and/or fields of the class.
* <p>
* The external listener callback mechanism enables the registration of a {@link Listener}
* instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events,
* allowing for more centralized processing than per class defined callback methods. The external listener
! * receives events when unmarshalling process is marshalling to a JAXB element or to JAXB mapped class.
* <p>
* The 'class defined' and external listener event callback methods are independent of each other,
* both can be called for one event. The invocation ordering when both listener callback methods exist is
* defined in {@link Listener#beforeUnmarshal(Object, Object)} and {@link Listener#afterUnmarshal(Object, Object)}.
* <p>
*** 1008,1018 ****
/**
* Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
*
* <p>
* Every unmarshaller internally maintains a
! * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
* which it uses for unmarshalling classes whose fields/methods are annotated
* with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
*
* <p>
* This method allows applications to use a configured instance of {@link XmlAdapter}.
--- 1007,1017 ----
/**
* Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
*
* <p>
* Every unmarshaller internally maintains a
! * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
* which it uses for unmarshalling classes whose fields/methods are annotated
* with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
*
* <p>
* This method allows applications to use a configured instance of {@link XmlAdapter}.
*** 1048,1058 ****
public <A extends XmlAdapter> A getAdapter( Class<A> type );
/**
* <p>Associate a context that resolves cid's, content-id URIs, to
* binary data passed as attachments.</p>
- * <p/>
* <p>Unmarshal time validation, enabled via {@link #setSchema(Schema)},
* must be supported even when unmarshaller is performing XOP processing.
* </p>
*
* @throws IllegalStateException if attempt to concurrently call this
--- 1047,1056 ----
*** 1061,1096 ****
void setAttachmentUnmarshaller(AttachmentUnmarshaller au);
AttachmentUnmarshaller getAttachmentUnmarshaller();
/**
! * <p/>
* Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen
* for unmarshal events.
! * <p/>
! * <p/>
* This class enables pre and post processing of an instance of a JAXB mapped class
* as XML data is unmarshalled into it. The event callbacks are called when unmarshalling
* XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition.
* The event callbacks are not called when unmarshalling to an instance of a
* Java datatype that represents a simple type definition.
! * <p/>
! * <p/>
* External listener is one of two different mechanisms for defining unmarshal event callbacks.
* See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview.
! * <p/>
* (@link #setListener(Listener)}
* (@link #getListener()}
*
* @since 1.6, JAXB 2.0
*/
public static abstract class Listener {
/**
! * <p/>
* Callback method invoked before unmarshalling into <tt>target</tt>.
! * <p/>
! * <p/>
* This method is invoked immediately after <tt>target</tt> was created and
* before the unmarshalling of this object begins. Note that
* if the class of <tt>target</tt> defines its own <tt>beforeUnmarshal</tt> method,
* the class specific callback method is invoked before this method is invoked.
*
--- 1059,1094 ----
void setAttachmentUnmarshaller(AttachmentUnmarshaller au);
AttachmentUnmarshaller getAttachmentUnmarshaller();
/**
! * <p>
* Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen
* for unmarshal events.
! * </p>
! * <p>
* This class enables pre and post processing of an instance of a JAXB mapped class
* as XML data is unmarshalled into it. The event callbacks are called when unmarshalling
* XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition.
* The event callbacks are not called when unmarshalling to an instance of a
* Java datatype that represents a simple type definition.
! * </p>
! * <p>
* External listener is one of two different mechanisms for defining unmarshal event callbacks.
* See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview.
! * </p>
* (@link #setListener(Listener)}
* (@link #getListener()}
*
* @since 1.6, JAXB 2.0
*/
public static abstract class Listener {
/**
! * <p>
* Callback method invoked before unmarshalling into <tt>target</tt>.
! * </p>
! * <p>
* This method is invoked immediately after <tt>target</tt> was created and
* before the unmarshalling of this object begins. Note that
* if the class of <tt>target</tt> defines its own <tt>beforeUnmarshal</tt> method,
* the class specific callback method is invoked before this method is invoked.
*
*** 1100,1113 ****
*/
public void beforeUnmarshal(Object target, Object parent) {
}
/**
! * <p/>
* Callback method invoked after unmarshalling XML data into <tt>target</tt>.
! * <p/>
! * <p/>
* This method is invoked after all the properties (except IDREF) are unmarshalled into <tt>target</tt>,
* but before <tt>target</tt> is set into its <tt>parent</tt> object.
* Note that if the class of <tt>target</tt> defines its own <tt>afterUnmarshal</tt> method,
* the class specific callback method is invoked before this method is invoked.
*
--- 1098,1111 ----
*/
public void beforeUnmarshal(Object target, Object parent) {
}
/**
! * <p>
* Callback method invoked after unmarshalling XML data into <tt>target</tt>.
! * </p>
! * <p>
* This method is invoked after all the properties (except IDREF) are unmarshalled into <tt>target</tt>,
* but before <tt>target</tt> is set into its <tt>parent</tt> object.
* Note that if the class of <tt>target</tt> defines its own <tt>afterUnmarshal</tt> method,
* the class specific callback method is invoked before this method is invoked.
*
< prev index next >