Polishing (selectively backported from recent 4.0 commits)

spring-context-support/src/main/java/org/springframework/scheduling/commonj/WorkManagerTaskExecutor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,10 +17,9 @@
 package org.springframework.scheduling.commonj;
 
 import java.util.Collection;
+import java.util.concurrent.Callable;
 import java.util.concurrent.Future;
 import java.util.concurrent.FutureTask;
-import java.util.concurrent.Callable;
-
 import javax.naming.NamingException;
 
 import commonj.work.Work;
@@ -54,10 +53,8 @@ import org.springframework.util.Assert;
  * server's JNDI environment, as defined in the server's management console.
  *
  * <p><b>Note: At the time of this writing, the CommonJ WorkManager facility
- * is only supported on IBM WebSphere 6.0+ and BEA WebLogic 9.0+,
+ * is only supported on IBM WebSphere 6.1+ and BEA WebLogic 9.0+,
  * despite being such a crucial API for an application server.</b>
- * (There is a similar facility available on WebSphere 5.1 Enterprise,
- * though, which we will discuss below.)
  *
  * <p><b>On JBoss and GlassFish, a similar facility is available through
  * the JCA WorkManager.</b> See the
@@ -80,8 +77,7 @@ public class WorkManagerTaskExecutor extends JndiLocatorSupport
 
 	/**
 	 * Specify the CommonJ WorkManager to delegate to.
-	 * <p>Alternatively, you can also specify the JNDI name
+	 * <p>Alternatively, you can also specify the JNDI name of the target WorkManager.
-	 * of the target WorkManager.
 	 * @see #setWorkManagerName
 	 */
 	public void setWorkManager(WorkManager workManager) {
@@ -90,9 +86,8 @@ public class WorkManagerTaskExecutor extends JndiLocatorSupport
 
 	/**
 	 * Set the JNDI name of the CommonJ WorkManager.
-	 * <p>This can either be a fully qualified JNDI name,
+	 * <p>This can either be a fully qualified JNDI name, or the JNDI name relative
-	 * or the JNDI name relative to the current environment
+	 * to the current environment naming context if "resourceRef" is set to "true".
-	 * naming context if "resourceRef" is set to "true".
 	 * @see #setWorkManager
 	 * @see #setResourceRef
 	 */
@@ -170,27 +165,19 @@ public class WorkManagerTaskExecutor extends JndiLocatorSupport
 	// Implementation of the CommonJ WorkManager interface
 	//-------------------------------------------------------------------------
 
-	public WorkItem schedule(Work work)
+	public WorkItem schedule(Work work) throws WorkException, IllegalArgumentException {
-			throws WorkException, IllegalArgumentException {
-
 		return this.workManager.schedule(work);
 	}
 
-	public WorkItem schedule(Work work, WorkListener workListener)
+	public WorkItem schedule(Work work, WorkListener workListener) throws WorkException {
-			throws WorkException, IllegalArgumentException {
-
 		return this.workManager.schedule(work, workListener);
 	}
 
-	public boolean waitForAll(Collection workItems, long timeout)
+	public boolean waitForAll(Collection workItems, long timeout) throws InterruptedException {
-			throws InterruptedException, IllegalArgumentException {
-
 		return this.workManager.waitForAll(workItems, timeout);
 	}
 
-	public Collection waitForAny(Collection workItems, long timeout)
+	public Collection waitForAny(Collection workItems, long timeout) throws InterruptedException {
-			throws InterruptedException, IllegalArgumentException {
-
 		return this.workManager.waitForAny(workItems, timeout);
 	}
 

spring-context/src/main/java/org/springframework/cache/Cache.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -39,11 +39,15 @@ public interface Cache {
 	Object getNativeCache();
 
 	/**
-	 * Return the value to which this cache maps the specified key. Returns
+	 * Return the value to which this cache maps the specified key.
-	 * {@code null} if the cache contains no mapping for this key.
+	 * <p>Returns {@code null} if the cache contains no mapping for this key;
-	 * @param key key whose associated value is to be returned.
+	 * otherwise, the cached value (which may be {@code null} itself) will
+	 * be returned in a {@link ValueWrapper}.
+	 * @param key the key whose associated value is to be returned
 	 * @return the value to which this cache maps the specified key,
-	 * or {@code null} if the cache contains no mapping for this key
+	 * contained within a {@link ValueWrapper} which may also hold
+	 * a cached {@code null} value. A straight {@code null} being
+	 * returned means that the cache contains no mapping for this key.
 	 */
 	ValueWrapper get(Object key);
 

spring-tx/src/main/java/org/springframework/jca/work/glassfish/GlassFishWorkManagerTaskExecutor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,12 +43,12 @@ public class GlassFishWorkManagerTaskExecutor extends WorkManagerTaskExecutor {
 
 	public GlassFishWorkManagerTaskExecutor() {
 		try {
-			Class wmf = getClass().getClassLoader().loadClass(WORK_MANAGER_FACTORY_CLASS);
+			Class<?> wmf = getClass().getClassLoader().loadClass(WORK_MANAGER_FACTORY_CLASS);
-			this.getWorkManagerMethod = wmf.getMethod("getWorkManager", new Class[] {String.class});
+			this.getWorkManagerMethod = wmf.getMethod("getWorkManager", String.class);
 		}
 		catch (Exception ex) {
 			throw new IllegalStateException(
-					"Could not initialize GlassFishWorkManagerTaskExecutor because GlassFish API is not available: " + ex);
+					"Could not initialize GlassFishWorkManagerTaskExecutor because GlassFish API is not available", ex);
 		}
 	}
 

spring-tx/src/main/java/org/springframework/jca/work/jboss/JBossWorkManagerTaskExecutor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2010 the original author or authors.
+ * Copyright 2002-2013 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,6 +29,10 @@ import org.springframework.jca.work.WorkManagerTaskExecutor;
  * {@link org.springframework.scheduling.commonj.WorkManagerTaskExecutor}
  * adapter for WebLogic and WebSphere.
  *
+ * <p><b>Note: This class does not work on JBoss 7 or higher.</b>
+ * There is no known immediate replacement, since JBoss does not want
+ * its JCA WorkManager to be exposed anymore.
+ *
  * @author Juergen Hoeller
  * @since 2.5.2
  * @see org.jboss.resource.work.JBossWorkManagerMBean

spring-tx/src/main/java/org/springframework/jca/work/jboss/JBossWorkManagerUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2010 the original author or authors.
+ * Copyright 2002-2013 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -69,7 +69,7 @@ public abstract class JBossWorkManagerUtils {
 		}
 		catch (Exception ex) {
 			throw new IllegalStateException(
-					"Could not initialize JBossWorkManagerTaskExecutor because JBoss API is not available: " + ex);
+					"Could not initialize JBossWorkManagerTaskExecutor because JBoss API is not available", ex);
 		}
 	}