Clarified CompositeCacheManager's applicability, added convenience constructor...

Clarified CompositeCacheManager's applicability, added convenience constructor with given delegates, and fixed getCacheNames implementation to never return duplicates

Issue: SPR-11427

spring-context/src/main/java/org/springframework/cache/support/CompositeCacheManager.java

 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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,42 +17,72 @@
 package org.springframework.cache.support;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Set;
 
 import org.springframework.beans.factory.InitializingBean;
 import org.springframework.cache.Cache;
 import org.springframework.cache.CacheManager;
-import org.springframework.util.Assert;
 
 /**
- * Composite {@link CacheManager} implementation that iterates
- * over a given collection of {@link CacheManager} instances.
+ * Composite {@link CacheManager} implementation that iterates over
+ * a given collection of delegate {@link CacheManager} instances.
  *
- * Allows {@link NoOpCacheManager} to be automatically added to the list for handling
- * the cache declarations without a backing store.
+ * <p>Allows {@link NoOpCacheManager} to be automatically added to the end of
+ * the list for handling cache declarations without a backing store. Otherwise,
+ * any custom {@link CacheManager} may play that role of the last delegate as
+ * well, lazily creating cache regions for any requested name.
+ *
+ * <p>Note: Regular CacheManagers that this composite manager delegates to need
+ * to return {@code null} from {@link #getCache(String)} if they are unaware of
+ * the specified cache name, allowing for iteration to the next delegate in line.
+ * However, most {@link CacheManager} implementations fall back to lazy creation
+ * of named caches once requested; check out the specific configuration details
+ * for a 'static' mode with fixed cache names, if available.
  *
  * @author Costin Leau
  * @author Juergen Hoeller
  * @since 3.1
+ * @see #setFallbackToNoOpCache
+ * @see org.springframework.cache.concurrent.ConcurrentMapCacheManager#setCacheNames
  */
-public class CompositeCacheManager implements InitializingBean, CacheManager {
+public class CompositeCacheManager implements CacheManager, InitializingBean {
 
-	private List<CacheManager> cacheManagers;
+	private final List<CacheManager> cacheManagers = new ArrayList<CacheManager>();
 
 	private boolean fallbackToNoOpCache = false;
 
 
+	/**
+	 * Construct an empty CompositeCacheManager, with delegate CacheManagers to
+	 * be added via the {@link #setCacheManagers "cacheManagers"} property.
+	 */
+	public CompositeCacheManager() {
+	}
+
+	/**
+	 * Construct a CompositeCacheManager from the given delegate CacheManagers.
+	 * @param cacheManagers the CacheManagers to delegate to
+	 */
+	public CompositeCacheManager(CacheManager... cacheManagers) {
+		setCacheManagers(Arrays.asList(cacheManagers));
+	}
+
+
+	/**
+	 * Specify the CacheManagers to delegate to.
+	 */
 	public void setCacheManagers(Collection<CacheManager> cacheManagers) {
-		Assert.notEmpty(cacheManagers, "cacheManagers Collection must not be empty");
-		this.cacheManagers = new ArrayList<CacheManager>();
 		this.cacheManagers.addAll(cacheManagers);
 	}
 
 	/**
-	 * Indicate whether a {@link NoOpCacheManager} should be added at the end of the manager lists.
-	 * In this case, any {@code getCache} requests not handled by the configured cache managers will
+	 * Indicate whether a {@link NoOpCacheManager} should be added at the end of the delegate list.
+	 * In this case, any {@code getCache} requests not handled by the configured CacheManagers will
 	 * be automatically handled by the {@link NoOpCacheManager} (and hence never return {@code null}).
 	 */
 	public void setFallbackToNoOpCache(boolean fallbackToNoOpCache) {
@@ -80,11 +110,11 @@ public class CompositeCacheManager implements InitializingBean, CacheManager {
 
 	@Override
 	public Collection<String> getCacheNames() {
-		List<String> names = new ArrayList<String>();
+		Set<String> names = new LinkedHashSet<String>();
 		for (CacheManager manager : this.cacheManagers) {
 			names.addAll(manager.getCacheNames());
 		}
-		return Collections.unmodifiableList(names);
+		return Collections.unmodifiableSet(names);
 	}
 
 }