169 * Unmarshalling from a StAX XMLEventReader:
170 * <blockquote>
171 * <pre>
172 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
173 * Unmarshaller u = jc.createUnmarshaller();
174 *
175 * javax.xml.stream.XMLEventReader xmlEventReader =
176 * javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... );
177 *
178 * Object o = u.unmarshal( xmlEventReader );
179 * </pre>
180 * </blockquote>
181 *
182 * <p>
183 * <a name="unmarshalEx"></a>
184 * <b>Unmarshalling XML Data</b><br>
185 * <blockquote>
186 * Unmarshalling can deserialize XML data that represents either an entire XML document
187 * or a subtree of an XML document. Typically, it is sufficient to use the
188 * unmarshalling methods described by
189 * <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal root element that is declared globally</a>.
190 * These unmarshal methods utilize {@link JAXBContext}'s mapping of global XML element
191 * declarations and type definitions to JAXB mapped classes to initiate the
192 * unmarshalling of the root element of XML data. When the {@link JAXBContext}'s
193 * mappings are not sufficient to unmarshal the root element of XML data,
194 * the application can assist the unmarshalling process by using the
195 * <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType methods</a>.
196 * These methods are useful for unmarshalling XML data where
197 * the root element corresponds to a local element declaration in the schema.
198 * </blockquote>
199 *
200 * <blockquote>
201 * An unmarshal method never returns null. If the unmarshal process is unable to unmarshal
202 * the root of XML content to a JAXB mapped object, a fatal error is reported that
203 * terminates processing by throwing JAXBException.
204 * </blockquote>
205 *
206 * <p>
207 * <a name="unmarshalGlobal"></a>
208 * <b>Unmarshal a root element that is globally declared</b><br>
209 * <blockquote>
210 * The unmarshal methods that do not have an {@code declaredType} parameter use
211 * {@link JAXBContext} to unmarshal the root element of an XML data. The {@link JAXBContext}
212 * instance is the one that was used to create this {@code Unmarshaller}. The {@link JAXBContext}
213 * instance maintains a mapping of globally declared XML element and type definition names to
214 * JAXB mapped classes. The unmarshal method checks if {@link JAXBContext} has a mapping
215 * from the root element's XML name and/or {@code @xsi:type} to a JAXB mapped class. If it does, it umarshalls the
259 * </thead>
260 * <tbody>
261 * <tr>
262 * <th scope="row">value</th>
263 * <td>{@code instanceof declaredType}</td>
264 * </tr>
265 * <tr>
266 * <th scope="row">declaredType</th>
267 * <td>unmarshal method {@code declaredType} parameter</td>
268 * </tr>
269 * <tr>
270 * <th scope="row">scope</th>
271 * <td>{@code null} <i>(actual scope is unknown)</i></td>
272 * </tr>
273 * </tbody>
274 * </table>
275 * </blockquote>
276 *
277 * <p>
278 * The following is an example of
279 * <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType method</a>.
280 * <p>
281 * Unmarshal by declaredType from a {@code org.w3c.dom.Node}:
282 * <blockquote>
283 * <pre>{@code
284 * Schema fragment for example
285 * <xs:schema>
286 * <xs:complexType name="FooType">...<\xs:complexType>
287 * <!-- global element declaration "PurchaseOrder" -->
288 * <xs:element name="PurchaseOrder">
289 * <xs:complexType>
290 * <xs:sequence>
291 * <!-- local element declaration "foo" -->
292 * <xs:element name="foo" type="FooType"/>
293 * ...
294 * </xs:sequence>
295 * </xs:complexType>
296 * </xs:element>
297 * </xs:schema>
298 *
299 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
405 * @since 1.6, JAXB 1.0
406 */
407 public interface Unmarshaller {
408
409 /**
410 * Unmarshal XML data from the specified file and return the resulting
411 * content tree.
412 *
413 * <p>
414 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
415 *
416 * @param f the file to unmarshal XML data from
417 * @return the newly created root object of the java content tree
418 *
419 * @throws JAXBException
420 * If any unexpected errors occur while unmarshalling
421 * @throws UnmarshalException
422 * If the {@link ValidationEventHandler ValidationEventHandler}
423 * returns false from its {@code handleEvent} method or the
424 * {@code Unmarshaller} is unable to perform the XML to Java
425 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
426 * @throws IllegalArgumentException
427 * If the file parameter is null
428 */
429 public Object unmarshal( java.io.File f ) throws JAXBException;
430
431 /**
432 * Unmarshal XML data from the specified InputStream and return the
433 * resulting content tree. Validation event location information may
434 * be incomplete when using this form of the unmarshal API.
435 *
436 * <p>
437 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
438 *
439 * @param is the InputStream to unmarshal XML data from
440 * @return the newly created root object of the java content tree
441 *
442 * @throws JAXBException
443 * If any unexpected errors occur while unmarshalling
444 * @throws UnmarshalException
445 * If the {@link ValidationEventHandler ValidationEventHandler}
446 * returns false from its {@code handleEvent} method or the
447 * {@code Unmarshaller} is unable to perform the XML to Java
448 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
449 * @throws IllegalArgumentException
450 * If the InputStream parameter is null
451 */
452 public Object unmarshal( java.io.InputStream is ) throws JAXBException;
453
454 /**
455 * Unmarshal XML data from the specified Reader and return the
456 * resulting content tree. Validation event location information may
457 * be incomplete when using this form of the unmarshal API,
458 * because a Reader does not provide the system ID.
459 *
460 * <p>
461 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
462 *
463 * @param reader the Reader to unmarshal XML data from
464 * @return the newly created root object of the java content tree
465 *
466 * @throws JAXBException
467 * If any unexpected errors occur while unmarshalling
468 * @throws UnmarshalException
469 * If the {@link ValidationEventHandler ValidationEventHandler}
470 * returns false from its {@code handleEvent} method or the
471 * {@code Unmarshaller} is unable to perform the XML to Java
472 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
473 * @throws IllegalArgumentException
474 * If the InputStream parameter is null
475 * @since 1.6, JAXB 2.0
476 */
477 public Object unmarshal( Reader reader ) throws JAXBException;
478
479 /**
480 * Unmarshal XML data from the specified URL and return the resulting
481 * content tree.
482 *
483 * <p>
484 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
485 *
486 * @param url the url to unmarshal XML data from
487 * @return the newly created root object of the java content tree
488 *
489 * @throws JAXBException
490 * If any unexpected errors occur while unmarshalling
491 * @throws UnmarshalException
492 * If the {@link ValidationEventHandler ValidationEventHandler}
493 * returns false from its {@code handleEvent} method or the
494 * {@code Unmarshaller} is unable to perform the XML to Java
495 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
496 * @throws IllegalArgumentException
497 * If the URL parameter is null
498 */
499 public Object unmarshal( java.net.URL url ) throws JAXBException;
500
501 /**
502 * Unmarshal XML data from the specified SAX InputSource and return the
503 * resulting content tree.
504 *
505 * <p>
506 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
507 *
508 * @param source the input source to unmarshal XML data from
509 * @return the newly created root object of the java content tree
510 *
511 * @throws JAXBException
512 * If any unexpected errors occur while unmarshalling
513 * @throws UnmarshalException
514 * If the {@link ValidationEventHandler ValidationEventHandler}
515 * returns false from its {@code handleEvent} method or the
516 * {@code Unmarshaller} is unable to perform the XML to Java
517 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
518 * @throws IllegalArgumentException
519 * If the InputSource parameter is null
520 */
521 public Object unmarshal( org.xml.sax.InputSource source ) throws JAXBException;
522
523 /**
524 * Unmarshal global XML data from the specified DOM tree and return the resulting
525 * content tree.
526 *
527 * <p>
528 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
529 *
530 * @param node
531 * the document/element to unmarshal XML data from.
532 * The caller must support at least Document and Element.
533 * @return the newly created root object of the java content tree
534 *
535 * @throws JAXBException
536 * If any unexpected errors occur while unmarshalling
537 * @throws UnmarshalException
538 * If the {@link ValidationEventHandler ValidationEventHandler}
539 * returns false from its {@code handleEvent} method or the
540 * {@code Unmarshaller} is unable to perform the XML to Java
541 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
542 * @throws IllegalArgumentException
543 * If the Node parameter is null
544 * @see #unmarshal(org.w3c.dom.Node, Class)
545 */
546 public Object unmarshal( org.w3c.dom.Node node ) throws JAXBException;
547
548 /**
549 * Unmarshal XML data by JAXB mapped {@code declaredType}
550 * and return the resulting content tree.
551 *
552 * <p>
553 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
554 *
555 * @param node
556 * the document/element to unmarshal XML data from.
557 * The caller must support at least Document and Element.
558 * @param declaredType
559 * appropriate JAXB mapped class to hold {@code node}'s XML data.
560 *
561 * @return <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element</a> representation of {@code node}
562 *
563 * @throws JAXBException
564 * If any unexpected errors occur while unmarshalling
565 * @throws UnmarshalException
566 * If the {@link ValidationEventHandler ValidationEventHandler}
567 * returns false from its {@code handleEvent} method or the
568 * {@code Unmarshaller} is unable to perform the XML to Java
569 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
570 * @throws IllegalArgumentException
571 * If any parameter is null
572 * @since 1.6, JAXB 2.0
573 */
574 public <T> JAXBElement<T> unmarshal( org.w3c.dom.Node node, Class<T> declaredType ) throws JAXBException;
575
576 /**
577 * Unmarshal XML data from the specified XML Source and return the
578 * resulting content tree.
579 *
580 * <p>
581 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
582 *
583 * <p>
584 * <a name="saxParserPlugable"></a>
585 * <b>SAX 2.0 Parser Pluggability</b>
586 * <p>
587 * A client application can choose not to use the default parser mechanism
588 * supplied with their JAXB provider. Any SAX 2.0 compliant parser can be
589 * substituted for the JAXB provider's default mechanism. To do so, the
590 * client application must properly configure a {@code SAXSource} containing
591 * an {@code XMLReader} implemented by the SAX 2.0 parser provider. If the
592 * {@code XMLReader} has an {@code org.xml.sax.ErrorHandler} registered
593 * on it, it will be replaced by the JAXB Provider so that validation errors
594 * can be reported via the {@code ValidationEventHandler} mechanism of
595 * JAXB. If the {@code SAXSource} does not contain an {@code XMLReader},
596 * then the JAXB provider's default parser mechanism will be used.
597 * <p>
598 * This parser replacement mechanism can also be used to replace the JAXB
599 * provider's unmarshal-time validation engine. The client application
600 * must properly configure their SAX 2.0 compliant parser to perform
601 * validation (as shown in the example above). Any {@code SAXParserExceptions}
607 * SAX 2.0 parser for unmarshalling does not necessarily replace the
608 * validation engine used by the JAXB provider for performing on-demand
609 * validation.
610 * <p>
611 * The only way for a client application to specify an alternate parser
612 * mechanism to be used during unmarshal is via the
613 * {@code unmarshal(SAXSource)} API. All other forms of the unmarshal
614 * method (File, URL, Node, etc) will use the JAXB provider's default
615 * parser and validator mechanisms.
616 *
617 * @param source the XML Source to unmarshal XML data from (providers are
618 * only required to support SAXSource, DOMSource, and StreamSource)
619 * @return the newly created root object of the java content tree
620 *
621 * @throws JAXBException
622 * If any unexpected errors occur while unmarshalling
623 * @throws UnmarshalException
624 * If the {@link ValidationEventHandler ValidationEventHandler}
625 * returns false from its {@code handleEvent} method or the
626 * {@code Unmarshaller} is unable to perform the XML to Java
627 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
628 * @throws IllegalArgumentException
629 * If the Source parameter is null
630 * @see #unmarshal(javax.xml.transform.Source, Class)
631 */
632 public Object unmarshal( javax.xml.transform.Source source )
633 throws JAXBException;
634
635
636 /**
637 * Unmarshal XML data from the specified XML Source by {@code declaredType} and return the
638 * resulting content tree.
639 *
640 * <p>
641 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
642 *
643 * <p>
644 * See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#saxParserPlugable">SAX 2.0 Parser Pluggability</a>
645 *
646 * @param source the XML Source to unmarshal XML data from (providers are
647 * only required to support SAXSource, DOMSource, and StreamSource)
648 * @param declaredType
649 * appropriate JAXB mapped class to hold {@code source}'s xml root element
650 * @return Java content rooted by <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element</a>
651 *
652 * @throws JAXBException
653 * If any unexpected errors occur while unmarshalling
654 * @throws UnmarshalException
655 * If the {@link ValidationEventHandler ValidationEventHandler}
656 * returns false from its {@code handleEvent} method or the
657 * {@code Unmarshaller} is unable to perform the XML to Java
658 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
659 * @throws IllegalArgumentException
660 * If any parameter is null
661 * @since 1.6, JAXB 2.0
662 */
663 public <T> JAXBElement<T> unmarshal( javax.xml.transform.Source source, Class<T> declaredType )
664 throws JAXBException;
665
666 /**
667 * Unmarshal XML data from the specified pull parser and return the
668 * resulting content tree.
669 *
670 * <p>
671 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
672 *
673 * <p>
674 * This method assumes that the parser is on a START_DOCUMENT or
675 * START_ELEMENT event. Unmarshalling will be done from this
676 * start event to the corresponding end event. If this method
677 * returns successfully, the {@code reader} will be pointing at
678 * the token right after the end event.
679 *
680 * @param reader
681 * The parser to be read.
682 * @return
683 * the newly created root object of the java content tree.
684 *
685 * @throws JAXBException
686 * If any unexpected errors occur while unmarshalling
687 * @throws UnmarshalException
688 * If the {@link ValidationEventHandler ValidationEventHandler}
689 * returns false from its {@code handleEvent} method or the
690 * {@code Unmarshaller} is unable to perform the XML to Java
691 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
692 * @throws IllegalArgumentException
693 * If the {@code reader} parameter is null
694 * @throws IllegalStateException
695 * If {@code reader} is not pointing to a START_DOCUMENT or
696 * START_ELEMENT event.
697 * @since 1.6, JAXB 2.0
698 * @see #unmarshal(javax.xml.stream.XMLStreamReader, Class)
699 */
700 public Object unmarshal( javax.xml.stream.XMLStreamReader reader )
701 throws JAXBException;
702
703 /**
704 * Unmarshal root element to JAXB mapped {@code declaredType}
705 * and return the resulting content tree.
706 *
707 * <p>
708 * This method implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType</a>.
709 * <p>
710 * This method assumes that the parser is on a START_DOCUMENT or
711 * START_ELEMENT event. Unmarshalling will be done from this
712 * start event to the corresponding end event. If this method
713 * returns successfully, the {@code reader} will be pointing at
714 * the token right after the end event.
715 *
716 * @param reader
717 * The parser to be read.
718 * @param declaredType
719 * appropriate JAXB mapped class to hold {@code reader}'s START_ELEMENT XML data.
720 *
721 * @return content tree rooted by <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
722 *
723 * @throws JAXBException
724 * If any unexpected errors occur while unmarshalling
725 * @throws UnmarshalException
726 * If the {@link ValidationEventHandler ValidationEventHandler}
727 * returns false from its {@code handleEvent} method or the
728 * {@code Unmarshaller} is unable to perform the XML to Java
729 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
730 * @throws IllegalArgumentException
731 * If any parameter is null
732 * @since 1.6, JAXB 2.0
733 */
734 public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLStreamReader reader, Class<T> declaredType ) throws JAXBException;
735
736 /**
737 * Unmarshal XML data from the specified pull parser and return the
738 * resulting content tree.
739 *
740 * <p>
741 * This method is an <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root method</a>.
742 *
743 * <p>
744 * This method assumes that the parser is on a START_DOCUMENT or
745 * START_ELEMENT event. Unmarshalling will be done from this
746 * start event to the corresponding end event. If this method
747 * returns successfully, the {@code reader} will be pointing at
748 * the token right after the end event.
749 *
750 * @param reader
751 * The parser to be read.
752 * @return
753 * the newly created root object of the java content tree.
754 *
755 * @throws JAXBException
756 * If any unexpected errors occur while unmarshalling
757 * @throws UnmarshalException
758 * If the {@link ValidationEventHandler ValidationEventHandler}
759 * returns false from its {@code handleEvent} method or the
760 * {@code Unmarshaller} is unable to perform the XML to Java
761 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
762 * @throws IllegalArgumentException
763 * If the {@code reader} parameter is null
764 * @throws IllegalStateException
765 * If {@code reader} is not pointing to a START_DOCUMENT or
766 * START_ELEMENT event.
767 * @since 1.6, JAXB 2.0
768 * @see #unmarshal(javax.xml.stream.XMLEventReader, Class)
769 */
770 public Object unmarshal( javax.xml.stream.XMLEventReader reader )
771 throws JAXBException;
772
773 /**
774 * Unmarshal root element to JAXB mapped {@code declaredType}
775 * and return the resulting content tree.
776 *
777 * <p>
778 * This method implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType</a>.
779 *
780 * <p>
781 * This method assumes that the parser is on a START_DOCUMENT or
782 * START_ELEMENT event. Unmarshalling will be done from this
783 * start event to the corresponding end event. If this method
784 * returns successfully, the {@code reader} will be pointing at
785 * the token right after the end event.
786 *
787 * @param reader
788 * The parser to be read.
789 * @param declaredType
790 * appropriate JAXB mapped class to hold {@code reader}'s START_ELEMENT XML data.
791 *
792 * @return content tree rooted by <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
793 *
794 * @throws JAXBException
795 * If any unexpected errors occur while unmarshalling
796 * @throws UnmarshalException
797 * If the {@link ValidationEventHandler ValidationEventHandler}
798 * returns false from its {@code handleEvent} method or the
799 * {@code Unmarshaller} is unable to perform the XML to Java
800 * binding. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
801 * @throws IllegalArgumentException
802 * If any parameter is null
803 * @since 1.6, JAXB 2.0
804 */
805 public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLEventReader reader, Class<T> declaredType ) throws JAXBException;
806
807 /**
808 * Get an unmarshaller handler object that can be used as a component in
809 * an XML pipeline.
810 *
811 * <p>
812 * The JAXB Provider can return the same handler object for multiple
813 * invocations of this method. In other words, this method does not
814 * necessarily create a new instance of {@code UnmarshallerHandler}. If the
815 * application needs to use more than one {@code UnmarshallerHandler}, it
816 * should create more than one {@code Unmarshaller}.
817 *
818 * @return the unmarshaller handler object
819 * @see UnmarshallerHandler
820 */
893 public void setEventHandler( ValidationEventHandler handler )
894 throws JAXBException;
895
896 /**
897 * Return the current event handler or the default event handler if one
898 * hasn't been set.
899 *
900 * @return the current ValidationEventHandler or the default event handler
901 * if it hasn't been set
902 * @throws JAXBException if an error was encountered while getting the
903 * current event handler
904 */
905 public ValidationEventHandler getEventHandler()
906 throws JAXBException;
907
908 /**
909 * Set the particular property in the underlying implementation of
910 * {@code Unmarshaller}. This method can only be used to set one of
911 * the standard JAXB defined properties above or a provider specific
912 * property. Attempting to set an undefined property will result in
913 * a PropertyException being thrown. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#supportedProps">
914 * Supported Properties</a>.
915 *
916 * @param name the name of the property to be set. This value can either
917 * be specified using one of the constant fields or a user
918 * supplied string.
919 * @param value the value of the property to be set
920 *
921 * @throws PropertyException when there is an error processing the given
922 * property or value
923 * @throws IllegalArgumentException
924 * If the name parameter is null
925 */
926 public void setProperty( String name, Object value )
927 throws PropertyException;
928
929 /**
930 * Get the particular property in the underlying implementation of
931 * {@code Unmarshaller}. This method can only be used to get one of
932 * the standard JAXB defined properties above or a provider specific
933 * property. Attempting to get an undefined property will result in
934 * a PropertyException being thrown. See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#supportedProps">
935 * Supported Properties</a>.
936 *
937 * @param name the name of the property to retrieve
938 * @return the value of the requested property
939 *
940 * @throws PropertyException
941 * when there is an error retrieving the given property or value
942 * property name
943 * @throws IllegalArgumentException
944 * If the name parameter is null
945 */
946 public Object getProperty( String name ) throws PropertyException;
947
948 /**
949 * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema}
950 * object that should be used to validate subsequent unmarshal operations
951 * against. Passing null into this method will disable validation.
952 * <p>
953 * This method replaces the deprecated {@link #setValidating(boolean) setValidating(boolean)}
954 * API.
|
169 * Unmarshalling from a StAX XMLEventReader:
170 * <blockquote>
171 * <pre>
172 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
173 * Unmarshaller u = jc.createUnmarshaller();
174 *
175 * javax.xml.stream.XMLEventReader xmlEventReader =
176 * javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... );
177 *
178 * Object o = u.unmarshal( xmlEventReader );
179 * </pre>
180 * </blockquote>
181 *
182 * <p>
183 * <a name="unmarshalEx"></a>
184 * <b>Unmarshalling XML Data</b><br>
185 * <blockquote>
186 * Unmarshalling can deserialize XML data that represents either an entire XML document
187 * or a subtree of an XML document. Typically, it is sufficient to use the
188 * unmarshalling methods described by
189 * <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal root element that is declared globally</a>.
190 * These unmarshal methods utilize {@link JAXBContext}'s mapping of global XML element
191 * declarations and type definitions to JAXB mapped classes to initiate the
192 * unmarshalling of the root element of XML data. When the {@link JAXBContext}'s
193 * mappings are not sufficient to unmarshal the root element of XML data,
194 * the application can assist the unmarshalling process by using the
195 * <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType methods</a>.
196 * These methods are useful for unmarshalling XML data where
197 * the root element corresponds to a local element declaration in the schema.
198 * </blockquote>
199 *
200 * <blockquote>
201 * An unmarshal method never returns null. If the unmarshal process is unable to unmarshal
202 * the root of XML content to a JAXB mapped object, a fatal error is reported that
203 * terminates processing by throwing JAXBException.
204 * </blockquote>
205 *
206 * <p>
207 * <a name="unmarshalGlobal"></a>
208 * <b>Unmarshal a root element that is globally declared</b><br>
209 * <blockquote>
210 * The unmarshal methods that do not have an {@code declaredType} parameter use
211 * {@link JAXBContext} to unmarshal the root element of an XML data. The {@link JAXBContext}
212 * instance is the one that was used to create this {@code Unmarshaller}. The {@link JAXBContext}
213 * instance maintains a mapping of globally declared XML element and type definition names to
214 * JAXB mapped classes. The unmarshal method checks if {@link JAXBContext} has a mapping
215 * from the root element's XML name and/or {@code @xsi:type} to a JAXB mapped class. If it does, it umarshalls the
259 * </thead>
260 * <tbody>
261 * <tr>
262 * <th scope="row">value</th>
263 * <td>{@code instanceof declaredType}</td>
264 * </tr>
265 * <tr>
266 * <th scope="row">declaredType</th>
267 * <td>unmarshal method {@code declaredType} parameter</td>
268 * </tr>
269 * <tr>
270 * <th scope="row">scope</th>
271 * <td>{@code null} <i>(actual scope is unknown)</i></td>
272 * </tr>
273 * </tbody>
274 * </table>
275 * </blockquote>
276 *
277 * <p>
278 * The following is an example of
279 * <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType method</a>.
280 * <p>
281 * Unmarshal by declaredType from a {@code org.w3c.dom.Node}:
282 * <blockquote>
283 * <pre>{@code
284 * Schema fragment for example
285 * <xs:schema>
286 * <xs:complexType name="FooType">...<\xs:complexType>
287 * <!-- global element declaration "PurchaseOrder" -->
288 * <xs:element name="PurchaseOrder">
289 * <xs:complexType>
290 * <xs:sequence>
291 * <!-- local element declaration "foo" -->
292 * <xs:element name="foo" type="FooType"/>
293 * ...
294 * </xs:sequence>
295 * </xs:complexType>
296 * </xs:element>
297 * </xs:schema>
298 *
299 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
405 * @since 1.6, JAXB 1.0
406 */
407 public interface Unmarshaller {
408
409 /**
410 * Unmarshal XML data from the specified file and return the resulting
411 * content tree.
412 *
413 * <p>
414 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
415 *
416 * @param f the file to unmarshal XML data from
417 * @return the newly created root object of the java content tree
418 *
419 * @throws JAXBException
420 * If any unexpected errors occur while unmarshalling
421 * @throws UnmarshalException
422 * If the {@link ValidationEventHandler ValidationEventHandler}
423 * returns false from its {@code handleEvent} method or the
424 * {@code Unmarshaller} is unable to perform the XML to Java
425 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
426 * @throws IllegalArgumentException
427 * If the file parameter is null
428 */
429 public Object unmarshal( java.io.File f ) throws JAXBException;
430
431 /**
432 * Unmarshal XML data from the specified InputStream and return the
433 * resulting content tree. Validation event location information may
434 * be incomplete when using this form of the unmarshal API.
435 *
436 * <p>
437 * Implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
438 *
439 * @param is the InputStream to unmarshal XML data from
440 * @return the newly created root object of the java content tree
441 *
442 * @throws JAXBException
443 * If any unexpected errors occur while unmarshalling
444 * @throws UnmarshalException
445 * If the {@link ValidationEventHandler ValidationEventHandler}
446 * returns false from its {@code handleEvent} method or the
447 * {@code Unmarshaller} is unable to perform the XML to Java
448 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
449 * @throws IllegalArgumentException
450 * If the InputStream parameter is null
451 */
452 public Object unmarshal( java.io.InputStream is ) throws JAXBException;
453
454 /**
455 * Unmarshal XML data from the specified Reader and return the
456 * resulting content tree. Validation event location information may
457 * be incomplete when using this form of the unmarshal API,
458 * because a Reader does not provide the system ID.
459 *
460 * <p>
461 * Implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
462 *
463 * @param reader the Reader to unmarshal XML data from
464 * @return the newly created root object of the java content tree
465 *
466 * @throws JAXBException
467 * If any unexpected errors occur while unmarshalling
468 * @throws UnmarshalException
469 * If the {@link ValidationEventHandler ValidationEventHandler}
470 * returns false from its {@code handleEvent} method or the
471 * {@code Unmarshaller} is unable to perform the XML to Java
472 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
473 * @throws IllegalArgumentException
474 * If the InputStream parameter is null
475 * @since 1.6, JAXB 2.0
476 */
477 public Object unmarshal( Reader reader ) throws JAXBException;
478
479 /**
480 * Unmarshal XML data from the specified URL and return the resulting
481 * content tree.
482 *
483 * <p>
484 * Implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
485 *
486 * @param url the url to unmarshal XML data from
487 * @return the newly created root object of the java content tree
488 *
489 * @throws JAXBException
490 * If any unexpected errors occur while unmarshalling
491 * @throws UnmarshalException
492 * If the {@link ValidationEventHandler ValidationEventHandler}
493 * returns false from its {@code handleEvent} method or the
494 * {@code Unmarshaller} is unable to perform the XML to Java
495 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
496 * @throws IllegalArgumentException
497 * If the URL parameter is null
498 */
499 public Object unmarshal( java.net.URL url ) throws JAXBException;
500
501 /**
502 * Unmarshal XML data from the specified SAX InputSource and return the
503 * resulting content tree.
504 *
505 * <p>
506 * Implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
507 *
508 * @param source the input source to unmarshal XML data from
509 * @return the newly created root object of the java content tree
510 *
511 * @throws JAXBException
512 * If any unexpected errors occur while unmarshalling
513 * @throws UnmarshalException
514 * If the {@link ValidationEventHandler ValidationEventHandler}
515 * returns false from its {@code handleEvent} method or the
516 * {@code Unmarshaller} is unable to perform the XML to Java
517 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
518 * @throws IllegalArgumentException
519 * If the InputSource parameter is null
520 */
521 public Object unmarshal( org.xml.sax.InputSource source ) throws JAXBException;
522
523 /**
524 * Unmarshal global XML data from the specified DOM tree and return the resulting
525 * content tree.
526 *
527 * <p>
528 * Implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
529 *
530 * @param node
531 * the document/element to unmarshal XML data from.
532 * The caller must support at least Document and Element.
533 * @return the newly created root object of the java content tree
534 *
535 * @throws JAXBException
536 * If any unexpected errors occur while unmarshalling
537 * @throws UnmarshalException
538 * If the {@link ValidationEventHandler ValidationEventHandler}
539 * returns false from its {@code handleEvent} method or the
540 * {@code Unmarshaller} is unable to perform the XML to Java
541 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
542 * @throws IllegalArgumentException
543 * If the Node parameter is null
544 * @see #unmarshal(org.w3c.dom.Node, Class)
545 */
546 public Object unmarshal( org.w3c.dom.Node node ) throws JAXBException;
547
548 /**
549 * Unmarshal XML data by JAXB mapped {@code declaredType}
550 * and return the resulting content tree.
551 *
552 * <p>
553 * Implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
554 *
555 * @param node
556 * the document/element to unmarshal XML data from.
557 * The caller must support at least Document and Element.
558 * @param declaredType
559 * appropriate JAXB mapped class to hold {@code node}'s XML data.
560 *
561 * @return <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element</a> representation of {@code node}
562 *
563 * @throws JAXBException
564 * If any unexpected errors occur while unmarshalling
565 * @throws UnmarshalException
566 * If the {@link ValidationEventHandler ValidationEventHandler}
567 * returns false from its {@code handleEvent} method or the
568 * {@code Unmarshaller} is unable to perform the XML to Java
569 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
570 * @throws IllegalArgumentException
571 * If any parameter is null
572 * @since 1.6, JAXB 2.0
573 */
574 public <T> JAXBElement<T> unmarshal( org.w3c.dom.Node node, Class<T> declaredType ) throws JAXBException;
575
576 /**
577 * Unmarshal XML data from the specified XML Source and return the
578 * resulting content tree.
579 *
580 * <p>
581 * Implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
582 *
583 * <p>
584 * <a name="saxParserPlugable"></a>
585 * <b>SAX 2.0 Parser Pluggability</b>
586 * <p>
587 * A client application can choose not to use the default parser mechanism
588 * supplied with their JAXB provider. Any SAX 2.0 compliant parser can be
589 * substituted for the JAXB provider's default mechanism. To do so, the
590 * client application must properly configure a {@code SAXSource} containing
591 * an {@code XMLReader} implemented by the SAX 2.0 parser provider. If the
592 * {@code XMLReader} has an {@code org.xml.sax.ErrorHandler} registered
593 * on it, it will be replaced by the JAXB Provider so that validation errors
594 * can be reported via the {@code ValidationEventHandler} mechanism of
595 * JAXB. If the {@code SAXSource} does not contain an {@code XMLReader},
596 * then the JAXB provider's default parser mechanism will be used.
597 * <p>
598 * This parser replacement mechanism can also be used to replace the JAXB
599 * provider's unmarshal-time validation engine. The client application
600 * must properly configure their SAX 2.0 compliant parser to perform
601 * validation (as shown in the example above). Any {@code SAXParserExceptions}
607 * SAX 2.0 parser for unmarshalling does not necessarily replace the
608 * validation engine used by the JAXB provider for performing on-demand
609 * validation.
610 * <p>
611 * The only way for a client application to specify an alternate parser
612 * mechanism to be used during unmarshal is via the
613 * {@code unmarshal(SAXSource)} API. All other forms of the unmarshal
614 * method (File, URL, Node, etc) will use the JAXB provider's default
615 * parser and validator mechanisms.
616 *
617 * @param source the XML Source to unmarshal XML data from (providers are
618 * only required to support SAXSource, DOMSource, and StreamSource)
619 * @return the newly created root object of the java content tree
620 *
621 * @throws JAXBException
622 * If any unexpected errors occur while unmarshalling
623 * @throws UnmarshalException
624 * If the {@link ValidationEventHandler ValidationEventHandler}
625 * returns false from its {@code handleEvent} method or the
626 * {@code Unmarshaller} is unable to perform the XML to Java
627 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
628 * @throws IllegalArgumentException
629 * If the Source parameter is null
630 * @see #unmarshal(javax.xml.transform.Source, Class)
631 */
632 public Object unmarshal( javax.xml.transform.Source source )
633 throws JAXBException;
634
635
636 /**
637 * Unmarshal XML data from the specified XML Source by {@code declaredType} and return the
638 * resulting content tree.
639 *
640 * <p>
641 * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
642 *
643 * <p>
644 * See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#saxParserPlugable">SAX 2.0 Parser Pluggability</a>
645 *
646 * @param source the XML Source to unmarshal XML data from (providers are
647 * only required to support SAXSource, DOMSource, and StreamSource)
648 * @param declaredType
649 * appropriate JAXB mapped class to hold {@code source}'s xml root element
650 * @return Java content rooted by <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element</a>
651 *
652 * @throws JAXBException
653 * If any unexpected errors occur while unmarshalling
654 * @throws UnmarshalException
655 * If the {@link ValidationEventHandler ValidationEventHandler}
656 * returns false from its {@code handleEvent} method or the
657 * {@code Unmarshaller} is unable to perform the XML to Java
658 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
659 * @throws IllegalArgumentException
660 * If any parameter is null
661 * @since 1.6, JAXB 2.0
662 */
663 public <T> JAXBElement<T> unmarshal( javax.xml.transform.Source source, Class<T> declaredType )
664 throws JAXBException;
665
666 /**
667 * Unmarshal XML data from the specified pull parser and return the
668 * resulting content tree.
669 *
670 * <p>
671 * Implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
672 *
673 * <p>
674 * This method assumes that the parser is on a START_DOCUMENT or
675 * START_ELEMENT event. Unmarshalling will be done from this
676 * start event to the corresponding end event. If this method
677 * returns successfully, the {@code reader} will be pointing at
678 * the token right after the end event.
679 *
680 * @param reader
681 * The parser to be read.
682 * @return
683 * the newly created root object of the java content tree.
684 *
685 * @throws JAXBException
686 * If any unexpected errors occur while unmarshalling
687 * @throws UnmarshalException
688 * If the {@link ValidationEventHandler ValidationEventHandler}
689 * returns false from its {@code handleEvent} method or the
690 * {@code Unmarshaller} is unable to perform the XML to Java
691 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
692 * @throws IllegalArgumentException
693 * If the {@code reader} parameter is null
694 * @throws IllegalStateException
695 * If {@code reader} is not pointing to a START_DOCUMENT or
696 * START_ELEMENT event.
697 * @since 1.6, JAXB 2.0
698 * @see #unmarshal(javax.xml.stream.XMLStreamReader, Class)
699 */
700 public Object unmarshal( javax.xml.stream.XMLStreamReader reader )
701 throws JAXBException;
702
703 /**
704 * Unmarshal root element to JAXB mapped {@code declaredType}
705 * and return the resulting content tree.
706 *
707 * <p>
708 * This method implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType</a>.
709 * <p>
710 * This method assumes that the parser is on a START_DOCUMENT or
711 * START_ELEMENT event. Unmarshalling will be done from this
712 * start event to the corresponding end event. If this method
713 * returns successfully, the {@code reader} will be pointing at
714 * the token right after the end event.
715 *
716 * @param reader
717 * The parser to be read.
718 * @param declaredType
719 * appropriate JAXB mapped class to hold {@code reader}'s START_ELEMENT XML data.
720 *
721 * @return content tree rooted by <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
722 *
723 * @throws JAXBException
724 * If any unexpected errors occur while unmarshalling
725 * @throws UnmarshalException
726 * If the {@link ValidationEventHandler ValidationEventHandler}
727 * returns false from its {@code handleEvent} method or the
728 * {@code Unmarshaller} is unable to perform the XML to Java
729 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
730 * @throws IllegalArgumentException
731 * If any parameter is null
732 * @since 1.6, JAXB 2.0
733 */
734 public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLStreamReader reader, Class<T> declaredType ) throws JAXBException;
735
736 /**
737 * Unmarshal XML data from the specified pull parser and return the
738 * resulting content tree.
739 *
740 * <p>
741 * This method is an <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root method</a>.
742 *
743 * <p>
744 * This method assumes that the parser is on a START_DOCUMENT or
745 * START_ELEMENT event. Unmarshalling will be done from this
746 * start event to the corresponding end event. If this method
747 * returns successfully, the {@code reader} will be pointing at
748 * the token right after the end event.
749 *
750 * @param reader
751 * The parser to be read.
752 * @return
753 * the newly created root object of the java content tree.
754 *
755 * @throws JAXBException
756 * If any unexpected errors occur while unmarshalling
757 * @throws UnmarshalException
758 * If the {@link ValidationEventHandler ValidationEventHandler}
759 * returns false from its {@code handleEvent} method or the
760 * {@code Unmarshaller} is unable to perform the XML to Java
761 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
762 * @throws IllegalArgumentException
763 * If the {@code reader} parameter is null
764 * @throws IllegalStateException
765 * If {@code reader} is not pointing to a START_DOCUMENT or
766 * START_ELEMENT event.
767 * @since 1.6, JAXB 2.0
768 * @see #unmarshal(javax.xml.stream.XMLEventReader, Class)
769 */
770 public Object unmarshal( javax.xml.stream.XMLEventReader reader )
771 throws JAXBException;
772
773 /**
774 * Unmarshal root element to JAXB mapped {@code declaredType}
775 * and return the resulting content tree.
776 *
777 * <p>
778 * This method implements <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType</a>.
779 *
780 * <p>
781 * This method assumes that the parser is on a START_DOCUMENT or
782 * START_ELEMENT event. Unmarshalling will be done from this
783 * start event to the corresponding end event. If this method
784 * returns successfully, the {@code reader} will be pointing at
785 * the token right after the end event.
786 *
787 * @param reader
788 * The parser to be read.
789 * @param declaredType
790 * appropriate JAXB mapped class to hold {@code reader}'s START_ELEMENT XML data.
791 *
792 * @return content tree rooted by <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
793 *
794 * @throws JAXBException
795 * If any unexpected errors occur while unmarshalling
796 * @throws UnmarshalException
797 * If the {@link ValidationEventHandler ValidationEventHandler}
798 * returns false from its {@code handleEvent} method or the
799 * {@code Unmarshaller} is unable to perform the XML to Java
800 * binding. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
801 * @throws IllegalArgumentException
802 * If any parameter is null
803 * @since 1.6, JAXB 2.0
804 */
805 public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLEventReader reader, Class<T> declaredType ) throws JAXBException;
806
807 /**
808 * Get an unmarshaller handler object that can be used as a component in
809 * an XML pipeline.
810 *
811 * <p>
812 * The JAXB Provider can return the same handler object for multiple
813 * invocations of this method. In other words, this method does not
814 * necessarily create a new instance of {@code UnmarshallerHandler}. If the
815 * application needs to use more than one {@code UnmarshallerHandler}, it
816 * should create more than one {@code Unmarshaller}.
817 *
818 * @return the unmarshaller handler object
819 * @see UnmarshallerHandler
820 */
893 public void setEventHandler( ValidationEventHandler handler )
894 throws JAXBException;
895
896 /**
897 * Return the current event handler or the default event handler if one
898 * hasn't been set.
899 *
900 * @return the current ValidationEventHandler or the default event handler
901 * if it hasn't been set
902 * @throws JAXBException if an error was encountered while getting the
903 * current event handler
904 */
905 public ValidationEventHandler getEventHandler()
906 throws JAXBException;
907
908 /**
909 * Set the particular property in the underlying implementation of
910 * {@code Unmarshaller}. This method can only be used to set one of
911 * the standard JAXB defined properties above or a provider specific
912 * property. Attempting to set an undefined property will result in
913 * a PropertyException being thrown. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#supportedProps">
914 * Supported Properties</a>.
915 *
916 * @param name the name of the property to be set. This value can either
917 * be specified using one of the constant fields or a user
918 * supplied string.
919 * @param value the value of the property to be set
920 *
921 * @throws PropertyException when there is an error processing the given
922 * property or value
923 * @throws IllegalArgumentException
924 * If the name parameter is null
925 */
926 public void setProperty( String name, Object value )
927 throws PropertyException;
928
929 /**
930 * Get the particular property in the underlying implementation of
931 * {@code Unmarshaller}. This method can only be used to get one of
932 * the standard JAXB defined properties above or a provider specific
933 * property. Attempting to get an undefined property will result in
934 * a PropertyException being thrown. See <a href="{@docRoot}/java/xml/bind/Unmarshaller.html#supportedProps">
935 * Supported Properties</a>.
936 *
937 * @param name the name of the property to retrieve
938 * @return the value of the requested property
939 *
940 * @throws PropertyException
941 * when there is an error retrieving the given property or value
942 * property name
943 * @throws IllegalArgumentException
944 * If the name parameter is null
945 */
946 public Object getProperty( String name ) throws PropertyException;
947
948 /**
949 * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema}
950 * object that should be used to validate subsequent unmarshal operations
951 * against. Passing null into this method will disable validation.
952 * <p>
953 * This method replaces the deprecated {@link #setValidating(boolean) setValidating(boolean)}
954 * API.
|