MarshallerPool (Apache SIS 1.6 API)
JavaScript is disabled on your browser.
   
Skip navigation links
Overview
Class
Use
Tree
New
Deprecated
Index
Search
Help
org.apache.sis.metadata
org.apache.sis.xml
MarshallerPool
Contents 
Description
Configuring (un)marshallers
Thread safety
Field Summary
Constructor Summary
Method Summary
Field Details
context
Constructor Details
MarshallerPool(Map)
MarshallerPool(JAXBContext, Map)
Method Details
acquireMarshaller()
acquireUnmarshaller()
recycle(Marshaller)
recycle(Unmarshaller)
createMarshaller()
createUnmarshaller()
toString()
Hide sidebar  Show sidebar
Class MarshallerPool
Object
MarshallerPool
public class MarshallerPool
extends Object
Creates and configures Marshaller or Unmarshaller objects for use with SIS.
Users fetch (un)marshallers by calls to the acquire­Marshaller() or
acquire­Unmarshaller() methods, and can restitute the (un)marshaller to the pool
after usage like below:
Copy
Marshaller marshaller = pool.acquireMarshaller();
marshaller.marchall(...);
pool.recycle(marshaller);
Configuring (un)marshallers
The (un)marshallers created by this class can optionally by configured with the SIS-specific
properties defined in the XML class, in addition to JAXB standard properties.
Thread safety
The same Marshaller­Pool instance can be safely used by many threads without synchronization
on the part of the caller. Subclasses should make sure that any overridden methods remain safe to call
from multiple threads.
Since:
0.3
See Also:
XML
JAXB Performance and thread-safety
Field Summary
Fields
Modifier and Type
Field
Description
protected final JAXBContext
context
The JAXB context to use for creating marshaller and unmarshaller.
Constructor Summary
Constructors
Constructor
Description
Marshaller­Pool(JAXBContext context,
Map<String,?> properties)
Creates a new factory using the given JAXB context.
Marshaller­Pool(Map<String,?> properties)
Creates a new factory using the SIS default JAXBContext instance.
Method Summary
All MethodsInstance MethodsConcrete Methods
Modifier and Type
Method
Description
Marshaller
acquire­Marshaller()
Returns a JAXB marshaller from the pool.
Unmarshaller
acquire­Unmarshaller()
Returns a JAXB unmarshaller from the pool.
protected Marshaller
create­Marshaller()
Creates an configures a new JAXB marshaller.
protected Unmarshaller
create­Unmarshaller()
Creates an configures a new JAXB unmarshaller.
void
recycle(Marshaller marshaller)
Declares a marshaller as available for reuse.
void
recycle(Unmarshaller unmarshaller)
Declares a unmarshaller as available for reuse.
String
to­String()
Returns a string representation of this pool for debugging purposes.
Methods inherited from class Object
clone, equals, finalize, get­Class, hash­Code, notify, notify­All, wait, wait, wait
Field Details
context
protected final JAXBContext context
The JAXB context to use for creating marshaller and unmarshaller.
See Also:
create­Marshaller()
create­Unmarshaller()
Constructor Details
MarshallerPool
public MarshallerPool(Map<String,?> properties)
throws JAXBException
Creates a new factory using the SIS default JAXBContext instance.
The properties map is optional. If non-null, then the keys can be XML constants or the
names of any other properties recognized by both Marshaller and Unmarshaller
implementations.
Tip: if the properties for the Marshaller differ from the properties
for the Unmarshaller, then consider overriding the create­Marshaller()
or create­Unmarshaller() methods instead.
Parameters:
properties - the properties to be given to the (un)marshaller, or null if none.
Throws:
JAXBException - if the JAXB context cannot be created.
MarshallerPool
public MarshallerPool(JAXBContext context,
Map<String,?> properties)
throws JAXBException
Creates a new factory using the given JAXB context.
The properties map is optional. If non-null, then the keys can be XML constants or the
names of any other properties recognized by both Marshaller and Unmarshaller
implementations.
Tip: if the properties for the Marshaller differ from the properties
for the Unmarshaller, then consider overriding the create­Marshaller()
or create­Unmarshaller() methods instead.
Parameters:
context - the JAXB context.
properties - the properties to be given to the (un)marshaller, or null if none.
Throws:
JAXBException - if the marshaller pool cannot be created.
Method Details
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 shall be used as below:
Copy
Marshaller marshaller = pool.acquireMarshaller();
marshaller.marchall(...);
pool.recycle(marshaller);
Note that recycle(Marshaller) shall not be invoked in case of exception,
since the marshaller may be in an invalid state.
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 shall be used as below:
Copy
Unmarshaller unmarshaller = pool.acquireUnmarshaller();
Unmarshaller.unmarchall(...);
pool.recycle(unmarshaller);
Note that recycle(Unmarshaller) shall not be invoked in case of exception,
since the unmarshaller may be in an invalid state.
Returns:
a unmarshaller configured for parsing OGC/ISO XML.
Throws:
JAXBException - if an error occurred while creating and configuring the unmarshaller.
recycle
public void recycle(Marshaller marshaller)
Declares a marshaller as available for reuse.
The caller should not use anymore the given marshaller after this method call,
since the marshaller may be re-used by another thread at any time after recycle.
Cautions
Do not invoke this method if the marshaller threw an exception, since the
marshaller may be in an invalid state. In particular, this method should not
be invoked in a finally block.
Do not invoke this method twice for the same marshaller, unless the marshaller
has been obtained by a new call to acquire­Marshaller().
In case of doubt, it is better to not recycle the marshaller at all.
Note that this method does not close any output stream.
Closing the marshaller stream is caller's or JAXB responsibility.
Parameters:
marshaller - the marshaller to return to the pool.
recycle
public void recycle(Unmarshaller unmarshaller)
Declares a unmarshaller as available for reuse.
The caller should not use anymore the given unmarshaller after this method call,
since the unmarshaller may be re-used by another thread at any time after recycle.
Cautions
Do not invoke this method if the unmarshaller threw an exception, since the
unmarshaller may be in an invalid state. In particular, this method should not
be invoked in a finally block.
Do not invoke this method twice for the same unmarshaller, unless the unmarshaller
has been obtained by a new call to acquire­Unmarshaller().
In case of doubt, it is better to not recycle the unmarshaller at all.
Note that this method does not close any input stream.
Closing the unmarshaller stream is caller's or JAXB responsibility.
Parameters:
unmarshaller - the unmarshaller to return to the pool.
createMarshaller
protected Marshaller createMarshaller()
throws JAXBException
Creates an configures a new JAXB marshaller.
This method is invoked only when no existing marshaller is available in the pool.
Subclasses can override this method if they need to change the marshaller configuration.
Returns:
a new marshaller configured for formatting OGC/ISO XML.
Throws:
JAXBException - if an error occurred while creating and configuring the marshaller.
See Also:
context
acquire­Marshaller()
createUnmarshaller
protected Unmarshaller createUnmarshaller()
throws JAXBException
Creates an configures a new JAXB unmarshaller.
This method is invoked only when no existing unmarshaller is available in the pool.
Subclasses can override this method if they need to change the unmarshaller configuration.
Returns:
a new unmarshaller configured for parsing OGC/ISO XML.
Throws:
JAXBException - if an error occurred while creating and configuring the unmarshaller.
See Also:
context
acquire­Unmarshaller()
toString
public String toString()
Returns a string representation of this pool for debugging purposes.
The string representation is unspecified and may change in any future
Apache SIS version.
Overrides:
to­String in class Object
Returns:
a string representation for debugging purposes.
Since:
1.5