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
158 * {@link JAXBIntrospector#isElement(java.lang.Object)};
159 * otherwise, a <tt>Marshaller.marshal</tt> method must throw a
160 * {@link MarshalException}. There exist two mechanisms
161 * to enable marshalling an instance that is not a JAXB element.
162 * One method is to wrap the instance as a value of a {@link JAXBElement},
163 * and pass the wrapper element as the first parameter to
164 * a <tt>Marshaller.marshal</tt> method. For java to schema binding, it
165 * is also possible to simply annotate the instance's class with
166 * @{@link XmlRootElement}.
167 * </blockquote>
168 *
169 * <p>
170 * <b>Encoding</b><br>
171 * <blockquote>
172 * By default, the Marshaller will use UTF-8 encoding when generating XML data
173 * to a <tt>java.io.OutputStream</tt>, or a <tt>java.io.Writer</tt>. Use the
174 * {@link #setProperty(String,Object) setProperty} API to change the output
175 * encoding used during these marshal operations. Client applications are
176 * expected to supply a valid character encoding name as defined in the
177 * <a href="http://www.w3.org/TR/2000/REC-xml-20001006#charencoding">W3C XML 1.0
178 * Recommendation</a> and supported by your Java Platform</a>.
179 * </blockquote>
180 *
181 * <p>
182 * <b>Validation and Well-Formedness</b><br>
183 * <blockquote>
184 * <p>
185 * Client applications are not required to validate the Java content tree prior
186 * to calling any of the marshal API's. Furthermore, there is no requirement
187 * that the Java content tree be valid with respect to its original schema in
188 * order to marshal it back into XML data. Different JAXB Providers will
189 * support marshalling invalid Java content trees at varying levels, however
190 * all JAXB Providers must be able to marshal a valid content tree back to
191 * XML data. A JAXB Provider must throw a <tt>MarshalException</tt> when it
192 * is unable to complete the marshal operation due to invalid content. Some
193 * JAXB Providers will fully allow marshalling invalid content, others will fail
194 * on the first validation error.
195 * <p>
196 * Even when schema validation is not explictly enabled for the marshal operation,
197 * it is possible that certain types of validation events will be detected
198 * during the operation. Validation events will be reported to the registered
647 /**
648 * Associates a configured instance of {@link XmlAdapter} with this marshaller.
649 *
650 * <p>
651 * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
652 *
653 * @see #setAdapter(Class,XmlAdapter)
654 * @throws IllegalArgumentException
655 * if the adapter parameter is null.
656 * @throws UnsupportedOperationException
657 * if invoked agains a JAXB 1.0 implementation.
658 * @since 1.6, JAXB 2.0
659 */
660 public void setAdapter( XmlAdapter adapter );
661
662 /**
663 * Associates a configured instance of {@link XmlAdapter} with this marshaller.
664 *
665 * <p>
666 * Every marshaller internally maintains a
667 * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
668 * which it uses for marshalling classes whose fields/methods are annotated
669 * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
670 *
671 * <p>
672 * This method allows applications to use a configured instance of {@link XmlAdapter}.
673 * When an instance of an adapter is not given, a marshaller will create
674 * one by invoking its default constructor.
675 *
676 * @param type
677 * The type of the adapter. The specified instance will be used when
678 * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
679 * refers to this type.
680 * @param adapter
681 * The instance of the adapter to be used. If null, it will un-register
682 * the current adapter set for this type.
683 * @throws IllegalArgumentException
684 * if the type parameter is null.
685 * @throws UnsupportedOperationException
686 * if invoked agains a JAXB 1.0 implementation.
687 * @since 1.6, JAXB 2.0
733 * @since 1.6, JAXB 2.0
734 */
735 public void setSchema( Schema schema );
736
737 /**
738 * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object
739 * being used to perform marshal-time validation. If there is no
740 * Schema set on the marshaller, then this method will return null
741 * indicating that marshal-time validation will not be performed.
742 *
743 * @return the Schema object being used to perform marshal-time
744 * validation or null if not present.
745 * @throws UnsupportedOperationException could be thrown if this method is
746 * invoked on an Marshaller created from a JAXBContext referencing
747 * JAXB 1.0 mapped classes
748 * @since 1.6, JAXB 2.0
749 */
750 public Schema getSchema();
751
752 /**
753 * <p/>
754 * Register an instance of an implementation of this class with a {@link Marshaller} to externally listen
755 * for marshal events.
756 * <p/>
757 * <p/>
758 * This class enables pre and post processing of each marshalled object.
759 * The event callbacks are called when marshalling from an instance that maps to an xml element or
760 * complex type definition. The event callbacks are not called when marshalling from an instance of a
761 * Java datatype that represents a simple type definition.
762 * <p/>
763 * <p/>
764 * External listener is one of two different mechanisms for defining marshal event callbacks.
765 * See <a href="Marshaller.html#marshalEventCallback">Marshal Event Callbacks</a> for an overview.
766 *
767 * @see Marshaller#setListener(Listener)
768 * @see Marshaller#getListener()
769 * @since 1.6, JAXB 2.0
770 */
771 public static abstract class Listener {
772 /**
773 * <p/>
774 * Callback method invoked before marshalling from <tt>source</tt> to XML.
775 * <p/>
776 * <p/>
777 * This method is invoked just before marshalling process starts to marshal <tt>source</tt>.
778 * Note that if the class of <tt>source</tt> defines its own <tt>beforeMarshal</tt> method,
779 * the class specific callback method is invoked just before this method is invoked.
780 *
781 * @param source instance of JAXB mapped class prior to marshalling from it.
782 */
783 public void beforeMarshal(Object source) {
784 }
785
786 /**
787 * <p/>
788 * Callback method invoked after marshalling <tt>source</tt> to XML.
789 * <p/>
790 * <p/>
791 * This method is invoked after <tt>source</tt> and all its descendants have been marshalled.
792 * Note that if the class of <tt>source</tt> defines its own <tt>afterMarshal</tt> method,
793 * the class specific callback method is invoked just before this method is invoked.
794 *
795 * @param source instance of JAXB mapped class after marshalling it.
796 */
797 public void afterMarshal(Object source) {
798 }
799 }
800
801 /**
802 * <p>
803 * Register marshal event callback {@link Listener} with this {@link Marshaller}.
804 *
805 * <p>
806 * There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener.
807 * One can unregister current Listener by setting listener to <tt>null</tt>.
808 *
809 * @param listener an instance of a class that implements {@link Listener}
810 * @since 1.6, JAXB 2.0
|
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
158 * {@link JAXBIntrospector#isElement(java.lang.Object)};
159 * otherwise, a <tt>Marshaller.marshal</tt> method must throw a
160 * {@link MarshalException}. There exist two mechanisms
161 * to enable marshalling an instance that is not a JAXB element.
162 * One method is to wrap the instance as a value of a {@link JAXBElement},
163 * and pass the wrapper element as the first parameter to
164 * a <tt>Marshaller.marshal</tt> method. For java to schema binding, it
165 * is also possible to simply annotate the instance's class with
166 * @{@link XmlRootElement}.
167 * </blockquote>
168 *
169 * <p>
170 * <b>Encoding</b><br>
171 * <blockquote>
172 * By default, the Marshaller will use UTF-8 encoding when generating XML data
173 * to a <tt>java.io.OutputStream</tt>, or a <tt>java.io.Writer</tt>. Use the
174 * {@link #setProperty(String,Object) setProperty} API to change the output
175 * encoding used during these marshal operations. Client applications are
176 * expected to supply a valid character encoding name as defined in the
177 * <a href="http://www.w3.org/TR/2000/REC-xml-20001006#charencoding">W3C XML 1.0
178 * Recommendation</a> and supported by your Java Platform.
179 * </blockquote>
180 *
181 * <p>
182 * <b>Validation and Well-Formedness</b><br>
183 * <blockquote>
184 * <p>
185 * Client applications are not required to validate the Java content tree prior
186 * to calling any of the marshal API's. Furthermore, there is no requirement
187 * that the Java content tree be valid with respect to its original schema in
188 * order to marshal it back into XML data. Different JAXB Providers will
189 * support marshalling invalid Java content trees at varying levels, however
190 * all JAXB Providers must be able to marshal a valid content tree back to
191 * XML data. A JAXB Provider must throw a <tt>MarshalException</tt> when it
192 * is unable to complete the marshal operation due to invalid content. Some
193 * JAXB Providers will fully allow marshalling invalid content, others will fail
194 * on the first validation error.
195 * <p>
196 * Even when schema validation is not explictly enabled for the marshal operation,
197 * it is possible that certain types of validation events will be detected
198 * during the operation. Validation events will be reported to the registered
647 /**
648 * Associates a configured instance of {@link XmlAdapter} with this marshaller.
649 *
650 * <p>
651 * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
652 *
653 * @see #setAdapter(Class,XmlAdapter)
654 * @throws IllegalArgumentException
655 * if the adapter parameter is null.
656 * @throws UnsupportedOperationException
657 * if invoked agains a JAXB 1.0 implementation.
658 * @since 1.6, JAXB 2.0
659 */
660 public void setAdapter( XmlAdapter adapter );
661
662 /**
663 * Associates a configured instance of {@link XmlAdapter} with this marshaller.
664 *
665 * <p>
666 * Every marshaller internally maintains a
667 * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
668 * which it uses for marshalling classes whose fields/methods are annotated
669 * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
670 *
671 * <p>
672 * This method allows applications to use a configured instance of {@link XmlAdapter}.
673 * When an instance of an adapter is not given, a marshaller will create
674 * one by invoking its default constructor.
675 *
676 * @param type
677 * The type of the adapter. The specified instance will be used when
678 * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
679 * refers to this type.
680 * @param adapter
681 * The instance of the adapter to be used. If null, it will un-register
682 * the current adapter set for this type.
683 * @throws IllegalArgumentException
684 * if the type parameter is null.
685 * @throws UnsupportedOperationException
686 * if invoked agains a JAXB 1.0 implementation.
687 * @since 1.6, JAXB 2.0
733 * @since 1.6, JAXB 2.0
734 */
735 public void setSchema( Schema schema );
736
737 /**
738 * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object
739 * being used to perform marshal-time validation. If there is no
740 * Schema set on the marshaller, then this method will return null
741 * indicating that marshal-time validation will not be performed.
742 *
743 * @return the Schema object being used to perform marshal-time
744 * validation or null if not present.
745 * @throws UnsupportedOperationException could be thrown if this method is
746 * invoked on an Marshaller created from a JAXBContext referencing
747 * JAXB 1.0 mapped classes
748 * @since 1.6, JAXB 2.0
749 */
750 public Schema getSchema();
751
752 /**
753 * <p>
754 * Register an instance of an implementation of this class with a {@link Marshaller} to externally listen
755 * for marshal events.
756 * </p>
757 * <p>
758 * This class enables pre and post processing of each marshalled object.
759 * The event callbacks are called when marshalling from an instance that maps to an xml element or
760 * complex type definition. The event callbacks are not called when marshalling from an instance of a
761 * Java datatype that represents a simple type definition.
762 * </p>
763 * <p>
764 * External listener is one of two different mechanisms for defining marshal event callbacks.
765 * See <a href="Marshaller.html#marshalEventCallback">Marshal Event Callbacks</a> for an overview.
766 *
767 * @see Marshaller#setListener(Listener)
768 * @see Marshaller#getListener()
769 * @since 1.6, JAXB 2.0
770 */
771 public static abstract class Listener {
772 /**
773 * <p>
774 * Callback method invoked before marshalling from <tt>source</tt> to XML.
775 * </p>
776 * <p>
777 * This method is invoked just before marshalling process starts to marshal <tt>source</tt>.
778 * Note that if the class of <tt>source</tt> defines its own <tt>beforeMarshal</tt> method,
779 * the class specific callback method is invoked just before this method is invoked.
780 *
781 * @param source instance of JAXB mapped class prior to marshalling from it.
782 */
783 public void beforeMarshal(Object source) {
784 }
785
786 /**
787 * <p>
788 * Callback method invoked after marshalling <tt>source</tt> to XML.
789 * </p>
790 * <p>
791 * This method is invoked after <tt>source</tt> and all its descendants have been marshalled.
792 * Note that if the class of <tt>source</tt> defines its own <tt>afterMarshal</tt> method,
793 * the class specific callback method is invoked just before this method is invoked.
794 *
795 * @param source instance of JAXB mapped class after marshalling it.
796 */
797 public void afterMarshal(Object source) {
798 }
799 }
800
801 /**
802 * <p>
803 * Register marshal event callback {@link Listener} with this {@link Marshaller}.
804 *
805 * <p>
806 * There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener.
807 * One can unregister current Listener by setting listener to <tt>null</tt>.
808 *
809 * @param listener an instance of a class that implements {@link Listener}
810 * @since 1.6, JAXB 2.0
|