325N/A * Copyright (c) 2006, 2011, Oracle and/or its affiliates. All rights reserved. 325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 325N/A * This code is free software; you can redistribute it and/or modify it 325N/A * under the terms of the GNU General Public License version 2 only, as 325N/A * published by the Free Software Foundation. Oracle designates this 325N/A * particular file as subject to the "Classpath" exception as provided 325N/A * by Oracle in the LICENSE file that accompanied this code. 325N/A * This code is distributed in the hope that it will be useful, but WITHOUT 325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 325N/A * version 2 for more details (a copy is included in the LICENSE file that 325N/A * accompanied this code). 325N/A * You should have received a copy of the GNU General Public License version 325N/A * 2 along with this work; if not, write to the Free Software Foundation, 325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 325N/A * or visit www.oracle.com if you need additional information or have any 325N/A * Class that defines convenience methods for common, simple use of JAXB. 325N/A * Methods defined in this class are convenience methods that combine several basic operations 325N/A * in the {@link JAXBContext}, {@link Unmarshaller}, and {@link Marshaller}. 325N/A * to be the prefered methods for developers new to JAXB. They have 325N/A * the following characterstics: 325N/A * <li>Generally speaking, the performance is not necessarily optimal. 325N/A * It is expected that people who need to write performance 325N/A * critical code will use the rest of the JAXB API directly. 325N/A * <li>Errors that happen during the processing is wrapped into 325N/A * {@link DataBindingException} (which will have {@link JAXBException} 325N/A * as its {@link Throwable#getCause() cause}. It is expected that 325N/A * people who prefer the checked exception would use 325N/A * the rest of the JAXB API directly. 325N/A * In addition, the <tt>unmarshal</tt> methods have the following characteristic: 325N/A * <li>Schema validation is not performed on the input XML. 325N/A * The processing will try to continue even if there 325N/A * are errors in the XML, as much as possible. Only as 325N/A * the last resort, this method fails with {@link DataBindingException}. 325N/A * Similarly, the <tt>marshal</tt> methods have the following characteristic: 325N/A * <li>The processing will try to continue even if the Java object tree 325N/A * does not meet the validity requirement. Only as 325N/A * the last resort, this method fails with {@link DataBindingException}. 325N/A * All the methods on this class require non-null arguments to all parameters. 325N/A * The <tt>unmarshal</tt> methods either fail with an exception or return 325N/A * @author Kohsuke Kawaguchi 325N/A * No instanciation is allowed. 325N/A * To improve the performance, we'll cache the last {@link JAXBContext} used. 325N/A * Cache. We don't want to prevent the {@link Cache#type} from GC-ed, 325N/A * hence {@link WeakReference}. 325N/A * Obtains the {@link JAXBContext} from the given type, 325N/A * by using the cache if possible. 325N/A * We don't use locks to control access to {@link #cache}, but this code 325N/A * should be thread-safe thanks to the immutable {@link Cache} and {@code volatile}. 325N/A * Reads in a Java object tree from the given XML input. 325N/A * Reads the entire file as XML. 325N/A * Reads in a Java object tree from the given XML input. 325N/A * The resource pointed by the URL is read in its entirety. 325N/A * Reads in a Java object tree from the given XML input. 325N/A * The URI is {@link URI#toURL() turned into URL} and then 325N/A * follows the handling of <tt>URL</tt>. 325N/A * Reads in a Java object tree from the given XML input. 325N/A * The string is first interpreted as an absolute <tt>URI</tt>. 325N/A * If it's not {@link URI#isAbsolute() a valid absolute URI}, 325N/A * then it's interpreted as a <tt>File</tt> 325N/A * Reads in a Java object tree from the given XML input. 325N/A * The entire stream is read as an XML infoset. 325N/A * Upon a successful completion, the stream will be closed by this method. 325N/A * Reads in a Java object tree from the given XML input. 325N/A * The character stream is read as an XML infoset. 325N/A * The encoding declaration in the XML will be ignored. 325N/A * Upon a successful completion, the stream will be closed by this method. 325N/A * Reads in a Java object tree from the given XML input. 325N/A * The XML infoset that the {@link Source} represents is read. 325N/A * Creates {@link Source} from various XML representation. 325N/A * See {@link #unmarshal} for the conversion rules. 325N/A * Writes a Java object tree to XML and store it to the specified location. 325N/A * The Java object to be marshalled into XML. If this object is 325N/A * a {@link JAXBElement}, it will provide the root tag name and 325N/A * the body. If this object has {@link XmlRootElement} 325N/A * on its class definition, that will be used as the root tag name 325N/A * and the given object will provide the body. Otherwise, 325N/A * the root tag name is {@link Introspector#decapitalize(String) infered} from 325N/A * {@link Class#getSimpleName() the short class name}. 325N/A * This parameter must not be null. 325N/A * XML will be written to this file. If it already exists, 325N/A * it will be overwritten. 325N/A * @throws DataBindingException 325N/A * If the operation fails, such as due to I/O error, unbindable classes. 325N/A * Writes a Java object tree to XML and store it to the specified location. 325N/A * The Java object to be marshalled into XML. If this object is 325N/A * a {@link JAXBElement}, it will provide the root tag name and 325N/A * the body. If this object has {@link XmlRootElement} 325N/A * on its class definition, that will be used as the root tag name 325N/A * and the given object will provide the body. Otherwise, 325N/A * the root tag name is {@link Introspector#decapitalize(String) infered} from 325N/A * {@link Class#getSimpleName() the short class name}. 325N/A * This parameter must not be null. 325N/A * The XML will be {@link URLConnection#getOutputStream() sent} to the 325N/A * resource pointed by this URL. Note that not all <tt>URL</tt>s support 325N/A * such operation, and exact semantics depends on the <tt>URL</tt> 325N/A * implementations. In case of {@link HttpURLConnection HTTP URLs}, 325N/A * this will perform HTTP POST. 325N/A * @throws DataBindingException 325N/A * If the operation fails, such as due to I/O error, unbindable classes. 325N/A * Writes a Java object tree to XML and store it to the specified location. 325N/A * The Java object to be marshalled into XML. If this object is 325N/A * a {@link JAXBElement}, it will provide the root tag name and 325N/A * the body. If this object has {@link XmlRootElement} 325N/A * on its class definition, that will be used as the root tag name 325N/A * and the given object will provide the body. Otherwise, 325N/A * the root tag name is {@link Introspector#decapitalize(String) infered} from 325N/A * {@link Class#getSimpleName() the short class name}. 325N/A * This parameter must not be null. 325N/A * The URI is {@link URI#toURL() turned into URL} and then 325N/A * follows the handling of <tt>URL</tt>. See above. 325N/A * @throws DataBindingException 325N/A * If the operation fails, such as due to I/O error, unbindable classes. 325N/A * Writes a Java object tree to XML and store it to the specified location. 325N/A * The Java object to be marshalled into XML. If this object is 325N/A * a {@link JAXBElement}, it will provide the root tag name and 325N/A * the body. If this object has {@link XmlRootElement} 325N/A * on its class definition, that will be used as the root tag name 325N/A * and the given object will provide the body. Otherwise, 325N/A * the root tag name is {@link Introspector#decapitalize(String) infered} from 325N/A * {@link Class#getSimpleName() the short class name}. 325N/A * This parameter must not be null. 325N/A * The string is first interpreted as an absolute <tt>URI</tt>. 325N/A * If it's not {@link URI#isAbsolute() a valid absolute URI}, 325N/A * then it's interpreted as a <tt>File</tt> 325N/A * @throws DataBindingException 325N/A * If the operation fails, such as due to I/O error, unbindable classes. 325N/A * Writes a Java object tree to XML and store it to the specified location. 325N/A * The Java object to be marshalled into XML. If this object is 325N/A * a {@link JAXBElement}, it will provide the root tag name and 325N/A * the body. If this object has {@link XmlRootElement} 325N/A * on its class definition, that will be used as the root tag name 325N/A * and the given object will provide the body. Otherwise, 325N/A * the root tag name is {@link Introspector#decapitalize(String) infered} from 325N/A * {@link Class#getSimpleName() the short class name}. 325N/A * This parameter must not be null. 325N/A * The XML will be sent to the given {@link OutputStream}. 325N/A * Upon a successful completion, the stream will be closed by this method. 325N/A * @throws DataBindingException 325N/A * If the operation fails, such as due to I/O error, unbindable classes. 325N/A * Writes a Java object tree to XML and store it to the specified location. 325N/A * The Java object to be marshalled into XML. If this object is 325N/A * a {@link JAXBElement}, it will provide the root tag name and 325N/A * the body. If this object has {@link XmlRootElement} 325N/A * on its class definition, that will be used as the root tag name 325N/A * and the given object will provide the body. Otherwise, 325N/A * the root tag name is {@link Introspector#decapitalize(String) infered} from 325N/A * {@link Class#getSimpleName() the short class name}. 325N/A * This parameter must not be null. 325N/A * The XML will be sent as a character stream to the given {@link Writer}. 325N/A * Upon a successful completion, the stream will be closed by this method. 325N/A * @throws DataBindingException 325N/A * If the operation fails, such as due to I/O error, unbindable classes. 325N/A * Writes a Java object tree to XML and store it to the specified location. 325N/A * The Java object to be marshalled into XML. If this object is 325N/A * a {@link JAXBElement}, it will provide the root tag name and 325N/A * the body. If this object has {@link XmlRootElement} 325N/A * on its class definition, that will be used as the root tag name 325N/A * and the given object will provide the body. Otherwise, 325N/A * the root tag name is {@link Introspector#decapitalize(String) infered} from 325N/A * {@link Class#getSimpleName() the short class name}. 325N/A * This parameter must not be null. 325N/A * The XML will be sent to the {@link Result} object. 325N/A * @throws DataBindingException 325N/A * If the operation fails, such as due to I/O error, unbindable classes. 325N/A * Writes a Java object tree to XML and store it to the specified location. 325N/A * This method is a convenience method that combines several basic operations 325N/A * in the {@link JAXBContext} and {@link Marshaller}. This method is designed 325N/A * to be the prefered method for developers new to JAXB. This method 325N/A * has the following characterstics: 325N/A * <li>Generally speaking, the performance is not necessarily optimal. 325N/A * It is expected that those people who need to write performance 325N/A * critical code will use the rest of the JAXB API directly. 325N/A * <li>Errors that happen during the processing is wrapped into 325N/A * {@link DataBindingException} (which will have {@link JAXBException} 325N/A * as its {@link Throwable#getCause() cause}. It is expected that 325N/A * those people who prefer the checked exception would use 325N/A * the rest of the JAXB API directly. 325N/A * The Java object to be marshalled into XML. If this object is 325N/A * a {@link JAXBElement}, it will provide the root tag name and 325N/A * the body. If this object has {@link XmlRootElement} 325N/A * on its class definition, that will be used as the root tag name 325N/A * and the given object will provide the body. Otherwise, 325N/A * the root tag name is {@link Introspector#decapitalize(String) infered} from 325N/A * {@link Class#getSimpleName() the short class name}. 325N/A * This parameter must not be null. 325N/A * Represents the receiver of XML. Objects of the following types are allowed. 325N/A * <td>{@link File}</td> 325N/A * <td>XML will be written to this file. If it already exists, 325N/A * it will be overwritten.</td> 325N/A * <td>The XML will be {@link URLConnection#getOutputStream() sent} to the 325N/A * resource pointed by this URL. Note that not all <tt>URL</tt>s support 325N/A * such operation, and exact semantics depends on the <tt>URL</tt> 325N/A * implementations. In case of {@link HttpURLConnection HTTP URLs}, 325N/A * this will perform HTTP POST.</td> 325N/A * <td>The URI is {@link URI#toURL() turned into URL} and then 325N/A * follows the handling of <tt>URL</tt>. See above.</td> 325N/A * <td>{@link String}</td> 325N/A * <td>The string is first interpreted as an absolute <tt>URI</tt>. 325N/A * If it's not {@link URI#isAbsolute() a valid absolute URI}, 325N/A * then it's interpreted as a <tt>File</tt></td> 325N/A * <td>{@link OutputStream}</td> 325N/A * <td>The XML will be sent to the given {@link OutputStream}. 325N/A * Upon a successful completion, the stream will be closed by this method.</td> 325N/A * <td>{@link Writer}</td> 325N/A * <td>The XML will be sent as a character stream to the given {@link Writer}. 325N/A * Upon a successful completion, the stream will be closed by this method.</td> 325N/A * <td>{@link Result}</td> 325N/A * <td>The XML will be sent to the {@link Result} object.</td> 325N/A * @throws DataBindingException 325N/A * If the operation fails, such as due to I/O error, unbindable classes. 325N/A // we need to infer the name 325N/A * Creates {@link Result} from various XML representation. 325N/A * See {@link #_marshal(Object,Object)} for the conversion rules.