https://github.com/jsr107/jsr107spec: Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/ 
Copyright 2011-2016 Terracotta, Inc.
Copyright 2011-2016 Oracle America Incorporated
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
    http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

/**
 * Copyright 2011-2016 Terracotta, Inc.
 * Copyright 2011-2016 Oracle America Incorporated
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package javax.cache.spi;

import javax.cache.CacheException;
import javax.cache.CacheManager;
import javax.cache.configuration.OptionalFeature;
import java.io.Closeable;
import java.net.URI;
import java.util.Properties;


Provides mechanisms to create, request and later manage the life-cycle of configured CacheManagers, identified by URIs and scoped by ClassLoaders. 
 The meaning and semantics of the URI used to identify a CacheManager is implementation dependent. For applications to remain implementation independent, they should avoid attempting to create URIs and instead use those returned by getDefaultURI(). 
Author:Brian Oliver, Greg Luck
Since:1.0
/**
 * Provides mechanisms to create, request and later manage the life-cycle of
 * configured {@link CacheManager}s, identified by {@link URI}s and scoped by
 * {@link ClassLoader}s.
 * <p>
 * The meaning and semantics of the {@link URI} used to identify a
 * {@link CacheManager} is implementation dependent.  For applications to remain
 * implementation independent, they should avoid attempting to create {@link URI}s
 * and instead use those returned by {@link #getDefaultURI()}.
 *
 * @author Brian Oliver
 * @author Greg Luck
 * @since 1.0
 */
public interface CachingProvider extends Closeable {

  
Requests a CacheManager configured according to the implementation specific URI be made available that uses the provided ClassLoader for loading underlying classes. 
 Multiple calls to this method with the same URI and ClassLoader must return the same CacheManager instance, except if a previously returned CacheManager has been closed. 
 Properties are used in construction of a CacheManager and do not form part of the identity of the CacheManager. i.e. if a second call is made to with the same URI and ClassLoader but different properties, the CacheManager created in the first call is returned. 
 Properties names follow the same scheme as package names. The prefixes java and javax are reserved. Properties are passed through and can be retrieved via CacheManager.getProperties(). Properties within the package scope of a caching implementation may be used for additional configuration. 
Params:
Throws:
/**
   * Requests a {@link CacheManager} configured according to the implementation
   * specific {@link URI} be made available that uses the provided
   * {@link ClassLoader} for loading underlying classes.
   * <p>
   * Multiple calls to this method with the same {@link URI} and
   * {@link ClassLoader} must return the same {@link CacheManager} instance,
   * except if a previously returned {@link CacheManager} has been closed.
   * <p>
   * Properties are used in construction of a {@link CacheManager} and do not form
   * part of the identity of the CacheManager. i.e. if a second call is made to
   * with the same {@link URI} and {@link ClassLoader} but different properties,
   * the {@link CacheManager} created in the first call is returned.
   * <p>
   * Properties names follow the same scheme as package names.
   * The prefixes {@code java} and {@code javax} are reserved.
   * Properties are passed through and can be retrieved via
   * {@link CacheManager#getProperties()}.
   * Properties within the package scope of a caching implementation may be used for
   * additional configuration.
   *
   * @param uri         an implementation specific URI for the
   *                    {@link CacheManager} (null means use
   *                    {@link #getDefaultURI()})
   * @param classLoader the {@link ClassLoader}  to use for the
   *                    {@link CacheManager} (null means use
   *                    {@link #getDefaultClassLoader()})
   * @param properties  the {@link Properties} for the {@link CachingProvider}
   *                    to create the {@link CacheManager} (null means no
   *                    implementation specific Properties are required)
   * @throws CacheException    when a {@link CacheManager} for the
   *                           specified arguments could not be produced
   * @throws SecurityException when the operation could not be performed
   *                           due to the current security settings
   */
  CacheManager getCacheManager(URI uri, ClassLoader classLoader,
                               Properties properties);

  
Obtains the default ClassLoader that will be used by the CachingProvider. 
Returns:the default ClassLoader used by the CachingProvider
/**
   * Obtains the default {@link ClassLoader} that will be used by the
   * {@link CachingProvider}.
   *
   * @return the default {@link ClassLoader} used by the {@link CachingProvider}
   */
  ClassLoader getDefaultClassLoader();

  
Obtains the default URI for the CachingProvider. 
 Use this method to obtain a suitable URI for the CachingProvider. 
Returns:the default URI for the CachingProvider
/**
   * Obtains the default {@link URI} for the {@link CachingProvider}.
   * <p>
   * Use this method to obtain a suitable {@link URI} for the
   * {@link CachingProvider}.
   *
   * @return the default {@link URI} for the {@link CachingProvider}
   */
  URI getDefaultURI();

  
Obtains the default Properties for the CachingProvider. 
 Use this method to obtain suitable Properties for the CachingProvider. 
Returns:the default Properties for the CachingProvider
/**
   * Obtains the default {@link Properties} for the {@link CachingProvider}.
   * <p>
   * Use this method to obtain suitable {@link Properties} for the
   * {@link CachingProvider}.
   *
   * @return the default {@link Properties} for the {@link CachingProvider}
   */
  Properties getDefaultProperties();

  
Requests a CacheManager configured according to the implementation specific URI that uses the provided ClassLoader for loading underlying classes. 
 Multiple calls to this method with the same URI and ClassLoader must return the same CacheManager instance, except if a previously returned CacheManager has been closed. 
Params:
Throws:
/**
   * Requests a {@link CacheManager} configured according to the implementation
   * specific {@link URI} that uses the provided {@link ClassLoader} for loading
   * underlying classes.
   * <p>
   * Multiple calls to this method with the same {@link URI} and
   * {@link ClassLoader} must return the same {@link CacheManager} instance,
   * except if a previously returned {@link CacheManager} has been closed.
   *
   * @param uri         an implementation specific {@link URI} for the
   *                    {@link CacheManager} (null means
   *                    use {@link #getDefaultURI()})
   * @param classLoader the {@link ClassLoader}  to use for the
   *                    {@link CacheManager} (null means
   *                    use {@link #getDefaultClassLoader()})
   * @throws CacheException    when a {@link CacheManager} for the
   *                           specified arguments could not be produced
   * @throws SecurityException when the operation could not be performed
   *                           due to the current security settings
   */
  CacheManager getCacheManager(URI uri, ClassLoader classLoader);

  
Requests a CacheManager configured according to the getDefaultURI() and getDefaultProperties() be made available that using the getDefaultClassLoader() for loading underlying classes. 
 Multiple calls to this method must return the same CacheManager instance, except if a previously returned CacheManager has been closed. 
Throws:
  • SecurityException – when the operation could not be performed
                          due to the current security settings
/**
   * Requests a {@link CacheManager} configured according to the
   * {@link #getDefaultURI()} and {@link #getDefaultProperties()} be made
   * available that using the {@link #getDefaultClassLoader()} for loading
   * underlying classes.
   * <p>
   * Multiple calls to this method must return the same {@link CacheManager}
   * instance, except if a previously returned {@link CacheManager} has been
   * closed.
   *
   * @throws SecurityException when the operation could not be performed
   *                           due to the current security settings
   */
  CacheManager getCacheManager();

  
Closes all of the CacheManager instances and associated resources created and maintained by the CachingProvider across all ClassLoaders. 
 After closing the CachingProvider will still be operational. It may still be used for acquiring CacheManager instances, though those will now be new. 
Throws:
  • SecurityException – when the operation could not be performed
                          due to the current security settings
/**
   * Closes all of the {@link CacheManager} instances and associated resources
   * created and maintained by the {@link CachingProvider} across all
   * {@link ClassLoader}s.
   * <p>
   * After closing the {@link CachingProvider} will still be operational.  It
   * may still be used for acquiring {@link CacheManager} instances, though
   * those will now be new.
   *
   * @throws SecurityException when the operation could not be performed
   *                           due to the current security settings
   */
  void close();

  
Closes all CacheManager instances and associated resources created by the CachingProvider using the specified ClassLoader. 
 After closing the CachingProvider will still be operational. It may still be used for acquiring CacheManager instances, though those will now be new for the specified ClassLoader . 
Params:
Throws:
  • SecurityException – when the operation could not be performed
                          due to the current security settings
/**
   * Closes all {@link CacheManager} instances and associated resources created
   * by the {@link CachingProvider} using the specified {@link ClassLoader}.
   * <p>
   * After closing the {@link CachingProvider} will still be operational.  It
   * may still be used for acquiring {@link CacheManager} instances, though
   * those will now be new for the specified {@link ClassLoader} .
   *
   * @param classLoader the {@link ClassLoader}  to release
   * @throws SecurityException when the operation could not be performed
   *                           due to the current security settings
   */
  void close(ClassLoader classLoader);

  
Closes all CacheManager instances and associated resources created by the CachingProvider for the specified URI and ClassLoader. 
Params:
Throws:
  • SecurityException – when the operation could not be performed
                          due to the current security settings
/**
   * Closes all {@link CacheManager} instances and associated resources created
   * by the {@link CachingProvider} for the specified {@link URI} and
   * {@link ClassLoader}.
   *
   * @param uri         the {@link URI} to release
   * @param classLoader the {@link ClassLoader}  to release
   * @throws SecurityException when the operation could not be performed
   *                           due to the current security settings
   */
  void close(URI uri, ClassLoader classLoader);

  
Determines whether an optional feature is supported by the CachingProvider. 
Params:
  • optionalFeature – the feature to check for
Returns:true if the feature is supported
/**
   * Determines whether an optional feature is supported by the
   * {@link CachingProvider}.
   *
   * @param optionalFeature the feature to check for
   * @return true if the feature is supported
   */
  boolean isSupported(OptionalFeature optionalFeature);
}