Provide a configuration property for JMS listener container's receive timeout

[ibmmqmet]

The JMS receiveTimeout property spring.jms.template.receive-timeout is not being propagated from a configuration property into the created JMS Listener. That forces the application code to explicitly set it - which is something we find that applications rarely do and the default value is not good for performance in some environments.

This small change copies the external config into the listener.

(I'm told there is now a corporate CLA in place to allow this to be accepted.)

[pivotal-issuemaster]

@ibmmqmet Please sign the Contributor License Agreement!

Click here to manually synchronize the status of this Pull Request.

See the FAQ for frequently asked questions.

[wilkinsona]

Thanks for the proposal.

Given that we have separate properties for the template and the listener, users may be surprised that a spring.jms.template.* property has affected the listener's configuration. I think we should consider a couple of alternatives:

1. Introduce a separate spring.jms.listener.receive-timeout property
2. Deprecate spring.jms.template.receive-timeout and add spring.jms.receive-timeout that configures the receive timeout on both the template and the listener

1 provides more flexibility whereas 2 makes it easier to keep the two in sync. I don't have a strong opinion about which is the better option, although I am leaning towards 1. What do you think, @ibmmqmet. @snicoll will probably have an opinion too once he's back in the office.

[ibmmqmet]

The template seemed to be being used for quite a few other properties, but it's not clear what the real distinction is - it does have that receiveTimeout property inside the JMSProperties.Template class, which is not used elsewhere that I could see - so doing it this way made sense. What's the point of having the property in the class otherwise. And it is configurable into the template, just not propagated. Maybe there's a philosophy around what belongs in a "template" and what belongs in the a "real" created object.

I don't know why you'd treat a JMS Listener differently than a Destination/Connection for default properties, but if there's a preferred way of doing it, then I don't really care.

Of your two options (1) is probably easiest to understand.

[wilkinsona]

The template seemed to be being used for quite a few other properties, but it's not clear what the real distinction is - it does have that receiveTimeout property inside the JMSProperties.Template class, which is not used elsewhere that I could see - so doing it this way made sense. What's the point of having the property in the class otherwise.

spring.jms.template properties are used to configure the JmsTemplate bean that's created by JmsAutoConfiguration:

spring-boot/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/jms/JmsAutoConfiguration.java

Lines 85 to 96 in aef92b9

	private void mapTemplateProperties(Template properties, JmsTemplate template) {
	PropertyMapper map = PropertyMapper.get();
	map.from(properties::getDefaultDestination).whenNonNull().to(template::setDefaultDestinationName);
	map.from(properties::getDeliveryDelay).whenNonNull().as(Duration::toMillis).to(template::setDeliveryDelay);
	map.from(properties::determineQosEnabled).to(template::setExplicitQosEnabled);
	map.from(properties::getDeliveryMode).whenNonNull().as(DeliveryMode::getValue)
	.to(template::setDeliveryMode);
	map.from(properties::getPriority).whenNonNull().to(template::setPriority);
	map.from(properties::getTimeToLive).whenNonNull().as(Duration::toMillis).to(template::setTimeToLive);
	map.from(properties::getReceiveTimeout).whenNonNull().as(Duration::toMillis)
	.to(template::setReceiveTimeout);
	}

And it is configurable into the template, just not propagated. Maybe there's a philosophy around what belongs in a "template" and what belongs in the a "real" created object.

It sounds like you weren't aware of Spring Framework's JmsTemplate which simplifies code that's using JMS. That's what the template in the property name is referring to. The JmsTemplate that's created by the auto-configuration and configured using the spring.jms.template.* properties is a real object and is exposed to applications as a bean. On the other hand, the spring.jms.listener properties are using to configure the message listener container that's created by the JMS auto-configuration.

In short:

• the receive timeout on the auto-configured JmsTemplate controls the timeout for receiving messages when application code is using JmsTemplate to work with JMS
• the receive timeout on the auto-configured message listener container controls the timeout for the container receiving messages it then passes to any beans that are listening for JMS messages.

In light of the above, is your preference still for the first of the two options that I proposed?

[wilkinsona]

(I'm told there is now a corporate CLA in place to allow this to be accepted.)

To associate your GitHub account with IBM's corporate CLA it needs to be a public member of the IBM or OpenLiberty GitHub organisations. There is a little more about this in the CLA tool's FAQ.

[ibmmqmet]

Yes, a separate property as in (1) would work.

[wilkinsona]

Would you like to update your proposal to that effect?

[wilkinsona]

@ibmmqmet Thanks for the updates. Can you please make the necessary changes to have your GitHub account associated with IBM's CLA?

[snicoll]

Thanks for the PR. Would you mind updating JmsAutoConfigurationTests#testJmsListenerContainerFactoryWithCustomSettings to validate the mapping of the receive timeout?

[snicoll]

The current default is 1 second so it would be nice to have that documented and tested.

[snicoll]

0 and -1 have special meaning so it would be nice to have those documented here. See the javadoc of org.springframework.jms.listener.AbstractPollingMessageListenerContainer#setReceiveTimeout

[snicoll]

@ibmmqmet could we please get some feedback on this?

[ibmmqmet]

Sorry for the delay - other projects and being away from my desk got in the way...

I've added the requested comments. But can't add the functions to the test file because the org.springframework.jms.listener.AbstractPollingMessageListenerContainer#getReceiveTimeout() method is marked "protected" (for no obvious reason) so can't be accessed directly.

[wilkinsona]

Thanks for the updates.

method is marked "protected" (for no obvious reason) so can't be accessed directly.

It is marked protected to limit the surface area of the public API.

When we want to test the value of something that isn't publicly accessible we typically use reflection. AssertJ's hasFieldOrPropertyWithValue provides a way of doing that. There are some examples of its usage in several tests in JmsAutoConfigurationTests. Here's one:

spring-boot/spring-boot-project/spring-boot-autoconfigure/src/test/java/org/springframework/boot/autoconfigure/jms/JmsAutoConfigurationTests.java

Lines 168 to 169 in c44a6de

	assertThat(container).hasFieldOrPropertyWithValue("transactionManager",
	context.getBean(JtaTransactionManager.class));

Could you please use this approach to test the new receive timeout property?

In addition to the missing tests, unfortunately we also can't merge this due to the failing CLA check. Our current understanding is that your membership of the IBM or OpenLiberty GitHub organisations needs to be made public.

[wilkinsona]

Thanks for the updates. Any news on the CLA?

Unfortunately, if this drags on too much longer we'll have to close the PR as the overhead of monitoring it is starting to outweigh the benefit of the changes.

[ibmmqmet]

CLA seems to be signed now

[pivotal-issuemaster]

@ibmmqmet Thank you for signing the Contributor License Agreement!

[wilkinsona]

Thanks very much for making your first contribution to Spring Boot, @ibmmqmet. I'm pleased that we managed to get there in the end.