1 /*
2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
221 * declaredType methods described in the next subsection.
222 * </blockquote>
223 *
224 * <p>
225 * <a name="unmarshalByDeclaredType"></a>
226 * <b>Unmarshal by Declared Type</b><br>
227 * <blockquote>
228 * The unmarshal methods with a <code>declaredType</code> parameter enable an
229 * application to deserialize a root element of XML data, even when
230 * there is no mapping in {@link JAXBContext} of the root element's XML name.
231 * The unmarshaller unmarshals the root element using the application provided
232 * mapping specified as the <tt>declaredType</tt> parameter.
233 * Note that even when the root element's element name is mapped by {@link JAXBContext},
234 * the <code>declaredType</code> parameter overrides that mapping for
235 * deserializing the root element when using these unmarshal methods.
236 * Additionally, when the root element of XML data has an <tt>xsi:type</tt> attribute and
237 * that attribute's value references a type definition that is mapped
238 * to a JAXB mapped class by {@link JAXBContext}, that the root
239 * element's <tt>xsi:type</tt> attribute takes
240 * precedence over the unmarshal methods <tt>declaredType</tt> parameter.
241 * These methods always return a <tt>JAXBElement<declaredType></tt>
242 * instance. The table below shows how the properties of the returned JAXBElement
243 * instance are set.
244 *
245 * <a name="unmarshalDeclaredTypeReturn"></a>
246 * <p>
247 * <table border="2" rules="all" cellpadding="4">
248 * <thead>
249 * <tr>
250 * <th align="center" colspan="2">
251 * Unmarshal By Declared Type returned JAXBElement
252 * </tr>
253 * <tr>
254 * <th>JAXBElement Property</th>
255 * <th>Value</th>
256 * </tr>
257 * <tr>
258 * <td>name</td>
259 * <td><code>xml element name</code></td>
260 * </tr>
261 * </thead>
262 * <tbody>
263 * <tr>
264 * <td>value</td>
265 * <td><code>instanceof declaredType</code></td>
266 * </tr>
267 * <tr>
268 * <td>declaredType</td>
269 * <td>unmarshal method <code>declaredType</code> parameter</td>
270 * </tr>
271 * <tr>
272 * <td>scope</td>
273 * <td><code>null</code> <i>(actual scope is unknown)</i></td>
274 * </tr>
275 * </tbody>
276 * </table>
277 * </blockquote>
278 *
279 * <p>
280 * The following is an example of
281 * <a href="#unmarshalByDeclaredType">unmarshal by declaredType method</a>.
282 * <p>
283 * Unmarshal by declaredType from a <tt>org.w3c.dom.Node</tt>:
284 * <blockquote>
285 * <pre>
286 * Schema fragment for example
287 * <xs:schema>
288 * <xs:complexType name="FooType">...<\xs:complexType>
289 * <!-- global element declaration "PurchaseOrder" -->
290 * <xs:element name="PurchaseOrder">
291 * <xs:complexType>
292 * <xs:sequence>
293 * <!-- local element declaration "foo" -->
294 * <xs:element name="foo" type="FooType"/>
295 * ...
296 * </xs:sequence>
297 * </xs:complexType>
298 * </xs:element>
299 * </xs:schema>
300 *
301 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
302 * Unmarshaller u = jc.createUnmarshaller();
303 *
304 * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
305 * dbf.setNamespaceAware(true);
306 * DocumentBuilder db = dbf.newDocumentBuilder();
307 * Document doc = db.parse(new File( "nosferatu.xml"));
308 * Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
309 * // local element declaration in schema.
310 *
311 * // FooType is the JAXB mapping of the type of local element declaration foo.
312 * JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);
313 * </pre>
314 * </blockquote>
315 *
316 * <p>
317 * <b>Support for SAX2.0 Compliant Parsers</b><br>
318 * <blockquote>
319 * A client application has the ability to select the SAX2.0 compliant parser
320 * of their choice. If a SAX parser is not selected, then the JAXB Provider's
321 * default parser will be used. Even though the JAXB Provider's default parser
322 * is not required to be SAX2.0 compliant, all providers are required to allow
323 * a client application to specify their own SAX2.0 parser. Some providers may
324 * require the client application to specify the SAX2.0 parser at schema compile
325 * time. See {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)}
326 * for more detail.
327 * </blockquote>
328 *
329 * <p>
330 * <b>Validation and Well-Formedness</b><br>
331 * <blockquote>
332 * <p>
373 * <p>
374 * 'Class defined' event callback methods allow any JAXB mapped class to specify
375 * its own specific callback methods by defining methods with the following method signature:
376 * <blockquote>
377 * <pre>
378 * // This method is called immediately after the object is created and before the unmarshalling of this
379 * // object begins. The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling.
380 * void beforeUnmarshal(Unmarshaller, Object parent);
381 *
382 * //This method is called after all the properties (except IDREF) are unmarshalled for this object,
383 * //but before this object is set to the parent object.
384 * void afterUnmarshal(Unmarshaller, Object parent);
385 * </pre>
386 * </blockquote>
387 * The class defined callback methods should be used when the callback method requires
388 * access to non-public methods and/or fields of the class.
389 * <p>
390 * The external listener callback mechanism enables the registration of a {@link Listener}
391 * instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events,
392 * allowing for more centralized processing than per class defined callback methods. The external listener
393 * receives events when unmarshalling proces is marshalling to a JAXB element or to JAXB mapped class.
394 * <p>
395 * The 'class defined' and external listener event callback methods are independent of each other,
396 * both can be called for one event. The invocation ordering when both listener callback methods exist is
397 * defined in {@link Listener#beforeUnmarshal(Object, Object)} and {@link Listener#afterUnmarshal(Object, Object)}.
398 * <p>
399 * An event callback method throwing an exception terminates the current unmarshal process.
400 *
401 * </blockquote>
402 *
403 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
404 * @see JAXBContext
405 * @see Marshaller
406 * @see Validator
407 * @since 1.6, JAXB 1.0
408 */
409 public interface Unmarshaller {
410
411 /**
412 * Unmarshal XML data from the specified file and return the resulting
413 * content tree.
993 /**
994 * Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
995 *
996 * <p>
997 * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
998 *
999 * @see #setAdapter(Class,XmlAdapter)
1000 * @throws IllegalArgumentException
1001 * if the adapter parameter is null.
1002 * @throws UnsupportedOperationException
1003 * if invoked agains a JAXB 1.0 implementation.
1004 * @since 1.6, JAXB 2.0
1005 */
1006 public void setAdapter( XmlAdapter adapter );
1007
1008 /**
1009 * Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
1010 *
1011 * <p>
1012 * Every unmarshaller internally maintains a
1013 * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
1014 * which it uses for unmarshalling classes whose fields/methods are annotated
1015 * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
1016 *
1017 * <p>
1018 * This method allows applications to use a configured instance of {@link XmlAdapter}.
1019 * When an instance of an adapter is not given, an unmarshaller will create
1020 * one by invoking its default constructor.
1021 *
1022 * @param type
1023 * The type of the adapter. The specified instance will be used when
1024 * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
1025 * refers to this type.
1026 * @param adapter
1027 * The instance of the adapter to be used. If null, it will un-register
1028 * the current adapter set for this type.
1029 * @throws IllegalArgumentException
1030 * if the type parameter is null.
1031 * @throws UnsupportedOperationException
1032 * if invoked agains a JAXB 1.0 implementation.
1033 * @since 1.6, JAXB 2.0
1034 */
1035 public <A extends XmlAdapter> void setAdapter( Class<A> type, A adapter );
1036
1037 /**
1038 * Gets the adapter associated with the specified type.
1039 *
1040 * This is the reverse operation of the {@link #setAdapter} method.
1041 *
1042 * @throws IllegalArgumentException
1043 * if the type parameter is null.
1044 * @throws UnsupportedOperationException
1045 * if invoked agains a JAXB 1.0 implementation.
1046 * @since 1.6, JAXB 2.0
1047 */
1048 public <A extends XmlAdapter> A getAdapter( Class<A> type );
1049
1050 /**
1051 * <p>Associate a context that resolves cid's, content-id URIs, to
1052 * binary data passed as attachments.</p>
1053 * <p/>
1054 * <p>Unmarshal time validation, enabled via {@link #setSchema(Schema)},
1055 * must be supported even when unmarshaller is performing XOP processing.
1056 * </p>
1057 *
1058 * @throws IllegalStateException if attempt to concurrently call this
1059 * method during a unmarshal operation.
1060 */
1061 void setAttachmentUnmarshaller(AttachmentUnmarshaller au);
1062
1063 AttachmentUnmarshaller getAttachmentUnmarshaller();
1064
1065 /**
1066 * <p/>
1067 * Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen
1068 * for unmarshal events.
1069 * <p/>
1070 * <p/>
1071 * This class enables pre and post processing of an instance of a JAXB mapped class
1072 * as XML data is unmarshalled into it. The event callbacks are called when unmarshalling
1073 * XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition.
1074 * The event callbacks are not called when unmarshalling to an instance of a
1075 * Java datatype that represents a simple type definition.
1076 * <p/>
1077 * <p/>
1078 * External listener is one of two different mechanisms for defining unmarshal event callbacks.
1079 * See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview.
1080 * <p/>
1081 * (@link #setListener(Listener)}
1082 * (@link #getListener()}
1083 *
1084 * @since 1.6, JAXB 2.0
1085 */
1086 public static abstract class Listener {
1087 /**
1088 * <p/>
1089 * Callback method invoked before unmarshalling into <tt>target</tt>.
1090 * <p/>
1091 * <p/>
1092 * This method is invoked immediately after <tt>target</tt> was created and
1093 * before the unmarshalling of this object begins. Note that
1094 * if the class of <tt>target</tt> defines its own <tt>beforeUnmarshal</tt> method,
1095 * the class specific callback method is invoked before this method is invoked.
1096 *
1097 * @param target non-null instance of JAXB mapped class prior to unmarshalling into it.
1098 * @param parent instance of JAXB mapped class that will eventually reference <tt>target</tt>.
1099 * <tt>null</tt> when <tt>target</tt> is root element.
1100 */
1101 public void beforeUnmarshal(Object target, Object parent) {
1102 }
1103
1104 /**
1105 * <p/>
1106 * Callback method invoked after unmarshalling XML data into <tt>target</tt>.
1107 * <p/>
1108 * <p/>
1109 * This method is invoked after all the properties (except IDREF) are unmarshalled into <tt>target</tt>,
1110 * but before <tt>target</tt> is set into its <tt>parent</tt> object.
1111 * Note that if the class of <tt>target</tt> defines its own <tt>afterUnmarshal</tt> method,
1112 * the class specific callback method is invoked before this method is invoked.
1113 *
1114 * @param target non-null instance of JAXB mapped class prior to unmarshalling into it.
1115 * @param parent instance of JAXB mapped class that will reference <tt>target</tt>.
1116 * <tt>null</tt> when <tt>target</tt> is root element.
1117 */
1118 public void afterUnmarshal(Object target, Object parent) {
1119 }
1120 }
1121
1122 /**
1123 * <p>
1124 * Register unmarshal event callback {@link Listener} with this {@link Unmarshaller}.
1125 *
1126 * <p>
1127 * There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener.
1128 * One can unregister current Listener by setting listener to <tt>null</tt>.
|
1 /*
2 * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
221 * declaredType methods described in the next subsection.
222 * </blockquote>
223 *
224 * <p>
225 * <a name="unmarshalByDeclaredType"></a>
226 * <b>Unmarshal by Declared Type</b><br>
227 * <blockquote>
228 * The unmarshal methods with a <code>declaredType</code> parameter enable an
229 * application to deserialize a root element of XML data, even when
230 * there is no mapping in {@link JAXBContext} of the root element's XML name.
231 * The unmarshaller unmarshals the root element using the application provided
232 * mapping specified as the <tt>declaredType</tt> parameter.
233 * Note that even when the root element's element name is mapped by {@link JAXBContext},
234 * the <code>declaredType</code> parameter overrides that mapping for
235 * deserializing the root element when using these unmarshal methods.
236 * Additionally, when the root element of XML data has an <tt>xsi:type</tt> attribute and
237 * that attribute's value references a type definition that is mapped
238 * to a JAXB mapped class by {@link JAXBContext}, that the root
239 * element's <tt>xsi:type</tt> attribute takes
240 * precedence over the unmarshal methods <tt>declaredType</tt> parameter.
241 * These methods always return a <tt>JAXBElement<declaredType></tt>
242 * instance. The table below shows how the properties of the returned JAXBElement
243 * instance are set.
244 *
245 * <a name="unmarshalDeclaredTypeReturn"></a>
246 * <table summary="" border="2" rules="all" cellpadding="4">
247 * <thead>
248 * <tr>
249 * <th align="center" colspan="2">
250 * Unmarshal By Declared Type returned JAXBElement
251 * </tr>
252 * <tr>
253 * <th>JAXBElement Property</th>
254 * <th>Value</th>
255 * </tr>
256 * <tr>
257 * <td>name</td>
258 * <td><code>xml element name</code></td>
259 * </tr>
260 * </thead>
261 * <tbody>
262 * <tr>
263 * <td>value</td>
264 * <td><code>instanceof declaredType</code></td>
265 * </tr>
266 * <tr>
267 * <td>declaredType</td>
268 * <td>unmarshal method <code>declaredType</code> parameter</td>
269 * </tr>
270 * <tr>
271 * <td>scope</td>
272 * <td><code>null</code> <i>(actual scope is unknown)</i></td>
273 * </tr>
274 * </tbody>
275 * </table>
276 * </blockquote>
277 *
278 * <p>
279 * The following is an example of
280 * <a href="#unmarshalByDeclaredType">unmarshal by declaredType method</a>.
281 * <p>
282 * Unmarshal by declaredType from a <tt>org.w3c.dom.Node</tt>:
283 * <blockquote>
284 * <pre>
285 * Schema fragment for example
286 * <xs:schema>
287 * <xs:complexType name="FooType">...<\xs:complexType>
288 * <!-- global element declaration "PurchaseOrder" -->
289 * <xs:element name="PurchaseOrder">
290 * <xs:complexType>
291 * <xs:sequence>
292 * <!-- local element declaration "foo" -->
293 * <xs:element name="foo" type="FooType"/>
294 * ...
295 * </xs:sequence>
296 * </xs:complexType>
297 * </xs:element>
298 * </xs:schema>
299 *
300 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
301 * Unmarshaller u = jc.createUnmarshaller();
302 *
303 * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
304 * dbf.setNamespaceAware(true);
305 * DocumentBuilder db = dbf.newDocumentBuilder();
306 * Document doc = db.parse(new File( "nosferatu.xml"));
307 * Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
308 * // local element declaration in schema.
309 *
310 * // FooType is the JAXB mapping of the type of local element declaration foo.
311 * JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);
312 * </pre>
313 * </blockquote>
314 *
315 * <p>
316 * <b>Support for SAX2.0 Compliant Parsers</b><br>
317 * <blockquote>
318 * A client application has the ability to select the SAX2.0 compliant parser
319 * of their choice. If a SAX parser is not selected, then the JAXB Provider's
320 * default parser will be used. Even though the JAXB Provider's default parser
321 * is not required to be SAX2.0 compliant, all providers are required to allow
322 * a client application to specify their own SAX2.0 parser. Some providers may
323 * require the client application to specify the SAX2.0 parser at schema compile
324 * time. See {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)}
325 * for more detail.
326 * </blockquote>
327 *
328 * <p>
329 * <b>Validation and Well-Formedness</b><br>
330 * <blockquote>
331 * <p>
372 * <p>
373 * 'Class defined' event callback methods allow any JAXB mapped class to specify
374 * its own specific callback methods by defining methods with the following method signature:
375 * <blockquote>
376 * <pre>
377 * // This method is called immediately after the object is created and before the unmarshalling of this
378 * // object begins. The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling.
379 * void beforeUnmarshal(Unmarshaller, Object parent);
380 *
381 * //This method is called after all the properties (except IDREF) are unmarshalled for this object,
382 * //but before this object is set to the parent object.
383 * void afterUnmarshal(Unmarshaller, Object parent);
384 * </pre>
385 * </blockquote>
386 * The class defined callback methods should be used when the callback method requires
387 * access to non-public methods and/or fields of the class.
388 * <p>
389 * The external listener callback mechanism enables the registration of a {@link Listener}
390 * instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events,
391 * allowing for more centralized processing than per class defined callback methods. The external listener
392 * receives events when unmarshalling process is marshalling to a JAXB element or to JAXB mapped class.
393 * <p>
394 * The 'class defined' and external listener event callback methods are independent of each other,
395 * both can be called for one event. The invocation ordering when both listener callback methods exist is
396 * defined in {@link Listener#beforeUnmarshal(Object, Object)} and {@link Listener#afterUnmarshal(Object, Object)}.
397 * <p>
398 * An event callback method throwing an exception terminates the current unmarshal process.
399 *
400 * </blockquote>
401 *
402 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
403 * @see JAXBContext
404 * @see Marshaller
405 * @see Validator
406 * @since 1.6, JAXB 1.0
407 */
408 public interface Unmarshaller {
409
410 /**
411 * Unmarshal XML data from the specified file and return the resulting
412 * content tree.
992 /**
993 * Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
994 *
995 * <p>
996 * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
997 *
998 * @see #setAdapter(Class,XmlAdapter)
999 * @throws IllegalArgumentException
1000 * if the adapter parameter is null.
1001 * @throws UnsupportedOperationException
1002 * if invoked agains a JAXB 1.0 implementation.
1003 * @since 1.6, JAXB 2.0
1004 */
1005 public void setAdapter( XmlAdapter adapter );
1006
1007 /**
1008 * Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
1009 *
1010 * <p>
1011 * Every unmarshaller internally maintains a
1012 * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
1013 * which it uses for unmarshalling classes whose fields/methods are annotated
1014 * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
1015 *
1016 * <p>
1017 * This method allows applications to use a configured instance of {@link XmlAdapter}.
1018 * When an instance of an adapter is not given, an unmarshaller will create
1019 * one by invoking its default constructor.
1020 *
1021 * @param type
1022 * The type of the adapter. The specified instance will be used when
1023 * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
1024 * refers to this type.
1025 * @param adapter
1026 * The instance of the adapter to be used. If null, it will un-register
1027 * the current adapter set for this type.
1028 * @throws IllegalArgumentException
1029 * if the type parameter is null.
1030 * @throws UnsupportedOperationException
1031 * if invoked agains a JAXB 1.0 implementation.
1032 * @since 1.6, JAXB 2.0
1033 */
1034 public <A extends XmlAdapter> void setAdapter( Class<A> type, A adapter );
1035
1036 /**
1037 * Gets the adapter associated with the specified type.
1038 *
1039 * This is the reverse operation of the {@link #setAdapter} method.
1040 *
1041 * @throws IllegalArgumentException
1042 * if the type parameter is null.
1043 * @throws UnsupportedOperationException
1044 * if invoked agains a JAXB 1.0 implementation.
1045 * @since 1.6, JAXB 2.0
1046 */
1047 public <A extends XmlAdapter> A getAdapter( Class<A> type );
1048
1049 /**
1050 * <p>Associate a context that resolves cid's, content-id URIs, to
1051 * binary data passed as attachments.</p>
1052 * <p>Unmarshal time validation, enabled via {@link #setSchema(Schema)},
1053 * must be supported even when unmarshaller is performing XOP processing.
1054 * </p>
1055 *
1056 * @throws IllegalStateException if attempt to concurrently call this
1057 * method during a unmarshal operation.
1058 */
1059 void setAttachmentUnmarshaller(AttachmentUnmarshaller au);
1060
1061 AttachmentUnmarshaller getAttachmentUnmarshaller();
1062
1063 /**
1064 * <p>
1065 * Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen
1066 * for unmarshal events.
1067 * </p>
1068 * <p>
1069 * This class enables pre and post processing of an instance of a JAXB mapped class
1070 * as XML data is unmarshalled into it. The event callbacks are called when unmarshalling
1071 * XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition.
1072 * The event callbacks are not called when unmarshalling to an instance of a
1073 * Java datatype that represents a simple type definition.
1074 * </p>
1075 * <p>
1076 * External listener is one of two different mechanisms for defining unmarshal event callbacks.
1077 * See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview.
1078 * </p>
1079 * (@link #setListener(Listener)}
1080 * (@link #getListener()}
1081 *
1082 * @since 1.6, JAXB 2.0
1083 */
1084 public static abstract class Listener {
1085 /**
1086 * <p>
1087 * Callback method invoked before unmarshalling into <tt>target</tt>.
1088 * </p>
1089 * <p>
1090 * This method is invoked immediately after <tt>target</tt> was created and
1091 * before the unmarshalling of this object begins. Note that
1092 * if the class of <tt>target</tt> defines its own <tt>beforeUnmarshal</tt> method,
1093 * the class specific callback method is invoked before this method is invoked.
1094 *
1095 * @param target non-null instance of JAXB mapped class prior to unmarshalling into it.
1096 * @param parent instance of JAXB mapped class that will eventually reference <tt>target</tt>.
1097 * <tt>null</tt> when <tt>target</tt> is root element.
1098 */
1099 public void beforeUnmarshal(Object target, Object parent) {
1100 }
1101
1102 /**
1103 * <p>
1104 * Callback method invoked after unmarshalling XML data into <tt>target</tt>.
1105 * </p>
1106 * <p>
1107 * This method is invoked after all the properties (except IDREF) are unmarshalled into <tt>target</tt>,
1108 * but before <tt>target</tt> is set into its <tt>parent</tt> object.
1109 * Note that if the class of <tt>target</tt> defines its own <tt>afterUnmarshal</tt> method,
1110 * the class specific callback method is invoked before this method is invoked.
1111 *
1112 * @param target non-null instance of JAXB mapped class prior to unmarshalling into it.
1113 * @param parent instance of JAXB mapped class that will reference <tt>target</tt>.
1114 * <tt>null</tt> when <tt>target</tt> is root element.
1115 */
1116 public void afterUnmarshal(Object target, Object parent) {
1117 }
1118 }
1119
1120 /**
1121 * <p>
1122 * Register unmarshal event callback {@link Listener} with this {@link Unmarshaller}.
1123 *
1124 * <p>
1125 * There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener.
1126 * One can unregister current Listener by setting listener to <tt>null</tt>.
|