public class CacheFactory extends Object
cache and connect to the GemFire
singleton distributed system. If the application wants to connect to
GemFire as a client it should use ClientCacheFactory instead.
Once the factory has been configured using its set(String, String) method you produce a
Cache by calling the create() method.
To get the existing unclosed singleton cache instance call getAnyInstance().
If an instance of DistributedSystem already exists when this factory creates a cache,
that instance will be used if it is compatible with this factory.
The following examples illustrate bootstrapping the cache using region shortcuts:
Example 1: Create a cache and a replicate region named customers.
Cache c = new CacheFactory().create();
Region r = c.createRegionFactory(REPLICATE).create("customers");
Example 2: Create a cache and a partition region with redundancy
Cache c = new CacheFactory().create();
Region r = c.createRegionFactory(PARTITION_REDUNDANT).create("customers");
Example 3: Construct the cache region declaratively in cache.xml
<!DOCTYPE cache PUBLIC
"-//GemStone Systems, Inc.//GemFire Declarative Caching 8.0//EN"
"http://www.gemstone.com/dtd/cache8_0.dtd">
<cache>
<region name="myRegion" refid="REPLICATE"/>
<!-- you can override or add to the REPLICATE attributes by adding
a region-attributes sub element here -->
</cache>
Now, create the cache telling it to read your cache.xml file:
Cache c = new CacheFactory().set("cache-xml-file", "myCache.xml").create();
Region r = c.getRegion("myRegion");
For a complete list of all region shortcuts see RegionShortcut. Applications that need to
explicitly control the individual region attributes can do this declaratively in XML or using
APIs.
| Constructor and Description |
|---|
CacheFactory()
Creates a default cache factory.
|
CacheFactory(Properties props)
Create a CacheFactory initialized with the given gemfire properties.
|
| Modifier and Type | Method and Description |
|---|---|
CacheFactory |
addMeterSubregistry(io.micrometer.core.instrument.MeterRegistry subregistry)
Adds the given meter registry to the cache's composite registry for publishing cache metrics
to external monitoring systems.
|
Cache |
create()
Creates a new cache that uses the configured distributed system.
|
static Cache |
create(DistributedSystem system)
Deprecated.
as of 6.5 use
CacheFactory(Properties) instead. |
static Cache |
getAnyInstance()
|
static Cache |
getInstance(DistributedSystem system)
|
static Cache |
getInstanceCloseOk(DistributedSystem system)
|
static String |
getVersion()
Returns the version of the cache implementation.
|
CacheFactory |
set(String name,
String value)
Sets a gemfire property that will be used when creating the Cache.
|
CacheFactory |
setPdxDiskStore(String diskStoreName)
Set the disk store that is used for PDX meta data.
|
CacheFactory |
setPdxIgnoreUnreadFields(boolean ignore)
Control whether pdx ignores fields that were unread during deserialization.
|
CacheFactory |
setPdxPersistent(boolean isPersistent)
Control whether the type metadata for PDX objects is persisted to disk.
|
CacheFactory |
setPdxReadSerialized(boolean readSerialized)
Sets the object preference to PdxInstance type.
|
CacheFactory |
setPdxSerializer(PdxSerializer serializer)
Set the PDX serializer for the cache.
|
CacheFactory |
setPostProcessor(PostProcessor postProcessor)
Sets the postProcessor for the cache.
|
CacheFactory |
setSecurityManager(SecurityManager securityManager)
Sets the securityManager for the cache.
|
public CacheFactory()
public CacheFactory(Properties props)
props - the gemfire properties to initialize the factory with.public Cache create() throws TimeoutException, CacheWriterException, GatewayException, RegionExistsException
If the cache does need to be created it will also be initialized from cache.xml if it exists.
CacheXmlException - If a problem occurs while parsing the declarative caching XML file.TimeoutException - If a Region.put(Object, Object) times out while initializing
the cache.CacheWriterException - If a CacheWriterException is thrown while initializing the
cache.GatewayException - If a GatewayException is thrown while initializing the cache.RegionExistsException - If the declarative caching XML file describes a region that
already exists (including the root region).IllegalStateException - if cache already exists and is not compatible with the new
configuration.AuthenticationFailedException - if authentication fails.AuthenticationRequiredException - if the distributed system is in secure mode and this
new member is not configured with security credentials.public CacheFactory set(String name, String value)
ConfigurationProperties.name - the name of the gemfire propertyvalue - the value of the gemfire propertypublic CacheFactory setPdxReadSerialized(boolean readSerialized)
PdxInstance will be returned instead of the actual domain
class. The PdxInstance is an interface that provides run time access to the fields of a PDX
without deserializing the entire PDX. The PdxInstance implementation is a light weight wrapper
that simply refers to the raw bytes of the PDX that are kept in the cache. Using this method
applications can choose to access PdxInstance instead of Java object.
Note that a PdxInstance is only returned if a serialized PDX is found in the cache. If the cache contains a deserialized PDX, then a domain class instance is returned instead of a PdxInstance.
readSerialized - true to prefer PdxInstancePdxInstancepublic CacheFactory setSecurityManager(SecurityManager securityManager)
securityManager - the securityManager for the cachepublic CacheFactory setPostProcessor(PostProcessor postProcessor)
postProcessor - the postProcessor for the cachepublic CacheFactory setPdxSerializer(PdxSerializer serializer)
serializer - the serializer to usePdxSerializerpublic CacheFactory setPdxDiskStore(String diskStoreName)
diskStoreName - the name of the disk store to use for the PDX metadata.public CacheFactory setPdxPersistent(boolean isPersistent)
GatewaySender or AsyncEventQueue with PDX then you should
set this to true.isPersistent - true if the metadata should be persistentpublic CacheFactory setPdxIgnoreUnreadFields(boolean ignore)
You should only set this attribute to true if you know this member will only be reading
cache data. In this use case you do not need to pay the cost of preserving the unread fields
since you will never be reserializing pdx data.
ignore - true if fields not read during pdx deserialization should be ignored;
false, the default, if they should be preserved.@Experimental(value="Micrometer metrics is a new addition to Geode and the API may change") public CacheFactory addMeterSubregistry(io.micrometer.core.instrument.MeterRegistry subregistry)
Example adding a meter sub-registry:
MeterRegistry prometheusRegistry = new PrometheusMeterRegistry(...);
Cache cache = new CacheFactory()
.addMeterSubregistry(prometheusRegistry)
.create();
Example adding multiple meter sub-registries:
MeterRegistry prometheusRegistry = new PrometheusMeterRegistry(...);
MeterRegistry influxRegistry = new InfluxMeterRegistry(...);
MeterRegistry newRelicRegistry = new NewRelicMeterRegistry(...);
Cache cache = new CacheFactory()
.addMeterSubregistry(prometheusRegistry)
.addMeterSubregistry(influxRegistry)
.addMeterSubregistry(newRelicRegistry)
.create();
Experimental: Micrometer metrics is a new addition to Geode and the API may change.
subregistry - the registry to add@Deprecated public static Cache create(DistributedSystem system) throws CacheExistsException, TimeoutException, CacheWriterException, GatewayException, RegionExistsException
CacheFactory(Properties) instead.system.
The system can specify a
"cache-xml-file" property
which will cause this creation to also create the regions, objects, and attributes declared in
the file. The contents of the file must comply with the "doc-files/cache8_0.dtd"> file.
Note that when parsing the XML file Declarable classes are loaded using the current
thread's context class loader.
system - a DistributedSystem obtained by calling
DistributedSystem.connect(java.util.Properties).Cache that uses the specified system for distribution.IllegalArgumentException - If system is not connected.CacheExistsException - If an open cache already exists.CacheXmlException - If a problem occurs while parsing the declarative caching XML file.TimeoutException - If a Region.put(Object, Object) times out while initializing
the cache.CacheWriterException - If a CacheWriterException is thrown while initializing the
cache.GatewayException - If a GatewayException is thrown while initializing the cache.RegionExistsException - If the declarative caching XML file describes a region that
already exists (including the root region).public static Cache getInstance(DistributedSystem system)
system - the DistributedSystem the cache was created with.Cache associated with the specified system.CacheClosedException - if a cache has not been created or the created one is
closedpublic static Cache getInstanceCloseOk(DistributedSystem system)
system - the DistributedSystem the cache was created with.Cache associated with the specified system.CacheClosedException - if a cache has not been createdpublic static Cache getAnyInstance()
Cache produced by an earlier call to
create().
WARNING: To avoid risk of deadlock, do not invoke getAnyInstance() from within any CacheCallback including CacheListener, CacheLoader, CacheWriter, TransactionListener, TransactionWriter. Instead use EntryEvent.getRegion().getCache(), RegionEvent.getRegion().getCache(), LoaderHelper.getRegion().getCache(), or TransactionEvent.getCache().
Cache produced by an earlier call to
create()CacheClosedException - if a cache has not been created or the only created one is
closedpublic static String getVersion()
String