Package com.hazelcast.cache

Class HazelcastCachingProvider

java.lang.Object
com.hazelcast.cache.HazelcastCachingProvider
All Implemented Interfaces:
Closeable, AutoCloseable, javax.cache.spi.CachingProvider
public final class HazelcastCachingProvider extends 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 Details

    • HAZELCAST_CONFIG_LOCATION

      public static final String HAZELCAST_CONFIG_LOCATION
      Hazelcast config location property
      See Also:

    • HAZELCAST_INSTANCE_NAME

      public static final String HAZELCAST_INSTANCE_NAME
      Hazelcast instance name property
      See Also:

    • HAZELCAST_INSTANCE_ITSELF

      public static final String HAZELCAST_INSTANCE_ITSELF
      Hazelcast instance itself property
      See Also:

    • MEMBER_CACHING_PROVIDER

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

    • SERVER_CACHING_PROVIDER

      @Deprecated public static final 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 String CLIENT_CACHING_PROVIDER
      Class name of the client-side Caching Provider

    • SHARED_JCACHE_INSTANCE_NAME

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

  • Constructor Details

    • HazelcastCachingProvider

      public HazelcastCachingProvider()

  • Method Details

    • propertiesByLocation

      public static Properties propertiesByLocation(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 Properties propertiesByInstanceName(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 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(URI uri, ClassLoader classLoader, Properties properties)
      Specified by:
      getCacheManager in interface javax.cache.spi.CachingProvider

    • getDefaultClassLoader

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

    • getDefaultURI

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

    • getDefaultProperties

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

    • getCacheManager

      public javax.cache.CacheManager getCacheManager(URI uri, 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 AutoCloseable
      Specified by:
      close in interface javax.cache.spi.CachingProvider
      Specified by:
      close in interface Closeable

    • close

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

    • close

      public void close(URI uri, 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 String toString()
      Overrides:
      toString in class Object