Class 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, will locate the configuration from the given HTTP URL.
  • Property 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).


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();
 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");