Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Javadoc changes suggested from internal reviews

  • Loading branch information...
commit 72d534c908d7730fd9ea990943b2ace30eb9fe78 1 parent dc620e2
@yannis666 yannis666 authored
View
26 src/main/java/javax/cache/CacheManager.java
@@ -51,7 +51,6 @@
* <p/>
* Calls to this method will block while the state is changing.
* @return one of {@link Status}
- * todo RI should block until transition completed and needs internal transitional states
*/
Status getStatus();
@@ -72,7 +71,6 @@
* Cache&lt;Integer, String&gt; myCache1 = cacheManager.
* &lt;Integer, String&gt;createCacheBuilder("myCache1").
* setCacheLoader(cl).
- * setCacheLoader(cl).
* setStoreByValue(true).
* setReadThrough(true).
* setWriteThrough(false).
@@ -88,7 +86,7 @@
* The Cache will be created, added to the caches controlled by this CacheManager and started when
* {@link javax.cache.CacheBuilder#build()} is called.
* If there is an existing Cache of the same name associated with this CacheManager when build is invoked,
- * the old Cache will be stopped.
+ * an exception is thrown.
*
* @param cacheName the name of the cache to build. A cache name must consist of at least one non-whitespace character.
* @return the CacheBuilder for the named cache
@@ -109,11 +107,11 @@
<K, V> Cache<K, V> getCache(String cacheName);
/**
- * Returns an iterable over the caches managed by this CacheManager.
- * This is immutable and independent of the cache manager; if the caches managed
- * by the cache manager change the set is not affected
+ * Returns an Iterable over the caches managed by this CacheManager.
+ * The Iterable is immutable (iterator.remove will throw an IllegalStateException) and independent
+ * of the cache manager; if the caches managed by the cache manager change the Iterable is not affected
*
- * @return an iterable over the managed Caches
+ * @return an Iterable over the managed Caches
* @throws UnsupportedOperationException if an attempt it made to remove an element
*/
Iterable<Cache<?, ?>> getCaches();
@@ -148,14 +146,15 @@
/**
* Shuts down the CacheManager.
* <p/>
- * For each cache in the cache manager the {@link javax.cache.Cache#stop()} method will be invoked, in no guaranteed order.
- * If the stop throws an exception, the exception will be consumed silently.
+ * For each cache in the cache manager the {@link javax.cache.Cache#stop()}
+ * method will be invoked, in no guaranteed order.
+ * If the stop throws an exception, the exception is ignored.
* <p/>
* Calls to {@link #getStatus()} will block until shutdown completes.
* <p/>
- * During the execution of the method calls to {@link #getStatus()} will block.
- * On completion the CacheManager's status is changed to {@link Status#STOPPED}, and the manager's owned caches will be empty &amp;
- * {@link #getCaches()} will return an empty collection.
+ * On completion the CacheManager's status is changed to {@link Status#STOPPED},
+ * and the manager's owned caches will be empty and {@link #getCaches()}
+ * will return an empty collection.
* <p/>
* A given CacheManager instance cannot be restarted after it has been stopped. A new one must be created.
* @throws IllegalStateException if an operation is performed on CacheManager while stopping or stopped.
@@ -166,7 +165,8 @@
* Return an object of the specified type to allow access to the provider-specific API. If the provider's
* implementation does not support the specified class, the {@link IllegalArgumentException} is thrown.
*
- * @param cls the class of the object to be returned. This is normally either the underlying implementation class or an interface that it implements.
+ * @param cls the class of the object to be returned. This is normally either the
+ * underlying implementation class or an interface that it implements.
* @return an instance of the specified class
* @throws IllegalArgumentException if the provider doesn't support the specified class.
*/
View
17 src/main/java/javax/cache/Caching.java
@@ -26,10 +26,12 @@
* </pre>
* containing the class name implementing {@link javax.cache.spi.CachingProvider}
* <p/>
- * e.g. For the reference implementation:
+ * For example, in the reference implementation the contents are:
* <p/>
* "javax.cache.implementation.RIServiceFactory"
* <p/>
+ * If more than one CachingProvider is found, getCacheManagerFactory will throw an exception
+ * <p/>
* Also keeps track of all CacheManagers created by the factory. Subsequent calls
* to {@link #getCacheManager()} return the same CacheManager.
*
@@ -55,6 +57,7 @@ private Caching() {
/**
* Get the singleton CacheManagerFactory
* @return the cache manager factory
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static CacheManagerFactory getCacheManagerFactory() {
return ServiceFactoryHolder.INSTANCE.getCachingProvider().getCacheManagerFactory();
@@ -65,7 +68,7 @@ public static CacheManagerFactory getCacheManagerFactory() {
* The default cache manager is named {@link #DEFAULT_CACHE_MANAGER_NAME}
*
* @return the default cache manager
- * @throws IllegalStateException if no CachingProvider was found
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static CacheManager getCacheManager() {
return getCacheManager(DEFAULT_CACHE_MANAGER_NAME);
@@ -77,7 +80,7 @@ public static CacheManager getCacheManager() {
*
* @param classLoader the ClassLoader that should be used in converting values into Java Objects. May be null.
* @return the default cache manager
- * @throws IllegalStateException if no CachingProvider was found
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static CacheManager getCacheManager(ClassLoader classLoader) {
return getCacheManager(classLoader, DEFAULT_CACHE_MANAGER_NAME);
@@ -90,7 +93,7 @@ public static CacheManager getCacheManager(ClassLoader classLoader) {
* @param name the name of the cache manager
* @return the named cache manager
* @throws NullPointerException if name is null
- * @throws IllegalStateException if no CachingProvider was found
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static CacheManager getCacheManager(String name) {
return getCacheManagerFactory().getCacheManager(name);
@@ -124,7 +127,7 @@ public static CacheManager getCacheManager(String name) {
* @param name the name of this cache manager
* @return the new cache manager
* @throws NullPointerException if classLoader or name is null
- * @throws IllegalStateException if no CachingProvider was found
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static CacheManager getCacheManager(ClassLoader classLoader, String name) {
return getCacheManagerFactory().getCacheManager(classLoader, name);
@@ -145,6 +148,7 @@ public static CacheManager getCacheManager(ClassLoader classLoader, String name)
* </pre>
*
* @throws CachingShutdownException if any of the individual shutdowns failed
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static void close() throws CachingShutdownException {
getCacheManagerFactory().close();
@@ -158,6 +162,7 @@ public static void close() throws CachingShutdownException {
* @param classLoader the class loader for which managers will be shut down
* @return true if found, false otherwise
* @throws CachingShutdownException if any of the individual shutdowns failed
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static boolean close(ClassLoader classLoader) throws CachingShutdownException {
return getCacheManagerFactory().close(classLoader);
@@ -172,6 +177,7 @@ public static boolean close(ClassLoader classLoader) throws CachingShutdownExcep
* @param name the name of the cache manager
* @return true if found, false otherwise
* @throws CachingShutdownException if any of the individual shutdowns failed
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static boolean close(ClassLoader classLoader, String name) throws CachingShutdownException {
return getCacheManagerFactory().close(classLoader, name);
@@ -182,6 +188,7 @@ public static boolean close(ClassLoader classLoader, String name) throws Caching
*
* @param optionalFeature the feature to check for
* @return true if the feature is supported
+ * @throws IllegalStateException if no CachingProvider is found or if more than one CachingProvider is found
*/
public static boolean isSupported(OptionalFeature optionalFeature) {
return ServiceFactoryHolder.INSTANCE.getCachingProvider().isSupported(optionalFeature);
Please sign in to comment.
Something went wrong with that request. Please try again.