org.geotoolkit.xml
Class MarshallerPool

Object
  MarshallerPool

@ThreadSafe
public class MarshallerPool
extends Object

Creates and configures Marshaller or Unmarshaller objects for use with Geotk. Users fetch (un)marshallers by calls to the acquireMarshaller() or acquireUnmarshaller() methods.

Configuring marshallers
The (un)marshallers created by this class can optionally by configured with the Geotk-specific properties defined in the XML class, in addition to JAXB standard properties.

Since:

3.00

Version:

3.18

Author:

Martin Desruisseaux (Geomatys), Cédric Briançon (Geomatys)

See Also:

XML

Module:

utility/geotk-xml-base (download)

View source code for this class

TODO:

Need a timeout for disposing marshallers that have been unused for a while.

Field Summary

static String

ROOT_NAMESPACE_KEY The key to be used in the map given to the constructors for specifying the root namespace.

Constructor Summary

MarshallerPool(Class<?>... classesToBeBound)
Creates a new factory for the given class to be bound, with a default empty namespace.

MarshallerPool(Map<String,String> properties, Class<?>... classesToBeBound)
Creates a new factory for the given class to be bound.

MarshallerPool(Map<String,String> properties, String packages)
Creates a new factory for the given packages.

MarshallerPool(String packages)
Creates a new factory for the given packages, with a default empty namespace.

Method Summary

Marshaller	acquireMarshaller() Returns a JAXB marshaller from the pool.
Unmarshaller	acquireUnmarshaller() Returns a JAXB unmarshaller from the pool.
protected void	addAnchor(String label, URI linkage) Adds a label associated to an URN.
protected Marshaller	createMarshaller() Creates an configure a new JAXB marshaller.
protected Unmarshaller	createUnmarshaller() Creates an configure a new JAXB unmarshaller.
static Class<?>[]	defaultClassesToBeBound() Returns the root classes of Geotk objects to be marshalled by default.
void	release(Marshaller marshaller) Declares a marshaller as available for reuse.
void	release(Unmarshaller unmarshaller) Declares a unmarshaller as available for reuse.

Methods inherited from class Object

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

Field Detail

ROOT_NAMESPACE_KEY

public static final String ROOT_NAMESPACE_KEY

The key to be used in the map given to the constructors for specifying the root namespace. An example of value for this key is "http://www.isotc211.org/2005/gmd".

Since:

3.04

See Also:

Constant Field Values

Constructor Detail

MarshallerPool

public MarshallerPool(Class<?>... classesToBeBound)
               throws JAXBException

Creates a new factory for the given class to be bound, with a default empty namespace.

Parameters:

classesToBeBound - The classes to be bound, for example DefaultMetadata.class.

Throws:

JAXBException - If the JAXB context can not be created.

MarshallerPool

public MarshallerPool(Map<String,String> properties,
                      Class<?>... classesToBeBound)
               throws JAXBException

Creates a new factory for the given class to be bound. The keys in the properties map shall be one or many of the constants defined in this class like ROOT_NAMESPACE_KEY.

Parameters:

properties - The set of properties to be given to the pool.

classesToBeBound - The classes to be bound, for example DefaultMetadata.class.

Throws:

JAXBException - If the JAXB context can not be created.

Since:

3.04

MarshallerPool

public MarshallerPool(String packages)
               throws JAXBException

Creates a new factory for the given packages, with a default empty namespace. The separator character for the packages is the colon.

Parameters:

packages - The packages in which JAXB will search for annotated classes to be bound, for example "org.geotoolkit.metadata.iso:org.geotoolkit.metadata.iso.citation".

Throws:

JAXBException - If the JAXB context can not be created.

MarshallerPool

public MarshallerPool(Map<String,String> properties,
                      String packages)
               throws JAXBException

Creates a new factory for the given packages. The separator character for the packages is the colon. The keys in the properties map shall be one or many of the constants defined in this class like ROOT_NAMESPACE_KEY.

Parameters:

properties - The set of properties to be given to the pool.

packages - The packages in which JAXB will search for annotated classes to be bound, for example "org.geotoolkit.metadata.iso:org.geotoolkit.metadata.iso.citation".

Throws:

JAXBException - If the JAXB context can not be created.

Since:

3.04

Method Detail

defaultClassesToBeBound

public static Class<?>[] defaultClassesToBeBound()

Returns the root classes of Geotk objects to be marshalled by default. Those classes can be given as the last argument to the MarshallerPool constructors, in order to bound a default set of classes with JAXBContext.

The list of classes is determined dynamically from the Geotk modules found on the classpath.

Returns:

The default set of classes to be bound to the JAXBContext.

acquireMarshaller

public Marshaller acquireMarshaller()
                             throws JAXBException

Returns a JAXB marshaller from the pool. If there is no marshaller currently available in the pool, then this method will create a new one.

This method should be used as below:

Marshaller marshaller = pool.acquireMarshaller();
marshaller.marchall(...);
pool.release(marshaller);

Note that this is not strictly required to release the marshaller in a finally block. Actually it is safer to let the garbage collector disposes the marshaller if an error occurred while marshalling the object.

Returns:

A marshaller configured for formatting OGC/ISO XML.

Throws:

JAXBException - If an error occurred while creating and configuring a marshaller.

acquireUnmarshaller

public Unmarshaller acquireUnmarshaller()
                                 throws JAXBException

Returns a JAXB unmarshaller from the pool. If there is no unmarshaller currently available in the pool, then this method will create a new one.

This method should be used as below:

Unmarshaller unmarshaller = pool.acquireUnmarshaller();
Unmarshaller.unmarchall(...);
pool.release(unmarshaller);

Note that this is not strictly required to release the unmarshaller in a finally block. Actually it is safer to let the garbage collector disposes the unmarshaller if an error occurred while unmarshalling the object.

Returns:

A unmarshaller configured for parsing OGC/ISO XML.

Throws:

JAXBException - If an error occurred while creating and configuring the unmarshaller.

release

public void release(Marshaller marshaller)

Declares a marshaller as available for reuse. The caller should not use anymore the marshaller after this method call.

Parameters:

marshaller - The marshaller to return to the pool.

release

public void release(Unmarshaller unmarshaller)

Declares a unmarshaller as available for reuse. The caller should not use anymore the unmarshaller after this method call.

Parameters:

unmarshaller - The unmarshaller to return to the pool.

createMarshaller

protected Marshaller createMarshaller()
                               throws JAXBException

Creates an configure a new JAXB marshaller.

Returns:

A new marshaller configured for formatting OGC/ISO XML.

Throws:

JAXBException - If an error occurred while creating and configuring the marshaller.

createUnmarshaller

protected Unmarshaller createUnmarshaller()
                                   throws JAXBException

Creates an configure a new JAXB unmarshaller.

Returns:

A new unmarshaller configured for parsing OGC/ISO XML.

Throws:

JAXBException - If an error occurred while creating and configuring the unmarshaller.

addAnchor

protected void addAnchor(String label,
                         URI linkage)
                  throws IllegalStateException

Adds a label associated to an URN. For some methods expected to return a code as a String object, the code will be completed by the given URN in an AnchorType element.

This method should be invoked from subclasses constructor only. Anchors can be added but can not be removed or modified.

Parameters:

label - The label associated to the URN.

linkage - The URN.

Throws:

IllegalStateException - If a URN is already associated to the given linkage.