Package com.hazelcast.cache

Class HazelcastCachingProvider

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, javax.cache.spi.CachingProvider
    public final class HazelcastCachingProvider
extends java.lang.Object
implements javax.cache.spi.CachingProvider
    Hazelcast implementation of JCache CachingProvider.

    This provider class is registered as a CachingProvider implementation. When Hazelcast is the only CachingProvider on the classpath, using Caching.getCachingProvider() will instantiate and return an instance of this class.

    This provider implementation delegates to a CachingProvider backed by either a member- or a client-side HazelcastInstance:

    Provider Type Selection

    When using Caching.getCachingProvider() without a class name argument, this provider is instantiated. The choice between member- or client-side provider is made by inspecting the value of system property hazelcast.jcache.provider.type:

    • If no value was set, then the client-side caching provider is selected
    • If a value was set, then value member selects the member-side caching provider, while value client selects the client-side provider. Legacy value server is also accepted as an alias for member for backwards compatibility, however its usage is discouraged and will be removed in a future version. Other values result in a CacheException being thrown.

    When using one of Caching#getCachingProvider variants with an explicit class name argument, then:

    • using com.hazelcast.cache.HazelcastCachingProvider as class name is identical to using Caching.getCachingProvider(); choice between member- or client-side caching provider is performed via system property hazelcast.jcache.provider.type as described above.
    • using MEMBER_CACHING_PROVIDER as class name will return a member-side caching provider
    • using CLIENT_CACHING_PROVIDER as class name will return a client-side caching provider

    Creating or reusing HazelcastInstances with CacheManagers

    Arguments used with CachingProvider.getCacheManager(URI, ClassLoader, Properties) and its variants control whether a HazelcastInstance will be created or reused to back the CacheManager being created:
    • Property hazelcast.config.location specifies a URI to locate a Hazelcast member or client configuration file. Supports classpath:, file:, http: and https: URI schemes. Examples: classpath:com/acme/hazelcast.xml will locate hazelcast.xml in package com.acme, http://internal.acme.com/hazelcast.xml will locate the configuration from the given HTTP URL.
    • Property hazelcast.instance.name specifies the instance name of a running HazelcastInstance. If no instance is found running by that name, then a new HazelcastInstance is started with a default configuration and the given instance name.
    • In any CachingProvider#getCacheManager variant that accepts a URI as argument, and if no properties were provided or properties did not result in resolving a specific HazelcastInstance, then the URI argument is interpreted as a Hazelcast config location as follows:
      1. if URI starts with one of supported schemes (classpath:, http:, https:, file:), then a Hazelcast XML configuration is loaded from that location.
      2. otherwise, URI is interpreted as a system property. If System.getProperty(URI) returns a value that starts with one of supported schemes above, then a Hazelcast XML configuration is loaded from that location.
      3. if URI or its resolved value as a system property does not start with a supported URI scheme, a default HazelcastInstance named "_hzinstance_jcache_shared" is created or used, if it already exists.
    Convenience methods propertiesByLocation(String) and propertiesByInstanceName(String) will create an appropriate Properties instance for use with getCacheManager(URI, ClassLoader, Properties).

    Examples

    Obtain a member-side caching provider backed by an existing HazelcastInstance. In this example the member-side caching provider is selected by setting the value of system property hazelcast.jcache.provider.type to value "member". An existing HazelcastInstance is referenced by instance name in the Properties provided as argument to CachingProvider.getCacheManager(URI, ClassLoader, Properties). 

     Config config = new Config();
 config.setInstanceName("hz-jcache");
 HazelcastInstance member = Hazelcast.newHazelcastInstance(config);

 System.setProperty("hazelcast.jcache.provider.type", "member");
 CachingProvider provider = Caching.getCachingProvider();
 CacheManager manager = provider.getCacheManager(null, null, HazelcastCachingProvider.propertiesByInstanceName("hz-jcache"));
 Cache cache = manager.createCache("sessions", new MutableConfiguration());
 cache.put("a", "b");

    Obtain a client-side caching provider, starting a default client HazelcastInstance In this example the client-side caching provider is selected as default option. A new client-side HazelcastInstance is created with default configuration once CachingProvider.getCacheManager() is called. 

     // start a Hazelcast member for the client to connect to
 HazelcastInstance member = Hazelcast.newHazelcastInstance();

 // obtain a client-side (default) CachingProvider
 CachingProvider provider = Caching.getCachingProvider();
 // obtain the default CacheManager; since there is no JCache-backing client-side
 // HazelcastInstance started, this will start a new instance
 CacheManager manager = provider.getCacheManager();
 Cache cache = manager.createCache("sessions", new MutableConfiguration());
 cache.put("a", "b");
    Since:
    3.4

    • Field Detail

      • HAZELCAST_CONFIG_LOCATION

        public static final java.lang.String HAZELCAST_CONFIG_LOCATION
        Hazelcast config location property
        See Also:
        Constant Field Values

      • HAZELCAST_INSTANCE_NAME

        public static final java.lang.String HAZELCAST_INSTANCE_NAME
        Hazelcast instance name property
        See Also:
        Constant Field Values

      • HAZELCAST_INSTANCE_ITSELF

        public static final java.lang.String HAZELCAST_INSTANCE_ITSELF
        Hazelcast instance itself property
        See Also:
        Constant Field Values

      • MEMBER_CACHING_PROVIDER

        public static final java.lang.String MEMBER_CACHING_PROVIDER
        Class name of the member-side Caching Provider

      • SERVER_CACHING_PROVIDER

        @Deprecated
public static final java.lang.String SERVER_CACHING_PROVIDER
        Deprecated.
        Same value as MEMBER_CACHING_PROVIDER. This field is maintained for backwards compatibility. Its use is discouraged and will be removed in a future version.

      • CLIENT_CACHING_PROVIDER

        public static final java.lang.String CLIENT_CACHING_PROVIDER
        Class name of the client-side Caching Provider

      • SHARED_JCACHE_INSTANCE_NAME

        public static final java.lang.String SHARED_JCACHE_INSTANCE_NAME
        Name of default HazelcastInstance which may be started when obtaining the default CachingProvider.
        See Also:
        Constant Field Values

    • Constructor Detail

      • HazelcastCachingProvider

        public HazelcastCachingProvider()

    • Method Detail

      • propertiesByLocation

        public static java.util.Properties propertiesByLocation​(java.lang.String configFileLocation)
        Create the Properties with the provided config file location.
        Parameters:
        configFileLocation - the location of the config file to configure
        Returns:
        properties instance pre-configured with the configuration location

      • propertiesByInstanceName

        public static java.util.Properties propertiesByInstanceName​(java.lang.String instanceName)
        Create the Properties with the provided instance name.
        Parameters:
        instanceName - the instance name to configure
        Returns:
        the properties instance pre-configured with the instance name

      • propertiesByInstanceItself

        public static java.util.Properties propertiesByInstanceItself​(HazelcastInstance instance)
        Create the Properties with the provided instance itself.
        Parameters:
        instance - the instance itself to be used
        Returns:
        the properties instance pre-configured with the instance itself

      • getCacheManager

        public javax.cache.CacheManager getCacheManager​(java.net.URI uri,
                                                java.lang.ClassLoader classLoader,
                                                java.util.Properties properties)
        Specified by:
        getCacheManager in interface javax.cache.spi.CachingProvider

      • getDefaultClassLoader

        public java.lang.ClassLoader getDefaultClassLoader()
        Specified by:
        getDefaultClassLoader in interface javax.cache.spi.CachingProvider

      • getDefaultURI

        public java.net.URI getDefaultURI()
        Specified by:
        getDefaultURI in interface javax.cache.spi.CachingProvider

      • getDefaultProperties

        public java.util.Properties getDefaultProperties()
        Specified by:
        getDefaultProperties in interface javax.cache.spi.CachingProvider

      • getCacheManager

        public javax.cache.CacheManager getCacheManager​(java.net.URI uri,
                                                java.lang.ClassLoader classLoader)
        Specified by:
        getCacheManager in interface javax.cache.spi.CachingProvider

      • getCacheManager

        public javax.cache.CacheManager getCacheManager()
        Specified by:
        getCacheManager in interface javax.cache.spi.CachingProvider

      • close

        public void close()
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface javax.cache.spi.CachingProvider
        Specified by:
        close in interface java.io.Closeable

      • close

        public void close​(java.lang.ClassLoader classLoader)
        Specified by:
        close in interface javax.cache.spi.CachingProvider

      • close

        public void close​(java.net.URI uri,
                  java.lang.ClassLoader classLoader)
        Specified by:
        close in interface javax.cache.spi.CachingProvider

      • isSupported

        public boolean isSupported​(javax.cache.configuration.OptionalFeature optionalFeature)
        Specified by:
        isSupported in interface javax.cache.spi.CachingProvider

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object