Package org.apache.sis.xml

Class MarshallerPool

java.lang.Object
org.apache.sis.xml.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 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 the XML class, in addition to JAXB standard properties.

Thread safety

The same MarshallerPool 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 Details

    • TIMEOUT

      private static final long TIMEOUT
      Amount 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

      protected final JAXBContext context
      The JAXB context to use for creating marshaller and unmarshaller.
      See Also:

    • implementation

      private final Implementation implementation
      INTERNAL if the JAXB implementation is the one bundled in the JDK, ENDORSED if the TAXB implementation is the endorsed JAXB (Glassfish), or null if unknown.

    • replacements

      private final ServiceLoader<AdapterReplacement> replacements
      The provider of AdapterReplacement instances. Every usage of this service loader must be synchronized.
      Implementation note: Each MarshallerPool has its own service loader instance rather than using a system-wide instance because the ClassLoader 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

      private final PooledTemplate template
      The PooledTemplate to use for initializing recycled (un)marshaller.

    • marshallers

      private final Deque<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 the Deque.poll() method and, after use, given back to the pool using the Deque.push(Object) method.

      This queue must be a thread-safe implementation, since it will not be invoked in synchronized block.

      See Also:

    • unmarshallers

      private final Deque<Unmarshaller> 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 the Deque.poll() method and, after use, given back to the pool using the Deque.push(Object) method.

      This queue must be a thread-safe implementation, since it will not be invoked in synchronized block.

      See Also:

    • isRemovalScheduled

      private final AtomicBoolean isRemovalScheduled
      true if a task has been scheduled for removing expired (un)marshallers, or false if no removal task is currently scheduled.
      See Also:

  • 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 createMarshaller() or createUnmarshaller() 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 createMarshaller() or createUnmarshaller() 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

    • recycle

      private <T> void recycle(Deque<T> queue, T marshaller)
      Marks the given marshaller or unmarshaller available for further reuse. This method:
      • Resets the (un)marshaller to its initial state.
      • Pushes the (un)marshaller in the given queue.
      • Registers a delayed task for disposing expired (un)marshallers after the timeout.

    • 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 the TIMEOUT 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 by scheduleRemoval() 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

      private static <T> boolean removeExpired(Deque<T> queue, long now)
      Removes expired (un)marshallers from the given queue.
      Type Parameters:
      T - either Marshaller or Unmarshaller type.
      Parameters:
      queue - the queue from which to remove expired (un)marshallers.
      now - current value of System.nanoTime().
      Returns:
      true if the queue became empty as a result of this method call.

    • 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:

      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:

      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.

    • acquireUnmarshaller

      final Unmarshaller acquireUnmarshaller(Map<String,?> properties) throws JAXBException
      Acquires a unmarshaller and set the properties to the given value, if non-null.
      Throws:
      JAXBException

    • 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 acquireMarshaller(). 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 acquireUnmarshaller(). 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:

    • 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: