Package org.apache.sis.xml
Class MarshallerPool
Object
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:
 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 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
- See Also:
Defined in the sis-metadata module
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected final JAXBContextThe JAXB context to use for creating marshaller and unmarshaller.
- 
Constructor SummaryConstructorsConstructorDescriptionMarshallerPool(Map<String, ?> properties) Creates a new factory using the SIS defaultJAXBContextinstance.MarshallerPool(JAXBContext context, Map<String, ?> properties) Creates a new factory using the given JAXB context.
- 
Method SummaryModifier and TypeMethodDescriptionMarshallerReturns a JAXB marshaller from the pool.UnmarshallerReturns a JAXB unmarshaller from the pool.protected MarshallerCreates an configures a new JAXB marshaller.protected UnmarshallerCreates an configures a new JAXB unmarshaller.voidrecycle(Marshaller marshaller) Declares a marshaller as available for reuse.voidrecycle(Unmarshaller unmarshaller) Declares a unmarshaller as available for reuse.
- 
Field Details- 
contextprotected final JAXBContext contextThe JAXB context to use for creating marshaller and unmarshaller.- See Also:
 
 
- 
- 
Constructor Details- 
MarshallerPoolCreates a new factory using the SIS defaultJAXBContextinstance. Thepropertiesmap is optional. If non-null, then the keys can beXMLconstants or the names of any other properties recognized by bothMarshallerandUnmarshallerimplementations.Tip: if the properties for the Marshallerdiffer from the properties for theUnmarshaller, then consider overriding thecreateMarshaller()orcreateUnmarshaller()methods instead.- Parameters:
- properties- the properties to be given to the (un)marshaller, or- nullif none.
- Throws:
- JAXBException- if the JAXB context cannot be created.
 
- 
MarshallerPoolCreates a new factory using the given JAXB context. Thepropertiesmap is optional. If non-null, then the keys can beXMLconstants or the names of any other properties recognized by bothMarshallerandUnmarshallerimplementations.Tip: if the properties for the Marshallerdiffer 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, or- nullif none.
- Throws:
- JAXBException- if the marshaller pool cannot be created.
 
 
- 
- 
Method Details- 
acquireMarshallerpublic Marshaller acquireMarshaller() throws JAXBExceptionReturns 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 thatMarshaller marshaller = pool.acquireMarshaller(); marshaller.marchall(...); pool.recycle(marshaller); 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.
 
- 
acquireUnmarshallerpublic Unmarshaller acquireUnmarshaller() throws JAXBExceptionReturns 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 thatUnmarshaller unmarshaller = pool.acquireUnmarshaller(); Unmarshaller.unmarchall(...); pool.recycle(unmarshaller); 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.
 
- 
recyclepublic 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 finallyblock.
- 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 
- 
recyclepublic 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 finallyblock.
- 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 
- 
createMarshallerprotected Marshaller createMarshaller() throws JAXBExceptionCreates 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:
 
- 
createUnmarshallerprotected Unmarshaller createUnmarshaller() throws JAXBExceptionCreates 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:
 
 
-