uk.org.retep.util.xml
Class JAXBUtil

java.lang.Object
  uk.org.retep.util.concurrent.ReadWriteConcurrencySupport
      uk.org.retep.util.concurrent.ConcurrencySupport
          uk.org.retep.util.xml.JAXBUtil

@ThreadSafe
public class JAXBUtil
extends ConcurrencySupport

A suite of utility methods that make using JAXB a lot easier.

After creating an instance it allows you to add either the packages or a single class from each package that has been generated by xjc. This allows you to select what you want JAXB to be able to marshall/unmarshall.

Once you have selected everything you want, you can then use the getMashaller() and getUnmarshaller() methods to obtain the Marshaller/Unmarshaller's that operate over those packages.

In addition, due to the creation of the Marshaller/Unmarshaller's are an expensive operation, the class provides a concurrent pool of each, so you can return them back into the pool once you have finished them - really useful in a high load environment.

The MarshallerCallBack and UnmarshallerCallBack interfaces allow you to do additional configuration on Marshaller/Unmarshaller's when they are created.

Finally if you are using just the marshall/unmarshall methods, the class also provides those methods which will use the pool, removing the need to handle the get/release process from your code.

Author:

peter

Nested Class Summary

static interface	JAXBUtil.MarshallerCallback A callback called when a Marshaller is first created allowing the application to perform additional configuration on the Marshaller before it is first used
static interface	JAXBUtil.UnmarshallerCallback A callback called when a Unmarshaller is first created allowing the application to perform additional configuration on the Unmarshaller before it is first used

Constructor Summary

JAXBUtil()
Creates a new instance of JAXBUtil with no initial packages

JAXBUtil(ArrayList<String> packages)
Creates a new instance of JAXBUtil with packages added

JAXBUtil(String... packages)
Creates a new instance of JAXBUtil with packages added

Method Summary

void	addPackage(Class<?> clazz) Add the package containing the given class to this instance
void	addPackage(Package... packages) Add the Package to this instance
void	addPackage(String... pkg) Add one or more packages to this instance
void	addPackage(String pkg) Add one or more ':' delimited package names to this instance
void	addPackages(Class<?> clazz) Add all packages below this one to this instance
void	addPackages(Package pkg) Add all packages below this one to this instance
void	addSubPackages(String name) Add all subpackages to this instance
void	clear() Releases the JAXBContext and clears both the Marshaller and Unmarshaller pools.
void	ensureMarshallerPoolSize(int size) Ensure that the Marshaller pool contains this number of entries.
void	ensureUnmarshallerPoolSize(int size) Ensure that the Unmarshaller pool contains this number of entries.
JAXBContext	getJAXBContext() The current JAXBContext in use.
static <T> JAXBElement<T>	getJAXBElement(Object o) Utiity to cast an object to JAXBElement<T>
Marshaller	getMarshaller() Get a Marshaller from the pool, creating one as necessary.
JAXBUtil.MarshallerCallback	getMarshallerCallback() The callback currently used by Marshaller's, null if none
Unmarshaller	getUnmarshaller() Get an Unmarshaller from the pool, creating one as necessary.
JAXBUtil.UnmarshallerCallback	getUnmarshallerCallback() The callback currently used by Unmarshaller's, null if none
String	marshall(Object object) Marshall an object into a String
void	marshall(Object object, ContentHandler out) Marshal an object
void	marshall(Object object, File out) Marshal an object
void	marshall(Object object, Node out) Marshal an object
void	marshall(Object object, OutputStream out) Marshal an object
void	marshall(Object object, Result out) Marshal an object
void	marshall(Object object, Writer out) Marshal an object
void	marshall(Object object, XMLEventWriter out) Marshal an object
void	marshall(Object object, XMLStreamWriter out) Marshal an object
boolean	release(Marshaller marshaller) Releases a Marshaller back to the pool.
boolean	release(Unmarshaller unmarshaller) Releases a Unmarshaller back to the pool.
void	removePackage(Class<?> clazz) Remove the package containing this class
void	removePackage(Package pkg) Remove package
void	removePackage(String... pkg) Remove packages
void	removePackage(String pkg) Remove package
void	removePackages(Class<?> clazz) Remove the package containing this class and all sub-packages
void	removePackages(String name) Remove the package and all packages within it
void	removeSubPackages(Package pkg) Remove the package and all packages within it
void	setClassLoader(ClassLoader classLoader) Set the ClassLoader that JAXB will use.
void	setMarshallerCallback(JAXBUtil.MarshallerCallback marshallerCallback) Set the MarshallerCallback being used to configure Marshaller's, null if none
void	setPoolSize(int poolSize) Sets the size of the marshaller and unmarshaller pools.
void	setUnmarshallerCallback(JAXBUtil.UnmarshallerCallback unmarshallerCallback) Set the UnmarshallerCallback being used to configure Unmarshaller's, null if none
<T> T	unmarshall(File in) Unmarshal from a source
<T> T	unmarshall(InputSource in) Unmarshal from a source
<T> T	unmarshall(InputStream in) Unmarshal from a source
<T> T	unmarshall(Node in) Unmarshal from a source
<T> T	unmarshall(Reader in) Unmarshal from a source
<T> T	unmarshall(Source in) Unmarshal from a source
<T> T	unmarshall(String in) Unmarshal from a source
<T> T	unmarshall(URL in) Unmarshal from a source
<T> T	unmarshall(XMLEventReader in) Unmarshal from a source
<T> T	unmarshall(XMLStreamReader in) Unmarshal from a source

Methods inherited from class uk.org.retep.util.concurrent.ConcurrencySupport

getLog

Methods inherited from class uk.org.retep.util.concurrent.ReadWriteConcurrencySupport

readLock, writeLock

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JAXBUtil

public JAXBUtil()

Creates a new instance of JAXBUtil with no initial packages

JAXBUtil

public JAXBUtil(String... packages)

Creates a new instance of JAXBUtil with packages added

Parameters:

packages - packages to use

JAXBUtil

public JAXBUtil(ArrayList<String> packages)

Creates a new instance of JAXBUtil with packages added

Parameters:

packages - packages to use

Method Detail

setClassLoader

public void setClassLoader(ClassLoader classLoader)

Set the ClassLoader that JAXB will use. By default the caller's ClassLoader will be used but this method allows a specific ClassLoader to be used by JAXB, for example inside a J2EE environment or in an AnnotationProcessor.

Parameters:

classLoader - ClassLoader to use instead of the caller's ClassLoader

clear

@WriteLock
public void clear()

Releases the JAXBContext and clears both the Marshaller and Unmarshaller pools. Any Marshaller or Unmarshaller that was created by original JAXBContext will not be accepted by the release methods and any further requests for new Marshaller or Unmarshaller instances will be created from a new JAXBContext.

The various add and remove package methods call this method internally. It is public to enable the the pool's to be reset at any moment

Since:

9.3

addPackage

@WriteLock
public void addPackage(String... pkg)

Add one or more packages to this instance

Parameters:

pkg - One or more package names

addPackage

@WriteLock
public void addPackage(String pkg)

Add one or more ':' delimited package names to this instance

Parameters:

pkg - list of packages delimited by ':'

addPackage

public void addPackage(Package... packages)

Add the Package to this instance

Parameters:

packages - Package(s) to add

addPackage

public void addPackage(Class<?> clazz)

Add the package containing the given class to this instance

Parameters:

clazz - Class who's package is to be added

addPackages

public void addPackages(Class<?> clazz)

Add all packages below this one to this instance

Parameters:

clazz - Class who's package and subpackages are to be added

addPackages

@WriteLock
public void addPackages(Package pkg)

Add all packages below this one to this instance

Parameters:

pkg - Package and it's subpackages are to be added

addSubPackages

public void addSubPackages(String name)

Add all subpackages to this instance

Parameters:

name - Package and subpackages are to be added

removePackage

@WriteLock
public void removePackage(String... pkg)

Remove packages

Parameters:

pkg -

removePackage

@WriteLock
public void removePackage(String pkg)

Remove package

Parameters:

pkg -

removePackage

public void removePackage(Package pkg)

Remove package

Parameters:

pkg - Package to remove

removePackage

public void removePackage(Class<?> clazz)

Remove the package containing this class

Parameters:

clazz - Class who's package to remove

removePackages

public void removePackages(Class<?> clazz)

Remove the package containing this class and all sub-packages

Parameters:

clazz - Class who's package and subpackages are to be removed

removeSubPackages

@WriteLock
public void removeSubPackages(Package pkg)

Remove the package and all packages within it

Parameters:

pkg - Package to remove

removePackages

public void removePackages(String name)

Remove the package and all packages within it

Parameters:

name - Package to remove and all subpackages

getJAXBContext

@WriteLock
@Unsafe
public JAXBContext getJAXBContext()
                           throws JAXBException

The current JAXBContext in use.

Unless specifically necessary it is advised you do not use this method as the returned value can change during the lifetime of the JAXBUtil instance.

Returns:

Throws:

JAXBException

ensureMarshallerPoolSize

public void ensureMarshallerPoolSize(int size)
                              throws JAXBException

Ensure that the Marshaller pool contains this number of entries.

Parameters:

size - The number of entries required

Throws:

JAXBException

IllegalArgumentException - if size < 1

ensureUnmarshallerPoolSize

public void ensureUnmarshallerPoolSize(int size)
                                throws JAXBException

Ensure that the Unmarshaller pool contains this number of entries.

Parameters:

size - The number of entries required

Throws:

JAXBException

IllegalArgumentException - if size < 1

setPoolSize

@WriteLock
public void setPoolSize(int poolSize)

Sets the size of the marshaller and unmarshaller pools.

By default, this is set to 0 (unlimited), but if this is set with a value > 0, then the pool's are limited to that number of free entries.

When release() is called and the pool is full, then that Marshaller or Unmarshaller is made available to the garbage collector.

When called, this will lock the pools for the duration of the call, as it resizes the existing pools. If the value is less than the current size but not 0, then the excess entries are made available to the garbage collector.

Parameters:

poolSize - The size of each pool, 0 for unlimited.

getMarshaller

public Marshaller getMarshaller()
                         throws JAXBException

Get a Marshaller from the pool, creating one as necessary. If the pool is being used you should use this as follows:

 Marshaller marshaller = jaxbUtils.getMarshaller();
 try {
     // use the Marshaller here
 } finally {
     jaxbUtils.release( marshaller );
 }
 

Returns:

Marshaller

Throws:

JAXBException

getUnmarshaller

public Unmarshaller getUnmarshaller()
                             throws JAXBException

Get an Unmarshaller from the pool, creating one as necessary. If the pool is being used you should use this as follows:

 Unmarshaller unmarshaller = jaxbUtils.getUnmarshaller();
 try {
     // use the Marshaller here
 } finally {
     jaxbUtils.release( unmarshaller );
 }
 

Returns:

Unmarshaller

Throws:

JAXBException

release

@WriteLock
public boolean release(Marshaller marshaller)

Releases a Marshaller back to the pool.

Once this method has been called the caller must not use that instance again as it may be reused by another thread.

Parameters:

marshaller - Marshaller to return to the pool

Returns:

true if the Marshaller is in the pool, false if it has been dropped due to the pool being full

release

@WriteLock
public boolean release(Unmarshaller unmarshaller)

Releases a Unmarshaller back to the pool.

Once this method has been called the caller must not use that instance again as it may be reused by another thread.

Parameters:

unmarshaller - Unmarshaller to return to the pool

Returns:

true if the Unmarshaller is in the pool, false if it has been dropped due to the pool being full

getJAXBElement

public static <T> JAXBElement<T> getJAXBElement(Object o)

Utiity to cast an object to JAXBElement<T>

Type Parameters:

T - Type of the JAXBElement

Parameters:

o - Object to cast

Returns:

JAXBElement<T>

getMarshallerCallback

@ReadLock
public JAXBUtil.MarshallerCallback getMarshallerCallback()

The callback currently used by Marshaller's, null if none

Returns:

setMarshallerCallback

@WriteLock
public void setMarshallerCallback(JAXBUtil.MarshallerCallback marshallerCallback)

Set the MarshallerCallback being used to configure Marshaller's, null if none

Parameters:

marshallerCallback -

getUnmarshallerCallback

@ReadLock
public JAXBUtil.UnmarshallerCallback getUnmarshallerCallback()

The callback currently used by Unmarshaller's, null if none

Returns:

setUnmarshallerCallback

@WriteLock
public void setUnmarshallerCallback(JAXBUtil.UnmarshallerCallback unmarshallerCallback)

Set the UnmarshallerCallback being used to configure Unmarshaller's, null if none

Parameters:

unmarshallerCallback -

marshall

public void marshall(Object object,
                     ContentHandler out)
              throws JAXBException

Marshal an object

Parameters:

object - Object to marshall

out - destination of object

Throws:

JAXBException

Since:

9.2

marshall

public void marshall(Object object,
                     File out)
              throws JAXBException

Marshal an object

Parameters:

object - Object to marshall

out - destination of object

Throws:

JAXBException

Since:

9.2

marshall

public void marshall(Object object,
                     Node out)
              throws JAXBException

Marshal an object

Parameters:

object - Object to marshall

out - destination of object

Throws:

JAXBException

Since:

9.2

marshall

public void marshall(Object object,
                     OutputStream out)
              throws JAXBException

Marshal an object

Parameters:

object - Object to marshall

out - destination of object

Throws:

JAXBException

Since:

9.2

marshall

public void marshall(Object object,
                     Result out)
              throws JAXBException

Marshal an object

Parameters:

object - Object to marshall

out - destination of object

Throws:

JAXBException

Since:

9.2

marshall

public void marshall(Object object,
                     Writer out)
              throws JAXBException

Marshal an object

Parameters:

object - Object to marshall

out - destination of object

Throws:

JAXBException

Since:

9.2

marshall

public void marshall(Object object,
                     XMLEventWriter out)
              throws JAXBException

Marshal an object

Parameters:

object - Object to marshall

out - destination of object

Throws:

JAXBException

Since:

9.2

marshall

public void marshall(Object object,
                     XMLStreamWriter out)
              throws JAXBException

Marshal an object

Parameters:

object - Object to marshall

out - destination of object

Throws:

JAXBException

Since:

9.2

marshall

public String marshall(Object object)
                throws JAXBException

Marshall an object into a String

Parameters:

object - Object to marshall

Returns:

String containing the marshalled object

Throws:

JAXBException

Since:

9.3

unmarshall

public <T> T unmarshall(File in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(InputSource in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(InputStream in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(Node in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(Reader in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(Source in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(URL in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(XMLEventReader in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(XMLStreamReader in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException

unmarshall

public <T> T unmarshall(String in)
             throws JAXBException

Unmarshal from a source

Type Parameters:

T - Type of required Object

Parameters:

in - source

Returns:

Object

Throws:

JAXBException