Top Description Inners Fields Constructors Methods
jakarta.xml.bind

public final Class JAXB

extends Object
Class Inheritance
Imports
jakarta.xml.bind.annotation.XmlRootElement, javax.xml.namespace.QName, javax.xml.transform.Result, .Source, javax.xml.transform.stream.StreamResult, .StreamSource, java.io.File, .IOException, .InputStream, .OutputStream, .Reader, .Writer, java.lang.ref.WeakReference, java.net.HttpURLConnection, .URI, .URISyntaxException, .URL, .URLConnection
Class that defines convenience methods for common, simple use of Jakarta XML Binding.

Methods defined in this class are convenience methods that combine several basic operations in the JAXBContext, Unmarshaller, and Marshaller. They are designed to be the prefered methods for developers new to Jakarta XML Binding. They have the following characterstics:

  1. Generally speaking, the performance is not necessarily optimal. It is expected that people who need to write performance critical code will use the rest of the Jakarta XML Binding API directly.
  2. Errors that happen during the processing is wrapped into DataBindingException (which will have JAXBException as its cause. It is expected that people who prefer the checked exception would use the rest of the Jakarta XML Binding API directly.

In addition, the unmarshal methods have the following characteristic:

  1. Schema validation is not performed on the input XML. The processing will try to continue even if there are errors in the XML, as much as possible. Only as the last resort, this method fails with DataBindingException.

Similarly, the marshal methods have the following characteristic:

  1. The processing will try to continue even if the Java object tree does not meet the validity requirement. Only as the last resort, this method fails with DataBindingException.

All the methods on this class require non-null arguments to all parameters. The unmarshal methods either fail with an exception or return a non-null value.

Author
Kohsuke Kawaguchi
Since
1.6, JAXB 2.1

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
JAXB.Cache

To improve the performance, we'll cache the last JAXBContext used.

Field Summary

Modifier and TypeField and Description
private static volatile WeakReference<JAXB.Cache>
cache

Cache.

Constructor Summary

AccessConstructor and Description
private
JAXB()

No instantiation is allowed.

Method Summary

Modifier and TypeMethod and Description
private static void
_marshal(Object
The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.
jaxbObject, Object
Represents the receiver of XML. Objects of the following types are allowed.
Allowed Objects
Type Operation
File XML will be written to this file. If it already exists, it will be overwritten.
URL The XML will be sent to the resource pointed by this URL. Note that not all URLs support such operation, and exact semantics depends on the URL implementations. In case of HTTP URLs, this will perform HTTP POST.
URI The URI is turned into URL and then follows the handling of URL. See above.
String The string is first interpreted as an absolute URI. If it's not a valid absolute URI, then it's interpreted as a File
OutputStream The XML will be sent to the given OutputStream. Upon a successful completion, the stream will be closed by this method.
Writer The XML will be sent as a character stream to the given Writer. Upon a successful completion, the stream will be closed by this method.
Result The XML will be sent to the Result object.
xml)

Writes a Java object tree to XML and store it to the specified location.

private static <T> JAXBContext
getContext(Class<T> type)

Obtains the JAXBContext from the given type, by using the cache if possible.

private static String
inferName(Class<?> clazz)

public static void
marshal(Object
The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.
jaxbObject, File
XML will be written to this file. If it already exists, it will be overwritten.
xml)

Writes a Java object tree to XML and store it to the specified location.

public static void
marshal(Object
The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.
jaxbObject, URL
The XML will be sent to the resource pointed by this URL. Note that not all URLs support such operation, and exact semantics depends on the URL implementations. In case of HTTP URLs, this will perform HTTP POST.
xml)

Writes a Java object tree to XML and store it to the specified location.

public static void
marshal(Object
The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.
jaxbObject, URI
The URI is turned into URL and then follows the handling of URL. See above.
xml)

Writes a Java object tree to XML and store it to the specified location.

public static void
marshal(Object
The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.
jaxbObject, String
The string is first interpreted as an absolute URI. If it's not a valid absolute URI, then it's interpreted as a File
xml)

Writes a Java object tree to XML and store it to the specified location.

public static void
marshal(Object
The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.
jaxbObject, OutputStream
The XML will be sent to the given OutputStream. Upon a successful completion, the stream will be closed by this method.
xml)

Writes a Java object tree to XML and store it to the specified location.

public static void
marshal(Object
The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.
jaxbObject, Writer
The XML will be sent as a character stream to the given Writer. Upon a successful completion, the stream will be closed by this method.
xml)

Writes a Java object tree to XML and store it to the specified location.

public static void
marshal(Object
The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.
jaxbObject, Result
The XML will be sent to the Result object.
xml)

Writes a Java object tree to XML and store it to the specified location.

private static Result
toResult(Object xml)

Creates Result from various XML representation.

private static Source
toSource(Object xml)

Creates Source from various XML representation.

public static <T> T
unmarshal(File
Reads the entire file as XML.
xml, Class<T> type)

Reads in a Java object tree from the given XML input.

public static <T> T
unmarshal(URL
The resource pointed by the URL is read in its entirety.
xml, Class<T> type)

Reads in a Java object tree from the given XML input.

public static <T> T
unmarshal(URI
The URI is turned into URL and then follows the handling of URL.
xml, Class<T> type)

Reads in a Java object tree from the given XML input.

public static <T> T
unmarshal(String
The string is first interpreted as an absolute URI. If it's not a valid absolute URI, then it's interpreted as a File
xml, Class<T> type)

Reads in a Java object tree from the given XML input.

public static <T> T
unmarshal(InputStream
The entire stream is read as an XML infoset. Upon a successful completion, the stream will be closed by this method.
xml, Class<T> type)

Reads in a Java object tree from the given XML input.

public static <T> T
unmarshal(Reader
The character stream is read as an XML infoset. The encoding declaration in the XML will be ignored. Upon a successful completion, the stream will be closed by this method.
xml, Class<T> type)

Reads in a Java object tree from the given XML input.

public static <T> T
unmarshal(Source
The XML infoset that the Source represents is read.
xml, Class<T> type)

Reads in a Java object tree from the given XML input.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

cacheback to summary
private static volatile WeakReference<JAXB.Cache> cache

Cache. We don't want to prevent the Cache#type from GC-ed, hence WeakReference.

Constructor Detail

JAXBback to summary
private JAXB()

No instantiation is allowed.

Method Detail

_marshalback to summary
private static void _marshal(Object jaxbObject, Object xml)

Writes a Java object tree to XML and store it to the specified location.

This method is a convenience method that combines several basic operations in the JAXBContext and Marshaller. This method is designed to be the prefered method for developers new to Jakarta XML Binding. This method has the following characterstics:

  1. Generally speaking, the performance is not necessarily optimal. It is expected that those people who need to write performance critical code will use the rest of the Jakarta XML Binding API directly.
  2. Errors that happen during the processing is wrapped into DataBindingException (which will have JAXBException as its cause. It is expected that those people who prefer the checked exception would use the rest of the Jakarta XML Binding API directly.
Parameters
jaxbObject:Object

The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.

xml:Object

Represents the receiver of XML. Objects of the following types are allowed.

Allowed Objects
Type Operation
File XML will be written to this file. If it already exists, it will be overwritten.
URL The XML will be sent to the resource pointed by this URL. Note that not all URLs support such operation, and exact semantics depends on the URL implementations. In case of HTTP URLs, this will perform HTTP POST.
URI The URI is turned into URL and then follows the handling of URL. See above.
String The string is first interpreted as an absolute URI. If it's not a valid absolute URI, then it's interpreted as a File
OutputStream The XML will be sent to the given OutputStream. Upon a successful completion, the stream will be closed by this method.
Writer The XML will be sent as a character stream to the given Writer. Upon a successful completion, the stream will be closed by this method.
Result The XML will be sent to the Result object.
Annotations
@SuppressWarnings:rawtypes, unchecked
Exceptions
DataBindingException:
If the operation fails, such as due to I/O error, unbindable classes.
getContextback to summary
private static <T> JAXBContext getContext(Class<T> type) throws JAXBException

Obtains the JAXBContext from the given type, by using the cache if possible.

We don't use locks to control access to cache, but this code should be thread-safe thanks to the immutable Cache and volatile.

inferNameback to summary
private static String inferName(Class<?> clazz)
marshalback to summary
public static void marshal(Object jaxbObject, File xml)

Writes a Java object tree to XML and store it to the specified location.

Parameters
jaxbObject:Object

The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.

xml:File

XML will be written to this file. If it already exists, it will be overwritten.

Exceptions
DataBindingException:
If the operation fails, such as due to I/O error, unbindable classes.
marshalback to summary
public static void marshal(Object jaxbObject, URL xml)

Writes a Java object tree to XML and store it to the specified location.

Parameters
jaxbObject:Object

The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.

xml:URL

The XML will be sent to the resource pointed by this URL. Note that not all URLs support such operation, and exact semantics depends on the URL implementations. In case of HTTP URLs, this will perform HTTP POST.

Exceptions
DataBindingException:
If the operation fails, such as due to I/O error, unbindable classes.
marshalback to summary
public static void marshal(Object jaxbObject, URI xml)

Writes a Java object tree to XML and store it to the specified location.

Parameters
jaxbObject:Object

The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.

xml:URI

The URI is turned into URL and then follows the handling of URL. See above.

Exceptions
DataBindingException:
If the operation fails, such as due to I/O error, unbindable classes.
marshalback to summary
public static void marshal(Object jaxbObject, String xml)

Writes a Java object tree to XML and store it to the specified location.

Parameters
jaxbObject:Object

The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.

xml:String

The string is first interpreted as an absolute URI. If it's not a valid absolute URI, then it's interpreted as a File

Exceptions
DataBindingException:
If the operation fails, such as due to I/O error, unbindable classes.
marshalback to summary
public static void marshal(Object jaxbObject, OutputStream xml)

Writes a Java object tree to XML and store it to the specified location.

Parameters
jaxbObject:Object

The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.

xml:OutputStream

The XML will be sent to the given OutputStream. Upon a successful completion, the stream will be closed by this method.

Exceptions
DataBindingException:
If the operation fails, such as due to I/O error, unbindable classes.
marshalback to summary
public static void marshal(Object jaxbObject, Writer xml)

Writes a Java object tree to XML and store it to the specified location.

Parameters
jaxbObject:Object

The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.

xml:Writer

The XML will be sent as a character stream to the given Writer. Upon a successful completion, the stream will be closed by this method.

Exceptions
DataBindingException:
If the operation fails, such as due to I/O error, unbindable classes.
marshalback to summary
public static void marshal(Object jaxbObject, Result xml)

Writes a Java object tree to XML and store it to the specified location.

Parameters
jaxbObject:Object

The Java object to be marshalled into XML. If this object is a JAXBElement, it will provide the root tag name and the body. If this object has XmlRootElement on its class definition, that will be used as the root tag name and the given object will provide the body. Otherwise, the root tag name is inferred from the short class name. This parameter must not be null.

xml:Result

The XML will be sent to the Result object.

Exceptions
DataBindingException:
If the operation fails, such as due to I/O error, unbindable classes.
toResultback to summary
private static Result toResult(Object xml) throws IOException

Creates Result from various XML representation. See _marshal(Object, Object) for the conversion rules.

toSourceback to summary
private static Source toSource(Object xml) throws IOException

Creates Source from various XML representation. See unmarshal for the conversion rules.

unmarshalback to summary
public static <T> T unmarshal(File xml, Class<T> type)

Reads in a Java object tree from the given XML input.

Parameters
xml:File

Reads the entire file as XML.

unmarshalback to summary
public static <T> T unmarshal(URL xml, Class<T> type)

Reads in a Java object tree from the given XML input.

Parameters
xml:URL

The resource pointed by the URL is read in its entirety.

unmarshalback to summary
public static <T> T unmarshal(URI xml, Class<T> type)

Reads in a Java object tree from the given XML input.

Parameters
xml:URI

The URI is turned into URL and then follows the handling of URL.

unmarshalback to summary
public static <T> T unmarshal(String xml, Class<T> type)

Reads in a Java object tree from the given XML input.

Parameters
xml:String

The string is first interpreted as an absolute URI. If it's not a valid absolute URI, then it's interpreted as a File

unmarshalback to summary
public static <T> T unmarshal(InputStream xml, Class<T> type)

Reads in a Java object tree from the given XML input.

Parameters
xml:InputStream

The entire stream is read as an XML infoset. Upon a successful completion, the stream will be closed by this method.

unmarshalback to summary
public static <T> T unmarshal(Reader xml, Class<T> type)

Reads in a Java object tree from the given XML input.

Parameters
xml:Reader

The character stream is read as an XML infoset. The encoding declaration in the XML will be ignored. Upon a successful completion, the stream will be closed by this method.

unmarshalback to summary
public static <T> T unmarshal(Source xml, Class<T> type)

Reads in a Java object tree from the given XML input.

Parameters
xml:Source

The XML infoset that the Source represents is read.

jakarta.xml.bind back to summary

private final Class JAXB.Cache

extends Object
Class Inheritance
To improve the performance, we'll cache the last JAXBContext used.

Field Summary

Modifier and TypeField and Description
pack-priv final JAXBContext
context

pack-priv final Class<?>
type

Constructor Summary

AccessConstructor and Description
public
Cache(Class<?> type)

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

contextback to summary
pack-priv final JAXBContext context
typeback to summary
pack-priv final Class<?> type

Constructor Detail

Cacheback to summary
public Cache(Class<?> type) throws JAXBException