Package com.apama.correlator.jms.config.api.mapper

Class SimpleAbstractJmsMessageMapper

  • All Implemented Interfaces:
    JmsReceiverMapper, JmsReceiverMapperFactory, JmsSenderMapper, JmsSenderMapperFactory
    public abstract class SimpleAbstractJmsMessageMapper
extends java.lang.Object
implements JmsSenderMapper, JmsSenderMapperFactory, JmsReceiverMapper, JmsReceiverMapperFactory
    Abstract helper class for implementing simple mappings between JMS messages and Apama events, with optional support for delegation to another mapper.

    This class is the recommended way to implement a simple stateless bi-directional mapper, with trivial implementations of methods that most implementors will not need to be concerned with. Most implementations will only need to override the mapApamaToJmsMessage(JmsSenderMapperContext, MappableApamaEvent) and mapJmsToApamaMessage(JmsReceiverMapperContext, javax.jms.Message) methods, usually with EventType fields for each of the Apama event types the mapper can handle.

    This class also provides optional senderMapperDelegate/receiverMapperDelegate bean properties that identify another mapper to use for any messages that this mapper does not handle. The associated methods are used for the XML configuration but should not be called by subclasses.

    For more advanced cases, do not use this class but instead implement the factory interfaces directly, with separate classes for the sender and receiver mappers. This is particularly important when the mapping operations are stateful, for example if they rely on a cache which should not be shared across all the mapper instances created by the factory to avoid thread-safety concerns or costly and unnecessary synchronization.

    • Constructor Detail

      • SimpleAbstractJmsMessageMapper

        public SimpleAbstractJmsMessageMapper()

    • Method Detail

      • init

        public void init()
          throws java.lang.Exception
        Description copied from interface: JmsSenderMapperFactory
        Initialization method to be called after all configuration properties have been assigned, to initialize this factory and validate the configuration.

        If the configuration is invalid in any way then an exception should be thrown from this method. This method must be idempotent, as it may be called more than once during initialization (although always on the configuration loading thread, so there is no need for synchronization here).

        Specified by:
        init in interface JmsReceiverMapperFactory
        Specified by:
        init in interface JmsSenderMapperFactory
        Throws:
        java.lang.Exception

      • destroy

        public final void destroy()
        Provides a trivial no-op implementation of this method. Cannot be overridden by subclasses.
        Specified by:
        destroy in interface JmsReceiverMapper
        Specified by:
        destroy in interface JmsSenderMapper

      • mapApamaToJmsMessage

        public abstract JmsSenderMessageHolder mapApamaToJmsMessage​(JmsSenderMapperContext context,
                                                            MappableApamaEvent event)
                                                     throws java.lang.Exception
        Description copied from interface: JmsSenderMapper
        Converts an Apama event string and (possibly null) unique ids for duplicate elimination to a JmsSenderMessageHolder object containing the message and message sending parameters.

        Threading: a separate instance of the mapper interface will be created for each thread, so implementations of this method are not required to be thread-safe, and should in fact be careful to avoid synchronizing on data structures shared with other mapper instance to ensure mapping can be performed in parallel. Implementors may use read-only (unsynchronized) shared configuration state, including Apama EventType objects, but caches and other read-write data structures should be stored in instances of this object to ensure optimum performance and scalability.

        Specified by:
        mapApamaToJmsMessage in interface JmsSenderMapper
        Parameters:
        context - Should never be null
        event - Should never be null
        Returns:
        A JmsSenderMessageHolder containing the JMS Message, and send arguments such as its destination. If the event cannot be handled by this mapper, return null to allow the event to be discarded, or mapping to be delegated to another mapper if configured (but never return null in the event of an error - failure to handle a message this mapper is responsible for should always result in throwing an exception).
        Throws:
        java.lang.Exception

      • mapJmsToApamaMessage

        public abstract MappableApamaEvent mapJmsToApamaMessage​(JmsReceiverMapperContext context,
                                                        javax.jms.Message message)
                                                 throws java.lang.Exception,
                                                        javax.jms.JMSException
        Description copied from interface: JmsReceiverMapper
        Converts a JMS message object to an Apama event string (and unique message id for dup elimination, if available).

        Threading: a separate instance of the mapper interface will be created for each thread, so implementations of this method are not required to be thread-safe, and should in fact be careful to avoid synchronizing on data structures shared with other mapper instance to ensure mapping can be performed in parallel. Implementors may use read-only (unsynchronized) shared configuration state, including Apama EventType objects, but caches and other read-write data structures should be stored in instances of this object to ensure optimum performance and scalability.

        Specified by:
        mapJmsToApamaMessage in interface JmsReceiverMapper
        Parameters:
        context - Never null.
        message - Never null.
        Returns:
        A MappableApamaEvent. If the message cannot be handled by this mapper, return null to allow the message to be discarded, or mapping to be delegated to another mapper if configured (but never return null in the event of an error - failure to handle a message this mapper is responsible for should always result in throwing an exception).
        Throws:
        java.lang.Exception - If the mapping could not be performed for some reason.
        javax.jms.JMSException

      • createJmsSenderMapper

        public final JmsSenderMapper createJmsSenderMapper()
        Provides a trivial implementation of this factory method. Cannot be overridden by subclasses.
        Specified by:
        createJmsSenderMapper in interface JmsSenderMapperFactory
        Returns:
        A mapper instance that is guaranteed to be used only by a single thread.

      • createJmsReceiverMapper

        public final JmsReceiverMapper createJmsReceiverMapper()
        Provides a trivial implementation of this factory method. Cannot be overridden by subclasses.
        Specified by:
        createJmsReceiverMapper in interface JmsReceiverMapperFactory
        Returns:
        A mapper instance that is guaranteed to be used only by a single thread.

      • setSenderMapperDelegate

        public final void setSenderMapperDelegate​(JmsSenderMapperFactory factory)
        The optional senderMapperDelegate bean property specifies the factory of a sender mapper which should be used for any events not handled directly by this mapper.

        The delegate mapper factory will typically be specified by setting the ref="springidofmapper" attribute in the XML Spring configuration.

        Parameters:
        factory - May be null (the default) if no delegation is required.

      • setReceiverMapperDelegate

        public final void setReceiverMapperDelegate​(JmsReceiverMapperFactory factory)
        The optional receiverMapperDelegate bean property specifies the factory of a receiver mapper which should be used for any messages not handled directly by this mapper.

        The delegate mapper factory will typically be specified by setting the ref="springidofmapper" attribute in the XML Spring configuration.

        Parameters:
        factory - May be null (the default) if no delegation is required.