Package org.apache.sis.xml
Class MarshallerPool
java.lang.Object
org.apache.sis.xml.MarshallerPool
Creates and configures
Marshaller
or Unmarshaller
objects for use with SIS.
Users fetch (un)marshallers by calls to the acquireMarshaller()
or
acquireUnmarshaller()
methods, and can restitute the (un)marshaller to the pool
after usage like below:
Configuring (un)marshallers
The (un)marshallers created by this class can optionally by configured with the SIS-specific properties defined in theXML
class, in addition to JAXB standard properties.
Thread safety
The sameMarshallerPool
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
- Version:
- 1.1
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final JAXBContext
The JAXB context to use for creating marshaller and unmarshaller.private final Implementation
INTERNAL
if the JAXB implementation is the one bundled in the JDK,ENDORSED
if the TAXB implementation is the endorsed JAXB (Glassfish), ornull
if unknown.private final AtomicBoolean
true
if a task has been scheduled for removing expired (un)marshallers, orfalse
if no removal task is currently scheduled.private final Deque
<Marshaller> The pool of marshaller.private final ServiceLoader
<AdapterReplacement> The provider ofAdapterReplacement
instances.private final PooledTemplate
ThePooledTemplate
to use for initializing recycled (un)marshaller.private static final long
Amount of nanoseconds to wait before to remove unused (un)marshallers.private final Deque
<Unmarshaller> The pool of unmarshaller. -
Constructor Summary
ConstructorsConstructorDescriptionMarshallerPool
(Map<String, ?> properties) Creates a new factory using the SIS defaultJAXBContext
instance.MarshallerPool
(JAXBContext context, Map<String, ?> properties) Creates a new factory using the given JAXB context. -
Method Summary
Modifier and TypeMethodDescriptionReturns a JAXB marshaller from the pool.Returns a JAXB unmarshaller from the pool.(package private) final Unmarshaller
acquireUnmarshaller
(Map<String, ?> properties) Acquires a unmarshaller and set the properties to the given value, if non-null.protected Marshaller
Creates an configures a new JAXB marshaller.protected Unmarshaller
Creates an configures a new JAXB unmarshaller.private <T> void
Marks the given marshaller or unmarshaller available for further reuse.void
recycle
(Marshaller marshaller) Declares a marshaller as available for reuse.void
recycle
(Unmarshaller unmarshaller) Declares a unmarshaller as available for reuse.(package private) final void
Invoked from the task scheduled byscheduleRemoval()
for removing expired (un)marshallers.private static <T> boolean
removeExpired
(Deque<T> queue, long now) Removes expired (un)marshallers from the given queue.private void
Schedule a new task for removing expired (un)marshallers if no such task is currently registered.
-
Field Details
-
TIMEOUT
private static final long TIMEOUTAmount of nanoseconds to wait before to remove unused (un)marshallers. This is a very rough value: actual timeout will not be shorter, but may be twice longer.- See Also:
-
context
The JAXB context to use for creating marshaller and unmarshaller.- See Also:
-
implementation
INTERNAL
if the JAXB implementation is the one bundled in the JDK,ENDORSED
if the TAXB implementation is the endorsed JAXB (Glassfish), ornull
if unknown. -
replacements
The provider ofAdapterReplacement
instances. Every usage of this service loader must be synchronized.Implementation note: EachMarshallerPool
has its own service loader instance rather than using a system-wide instance because theClassLoader
used by the service loader is the context class loader, which depends on the thread that created the pool. So two pools in two different applications could have two different set of replacements. -
template
ThePooledTemplate
to use for initializing recycled (un)marshaller. -
marshallers
The pool of marshaller. This pool is initially empty and will be filled with elements as needed. Marshallers (if any) shall be fetched using theDeque.poll()
method and, after use, given back to the pool using theDeque.push(Object)
method.This queue must be a thread-safe implementation, since it will not be invoked in synchronized block.
- See Also:
-
unmarshallers
The pool of unmarshaller. This pool is initially empty and will be filled with elements as needed. Unmarshallers (if any) shall be fetched using theDeque.poll()
method and, after use, given back to the pool using theDeque.push(Object)
method.This queue must be a thread-safe implementation, since it will not be invoked in synchronized block.
- See Also:
-
isRemovalScheduled
true
if a task has been scheduled for removing expired (un)marshallers, orfalse
if no removal task is currently scheduled.- See Also:
-
-
Constructor Details
-
MarshallerPool
Creates a new factory using the SIS defaultJAXBContext
instance. Theproperties
map is optional. If non-null, then the keys can beXML
constants or the names of any other properties recognized by bothMarshaller
andUnmarshaller
implementations.Tip: if the properties for the
Marshaller
differ from the properties for theUnmarshaller
, then consider overriding thecreateMarshaller()
orcreateUnmarshaller()
methods instead.- Parameters:
properties
- the properties to be given to the (un)marshaller, ornull
if none.- Throws:
JAXBException
- if the JAXB context cannot be created.
-
MarshallerPool
Creates a new factory using the given JAXB context. Theproperties
map is optional. If non-null, then the keys can beXML
constants or the names of any other properties recognized by bothMarshaller
andUnmarshaller
implementations.Tip: if the properties for the
Marshaller
differ from the properties for theUnmarshaller
, then consider overriding thecreateMarshaller()
orcreateUnmarshaller()
methods instead.- Parameters:
context
- the JAXB context.properties
- the properties to be given to the (un)marshaller, ornull
if none.- Throws:
JAXBException
- if the marshaller pool cannot be created.
-
-
Method Details
-
recycle
-
scheduleRemoval
private void scheduleRemoval()Schedule a new task for removing expired (un)marshallers if no such task is currently registered. If a task is already registered, then this method does nothing. Note that this task will actually wait for a longer time than theTIMEOUT
value before to execute, in order to increase the chances to process many (un)marshallers at once. -
removeExpired
final void removeExpired()Invoked from the task scheduled byscheduleRemoval()
for removing expired (un)marshallers. If some (un)marshallers remain after execution of this task, then this method will reschedule a new task for checking again later. -
removeExpired
Removes expired (un)marshallers from the given queue.- Type Parameters:
T
- eitherMarshaller
orUnmarshaller
type.- Parameters:
queue
- the queue from which to remove expired (un)marshallers.now
- current value ofSystem.nanoTime()
.- Returns:
true
if the queue became empty as a result of this method call.
-
acquireMarshaller
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:
Note thatrecycle(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
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:
Note thatrecycle(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.
-
acquireUnmarshaller
Acquires a unmarshaller and set the properties to the given value, if non-null.- Throws:
JAXBException
-
recycle
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
acquireMarshaller()
. In case of doubt, it is better to not recycle the marshaller at all.
- Parameters:
marshaller
- the marshaller to return to the pool.
- 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
-
recycle
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
acquireUnmarshaller()
. In case of doubt, it is better to not recycle the unmarshaller at all.
- Parameters:
unmarshaller
- the unmarshaller to return to the pool.
- 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
-
createMarshaller
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:
-
createUnmarshaller
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:
-