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:

  • com.hazelcast.cache.impl.HazelcastServerCachingProvider is the member-side CachingProvider implementation
  • com.hazelcast.client.cache.impl.HazelcastClientCachingProvider is the client-side CachingProvider implementation

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 server selects the member-side caching provider, while value client selects the client-side provider. Other values result in a CacheException being thrown.

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

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 "server". 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", "server");
 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