root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

Polishing Javadoc and suppressing warnings.

This commit is contained in:
Sam Brannen 2011-08-14 17:02:45 +00:00
parent d746dcaa63
commit a94e3785b8
2 changed files with 60 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
org.springframework.jms/src/main/java/org/springframework/jms/listener/AbstractJmsListeningContainer.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright 2002-2010 the original author or authors. * Copyright 2002-2011 the original author or authors.
* *
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
@ -84,10 +84,10 @@ public abstract class AbstractJmsListeningContainer extends JmsDestinationAccess
/** /**
* Specify the JMS client id for a shared Connection created and used * Specify the JMS client ID for a shared Connection created and used
* by this container. * by this container.
* <p>Note that client ids need to be unique among all active Connections * <p>Note that client IDs need to be unique among all active Connections
* of the underlying JMS provider. Furthermore, a client id can only be * of the underlying JMS provider. Furthermore, a client ID can only be
* assigned if the original ConnectionFactory hasn't already assigned one. * assigned if the original ConnectionFactory hasn't already assigned one.
* @see javax.jms.Connection#setClientID * @see javax.jms.Connection#setClientID
* @see #setConnectionFactory * @see #setConnectionFactory
@ -530,7 +530,7 @@ public abstract class AbstractJmsListeningContainer extends JmsDestinationAccess
protected void resumePausedTasks() { protected void resumePausedTasks() {
synchronized (this.lifecycleMonitor) { synchronized (this.lifecycleMonitor) {
if (!this.pausedTasks.isEmpty()) { if (!this.pausedTasks.isEmpty()) {
for (Iterator it = this.pausedTasks.iterator(); it.hasNext();) { for (Iterator<?> it = this.pausedTasks.iterator(); it.hasNext();) {
Object task = it.next(); Object task = it.next();
try { try {
doRescheduleTask(task); doRescheduleTask(task);
@ -623,6 +623,7 @@ public abstract class AbstractJmsListeningContainer extends JmsDestinationAccess
* shared JMS Connection failed. This is indicating to invokers that they need * shared JMS Connection failed. This is indicating to invokers that they need
* to establish the shared Connection themselves on first access. * to establish the shared Connection themselves on first access.
*/ */
@SuppressWarnings("serial")
public static class SharedConnectionNotInitializedException extends RuntimeException { public static class SharedConnectionNotInitializedException extends RuntimeException {
/** /**

107
org.springframework.jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright 2002-2010 the original author or authors. * Copyright 2002-2011 the original author or authors.
* *
* Licensed under the Apache License, Version 2.0 (the "License"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. * you may not use this file except in compliance with the License.
@ -37,7 +37,7 @@ import org.springframework.util.Assert;
import org.springframework.util.ClassUtils; import org.springframework.util.ClassUtils;
/** /**
* Message listener container variant that uses plain JMS client API, specifically * Message listener container variant that uses plain JMS client APIs, specifically
* a loop of <code>MessageConsumer.receive()</code> calls that also allow for * a loop of <code>MessageConsumer.receive()</code> calls that also allow for
* transactional reception of messages (registering them with XA transactions). * transactional reception of messages (registering them with XA transactions).
* Designed to work in a native JMS environment as well as in a J2EE environment, * Designed to work in a native JMS environment as well as in a J2EE environment,
@ -45,41 +45,41 @@ import org.springframework.util.ClassUtils;
* *
* <p>This is a simple but nevertheless powerful form of message listener container. * <p>This is a simple but nevertheless powerful form of message listener container.
* On startup, it obtains a fixed number of JMS Sessions to invoke the listener, * On startup, it obtains a fixed number of JMS Sessions to invoke the listener,
* and optionally allows for dynamic adaptation at runtime (up until a maximum number). * and optionally allows for dynamic adaptation at runtime (up to a maximum number).
* Like {@link SimpleMessageListenerContainer}, its main advantage is its low level * Like {@link SimpleMessageListenerContainer}, its main advantage is its low level
* of runtime complexity, in particular the minimal requirements on the JMS provider: * of runtime complexity, in particular the minimal requirements on the JMS provider:
* Not even the JMS ServerSessionPool facility is required. Beyond that, it is * not even the JMS {@code ServerSessionPool} facility is required. Beyond that, it is
* fully self-recovering in case of the broker being temporarily unavailable, * fully self-recovering in case the broker is temporarily unavailable, and allows
* and allows for stops/restarts as well as runtime changes to its configuration. * for stops/restarts as well as runtime changes to its configuration.
* *
* <p>Actual MessageListener execution happens in asynchronous work units which are * <p>Actual {@code MessageListener} execution happens in asynchronous work units which are
* created through Spring's {@link org.springframework.core.task.TaskExecutor} * created through Spring's {@link org.springframework.core.task.TaskExecutor TaskExecutor}
* abstraction. By default, the specified number of invoker tasks will be created * abstraction. By default, the specified number of invoker tasks will be created
* on startup, according to the {@link #setConcurrentConsumers "concurrentConsumers"} * on startup, according to the {@link #setConcurrentConsumers "concurrentConsumers"}
* setting. Specify an alternative TaskExecutor to integrate with an existing * setting. Specify an alternative {@code TaskExecutor} to integrate with an existing
* thread pool facility (such as a J2EE server's), for example using a * thread pool facility (such as a J2EE server's), for example using a
* {@link org.springframework.scheduling.commonj.WorkManagerTaskExecutor CommonJ WorkManager}. * {@link org.springframework.scheduling.commonj.WorkManagerTaskExecutor CommonJ WorkManager}.
* With a native JMS setup, each of those listener threads is going to use a * With a native JMS setup, each of those listener threads is going to use a
* cached JMS Session and MessageConsumer (only refreshed in case of failure), * cached JMS {@code Session} and {@code MessageConsumer} (only refreshed in case
* using the JMS provider's resources as efficiently as possible. * of failure), using the JMS provider's resources as efficiently as possible.
* *
* <p>Message reception and listener execution can automatically be wrapped * <p>Message reception and listener execution can automatically be wrapped
* in transactions through passing a Spring * in transactions by passing a Spring
* {@link org.springframework.transaction.PlatformTransactionManager} into the * {@link org.springframework.transaction.PlatformTransactionManager} into the
* {@link #setTransactionManager "transactionManager"} property. This will usually * {@link #setTransactionManager "transactionManager"} property. This will usually
* be a {@link org.springframework.transaction.jta.JtaTransactionManager} in a * be a {@link org.springframework.transaction.jta.JtaTransactionManager} in a
* J2EE enviroment, in combination with a JTA-aware JMS ConnectionFactory obtained * J2EE environment, in combination with a JTA-aware JMS {@code ConnectionFactory}
* from JNDI (check your J2EE server's documentation). Note that this listener * obtained from JNDI (check your J2EE server's documentation). Note that this
* container will automatically reobtain all JMS handles for each transaction * listener container will automatically reobtain all JMS handles for each transaction
* in case of an external transaction manager specified, for compatibility with * in case an external transaction manager is specified, for compatibility with
* all J2EE servers (in particular JBoss). This non-caching behavior can be * all J2EE servers (in particular JBoss). This non-caching behavior can be
* overridden through the {@link #setCacheLevel "cacheLevel"} / * overridden through the {@link #setCacheLevel "cacheLevel"} /
* {@link #setCacheLevelName "cacheLevelName"} property, enforcing caching * {@link #setCacheLevelName "cacheLevelName"} property, enforcing caching of
* of the Connection (or also Session and MessageConsumer) even in case of * the {@code Connection} (or also {@code Session} and {@code MessageConsumer})
* an external transaction manager being involved. * even if an external transaction manager is involved.
* *
* <p>Dynamic scaling of the number of concurrent invokers can be activated * <p>Dynamic scaling of the number of concurrent invokers can be activated
* through specifying a {@link #setMaxConcurrentConsumers "maxConcurrentConsumers"} * by specifying a {@link #setMaxConcurrentConsumers "maxConcurrentConsumers"}
* value that is higher than the {@link #setConcurrentConsumers "concurrentConsumers"} * value that is higher than the {@link #setConcurrentConsumers "concurrentConsumers"}
* value. Since the latter's default is 1, you can also simply specify a * value. Since the latter's default is 1, you can also simply specify a
* "maxConcurrentConsumers" of e.g. 5, which will lead to dynamic scaling up to * "maxConcurrentConsumers" of e.g. 5, which will lead to dynamic scaling up to
@ -87,11 +87,12 @@ import org.springframework.util.ClassUtils;
* shrinking back to the standard number of consumers once the load decreases. * shrinking back to the standard number of consumers once the load decreases.
* Consider adapting the {@link #setIdleTaskExecutionLimit "idleTaskExecutionLimit"} * Consider adapting the {@link #setIdleTaskExecutionLimit "idleTaskExecutionLimit"}
* setting to control the lifespan of each new task, to avoid frequent scaling up * setting to control the lifespan of each new task, to avoid frequent scaling up
* and down, in particular if the ConnectionFactory does not pool JMS Sessions * and down, in particular if the {@code ConnectionFactory} does not pool JMS
* and/or the TaskExecutor does not pool threads (check your configuration!). * {@code Sessions} and/or the {@code TaskExecutor} does not pool threads (check
* Note that dynamic scaling only really makes sense for a queue in the first * your configuration!). Note that dynamic scaling only really makes sense for a
* place; for a topic, you will typically stick with the default number of 1 * queue in the first place; for a topic, you will typically stick with the default
* consumer, else you'd receive the same message multiple times on the same node. * number of 1 consumer, else you'd receive the same message multiple times on
* the same node.
* *
* <p><b>It is strongly recommended to either set {@link #setSessionTransacted * <p><b>It is strongly recommended to either set {@link #setSessionTransacted
* "sessionTransacted"} to "true" or specify an external {@link #setTransactionManager * "sessionTransacted"} to "true" or specify an external {@link #setTransactionManager
@ -129,29 +130,29 @@ public class DefaultMessageListenerContainer extends AbstractPollingMessageListe
public static final int CACHE_NONE = 0; public static final int CACHE_NONE = 0;
/** /**
* Constant that indicates to cache a shared JMS Connection. * Constant that indicates to cache a shared JMS {@code Connection} for each
* listener thread.
* @see #setCacheLevel * @see #setCacheLevel
*/ */
public static final int CACHE_CONNECTION = 1; public static final int CACHE_CONNECTION = 1;
/** /**
* Constant that indicates to cache a shared JMS Connection * Constant that indicates to cache a shared JMS {@code Connection} and a JMS
* and a JMS Session for each listener thread. * {@code Session} for each listener thread.
* @see #setCacheLevel * @see #setCacheLevel
*/ */
public static final int CACHE_SESSION = 2; public static final int CACHE_SESSION = 2;
/** /**
* Constant that indicates to cache a shared JMS Connection * Constant that indicates to cache a shared JMS {@code Connection}, a JMS
* and a JMS Session for each listener thread, as well as * {@code Session}, and a JMS MessageConsumer for each listener thread.
* a JMS MessageConsumer for each listener thread.
* @see #setCacheLevel * @see #setCacheLevel
*/ */
public static final int CACHE_CONSUMER = 3; public static final int CACHE_CONSUMER = 3;
/** /**
* Constant that indicates automatic choice of an appropriate * Constant that indicates automatic choice of an appropriate caching level
* caching level (depending on the transaction management strategy). * (depending on the transaction management strategy).
* @see #setCacheLevel * @see #setCacheLevel
*/ */
public static final int CACHE_AUTO = 4; public static final int CACHE_AUTO = 4;
@ -190,11 +191,11 @@ public class DefaultMessageListenerContainer extends AbstractPollingMessageListe
/** /**
* Set the Spring TaskExecutor to use for running the listener threads. * Set the Spring {@code TaskExecutor} to use for running the listener threads.
* <p>Default is a {@link org.springframework.core.task.SimpleAsyncTaskExecutor}, * <p>Default is a {@link org.springframework.core.task.SimpleAsyncTaskExecutor},
* starting up a number of new threads, according to the specified number * starting up a number of new threads, according to the specified number
* of concurrent consumers. * of concurrent consumers.
* <p>Specify an alternative TaskExecutor for integration with an existing * <p>Specify an alternative {@code TaskExecutor} for integration with an existing
* thread pool. Note that this really only adds value if the threads are * thread pool. Note that this really only adds value if the threads are
* managed in a specific fashion, for example within a J2EE environment. * managed in a specific fashion, for example within a J2EE environment.
* A plain thread pool does not add much value, as this listener container * A plain thread pool does not add much value, as this listener container
@ -230,17 +231,17 @@ public class DefaultMessageListenerContainer extends AbstractPollingMessageListe
/** /**
* Specify the level of caching that this listener container is allowed to apply. * Specify the level of caching that this listener container is allowed to apply.
* <p>Default is CACHE_NONE if an external transaction manager has been specified * <p>Default is {@link #CACHE_NONE} if an external transaction manager has been specified
* (to reobtain all resources freshly within the scope of the external transaction), * (to reobtain all resources freshly within the scope of the external transaction),
* and CACHE_CONSUMER else (operating with local JMS resources). * and {@link #CACHE_CONSUMER} otherwise (operating with local JMS resources).
* <p>Some J2EE servers only register their JMS resources with an ongoing XA * <p>Some J2EE servers only register their JMS resources with an ongoing XA
* transaction in case of a freshly obtained JMS Connection and Session, * transaction in case of a freshly obtained JMS {@code Connection} and {@code Session},
* which is why this listener container does by default not cache any of those. * which is why this listener container by default does not cache any of those.
* However, if you want to optimize for a specific server, consider switching * However, if you want to optimize for a specific server, consider switching
* this setting to at least CACHE_CONNECTION or CACHE_SESSION even in * this setting to at least {@link #CACHE_CONNECTION} or {@link #CACHE_SESSION} even in
* conjunction with an external transaction manager. * conjunction with an external transaction manager.
* <p>Currently known servers that absolutely require CACHE_NONE for XA transaction * <p>Currently known servers that absolutely require {@link #CACHE_NONE} for XA
* processing: JBoss 4. For any others, consider raising the cache level. * transaction processing: JBoss 4. For any others, consider raising the cache level.
* @see #CACHE_NONE * @see #CACHE_NONE
* @see #CACHE_CONNECTION * @see #CACHE_CONNECTION
* @see #CACHE_SESSION * @see #CACHE_SESSION
@ -578,9 +579,9 @@ public class DefaultMessageListenerContainer extends AbstractPollingMessageListe
/** /**
* Return the number of currently scheduled consumers. * Return the number of currently scheduled consumers.
* <p>This number will always be inbetween "concurrentConsumers" and * <p>This number will always be between "concurrentConsumers" and
* "maxConcurrentConsumers", but might be higher than "activeConsumerCount" * "maxConcurrentConsumers", but might be higher than "activeConsumerCount"
* (in case of some consumers being scheduled but not executed at the moment). * (in case some consumers are scheduled but not executing at the moment).
* @see #getConcurrentConsumers() * @see #getConcurrentConsumers()
* @see #getMaxConcurrentConsumers() * @see #getMaxConcurrentConsumers()
* @see #getActiveConsumerCount() * @see #getActiveConsumerCount()
@ -593,9 +594,9 @@ public class DefaultMessageListenerContainer extends AbstractPollingMessageListe
/** /**
* Return the number of currently active consumers. * Return the number of currently active consumers.
* <p>This number will always be inbetween "concurrentConsumers" and * <p>This number will always be between "concurrentConsumers" and
* "maxConcurrentConsumers", but might be lower than "scheduledConsumerCount". * "maxConcurrentConsumers", but might be lower than "scheduledConsumerCount"
* (in case of some consumers being scheduled but not executed at the moment). * (in case some consumers are scheduled but not executing at the moment).
* @see #getConcurrentConsumers() * @see #getConcurrentConsumers()
* @see #getMaxConcurrentConsumers() * @see #getMaxConcurrentConsumers()
* @see #getActiveConsumerCount() * @see #getActiveConsumerCount()
@ -607,19 +608,19 @@ public class DefaultMessageListenerContainer extends AbstractPollingMessageListe
} }
/** /**
* Return whether at lease one consumer has entered a fixed registration with the * Return whether at least one consumer has entered a fixed registration with the
* target destination. This is particularly interesting for the pub-sub case where * target destination. This is particularly interesting for the pub-sub case where
* it might be important to have an actual consumer registered that is guaranteed * it might be important to have an actual consumer registered that is guaranteed
* to not miss any messages that are just about to be published. * not to miss any messages that are just about to be published.
* <p>This method may be polled after a {@link #start()} call, until asynchronous * <p>This method may be polled after a {@link #start()} call, until asynchronous
* registration of consumers has happened which is when the method will start returning * registration of consumers has happened which is when the method will start returning
* <code>true</code> - provided that the listener container actually ever establishes * <code>true</code> &ndash; provided that the listener container ever actually establishes
* a fixed registration. It will then keep returning <code>true</code> until shutdown, * a fixed registration. It will then keep returning <code>true</code> until shutdown,
* since the container will hold on to at least one consumer registration thereafter. * since the container will hold on to at least one consumer registration thereafter.
* <p>Note that a listener container is not bound to having a fixed registration in * <p>Note that a listener container is not bound to having a fixed registration in
* the first place. It may also keep recreating consumers for every invoker execution. * the first place. It may also keep recreating consumers for every invoker execution.
* This particularly depends on the {@link #setCacheLevel cache level} setting: * This particularly depends on the {@link #setCacheLevel cache level} setting:
* Only CACHE_CONSUMER will lead to a fixed registration. * only {@link #CACHE_CONSUMER} will lead to a fixed registration.
*/ */
public boolean isRegisteredWithDestination() { public boolean isRegisteredWithDestination() {
synchronized (this.lifecycleMonitor) { synchronized (this.lifecycleMonitor) {
@ -801,7 +802,7 @@ public class DefaultMessageListenerContainer extends AbstractPollingMessageListe
} }
if (ex instanceof SharedConnectionNotInitializedException) { if (ex instanceof SharedConnectionNotInitializedException) {
if (!alreadyRecovered) { if (!alreadyRecovered) {
logger.debug("JMS message listener invoker needs to establish shared Connection"); logger.info("JMS message listener invoker needs to establish shared Connection");
} }
} }
else { else {
@ -900,7 +901,7 @@ public class DefaultMessageListenerContainer extends AbstractPollingMessageListe
/** /**
* Sleep according to the specified recovery interval. * Sleep according to the specified recovery interval.
* Called inbetween recovery attempts. * Called between recovery attempts.
*/ */
protected void sleepInbetweenRecoveryAttempts() { protected void sleepInbetweenRecoveryAttempts() {
if (this.recoveryInterval > 0) { if (this.recoveryInterval > 0) {