Package org.apache.sis.xml

## 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 `acquireMarshaller()` or `acquireUnmarshaller()` methods, and can restitute the (un)marshaller to the pool after usage like below:

  >     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 `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
  See Also:
    `XML`, JAXB Performance and thread-safety

  Defined in the `sis-metadata` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected JAXBContext` | `context` | The JAXB context to use for creating marshaller and unmarshaller.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MarshallerPool​(Map<String,​?> properties)` | Creates a new factory using the SIS default `JAXBContext` instance.
    `MarshallerPool​(JAXBContext context, Map<String,​?> properties)` | Creates a new factory using the given JAXB context.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Marshaller` | `acquireMarshaller()` | Returns a JAXB marshaller from the pool.
    `Unmarshaller` | `acquireUnmarshaller()` | Returns a JAXB unmarshaller from the pool.
    `protected Marshaller` | `createMarshaller()` | Creates an configures a new JAXB marshaller.
    `protected Unmarshaller` | `createUnmarshaller()` | 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.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### context

          protected final JAXBContext context

      The JAXB context to use for creating marshaller and unmarshaller.
      See Also:
        `createMarshaller()`, `createUnmarshaller()`

  - ### Constructor Detail

    - #### 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 can not 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 can not be created.

  - ### Method Detail

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

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

      >     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 `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:
        `context`, `acquireMarshaller()`

    - #### 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`, `acquireUnmarshaller()`