spring-projects/spring-framework

spring-jms

Active contributors: Juergen Hoeller, Sam Brannen

Purpose

spring-jms integrates Spring with Jakarta Messaging (JMS) — both as a sender (JmsTemplate) and as a listener container (asynchronous message consumption). It plugs into Spring's transaction manager and MessageConverter infrastructure, giving applications a uniform messaging model regardless of broker.

Directory layout

spring-jms/
└── src/main/java/org/springframework/jms/
    ├── JmsException.java
    ├── annotation/                                # @JmsListener, @EnableJms
    ├── config/                                    # XML namespace + listener container factory
    ├── connection/                                # CachingConnectionFactory, JmsTransactionManager
    ├── core/                                      # JmsTemplate, JmsOperations, MessagePostProcessor
    ├── listener/                                  # listener container infrastructure
    │   ├── adapter/                               # MessageListenerAdapter
    │   ├── DefaultMessageListenerContainer.java
    │   └── …
    └── support/
        ├── converter/                             # MessageConverter (JSON, XML, Marshalling)
        ├── destination/                           # JndiDestinationResolver, …
        └── …

Key abstractions

Type	File	Role
`JmsTemplate`	`spring-jms/src/main/java/org/springframework/jms/core/JmsTemplate.java`	Synchronous send / receive
`JmsMessagingTemplate`	`spring-jms/src/main/java/org/springframework/jms/core/JmsMessagingTemplate.java`	Bridge to `spring-messaging` types
`DefaultMessageListenerContainer`	`spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java`	Pull-based listener container
`@JmsListener`	`spring-jms/src/main/java/org/springframework/jms/annotation/JmsListener.java`	Annotation that registers a method as a JMS listener
`JmsTransactionManager`	`spring-jms/src/main/java/org/springframework/jms/connection/JmsTransactionManager.java`	`PlatformTransactionManager` for JMS sessions
`MessageConverter`	`spring-jms/src/main/java/org/springframework/jms/support/converter/MessageConverter.java`	Object ↔ JMS `Message`
`CachingConnectionFactory`	`spring-jms/src/main/java/org/springframework/jms/connection/CachingConnectionFactory.java`	Pools JMS connections / sessions / producers

How it works

Sending

sequenceDiagram
    participant App
    participant JT as JmsTemplate
    participant CF as ConnectionFactory
    participant Conn as Connection
    participant Sess as Session
    App->>JT: convertAndSend("queue.work", payload)
    JT->>CF: create connection
    CF-->>JT: Connection (cached)
    JT->>Conn: create session
    Conn-->>JT: Session
    JT->>JT: convert payload via MessageConverter
    JT->>Sess: send Message
    JT->>Sess: close (return to cache)

CachingConnectionFactory is essential in production — it pools the otherwise-expensive connection/session creation.

Listening

graph LR
    DMLC[DefaultMessageListenerContainer] -->|"receive"| Broker[JMS broker]
    Broker -->|"Message"| DMLC
    DMLC -->|"convert + dispatch"| Adapter[MessageListenerAdapter]
    Adapter -->|"reflective invoke"| Method["@JmsListener method"]

DefaultMessageListenerContainer runs N consumer threads that block on MessageConsumer.receive, dispatching to the listener. It's the de-facto choice unless you specifically need the older Spring async resource adapter.

@JmsListener methods are discovered by JmsListenerAnnotationBeanPostProcessor and registered with JmsListenerEndpointRegistry, which manages the lifecycle of all listener containers.

Transactional listeners

A listener method annotated @Transactional participates in a JMS transaction that brackets the message dispatch. Either the message is acknowledged and the database transaction commits, or both roll back together.

Integration points

Depends on spring-beans, spring-core, spring-messaging, spring-tx.
Optional spring-context-support for richer scheduling.
JMS provider independent — works with ActiveMQ, Artemis, IBM MQ, Solace, etc.

Entry points for modification

Custom listener container — Extend AbstractMessageListenerContainer for unusual concurrency models.
Custom converter — Implement MessageConverter for a payload format your broker uses (in addition to the built-in MappingJackson2MessageConverter and MarshallingMessageConverter).
Custom destination resolution — Implement DestinationResolver.