com.gemstone.gemfire.cache
Class CacheFactory

java.lang.Object
  com.gemstone.gemfire.cache.CacheFactory

public class CacheFactory
extends Object

Factory class used to create the singleton cache and connect to GemFire the 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 6.5//EN"
    "http://www.gemstone.com/dtd/cache6_5.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.

Since:

3.0

Constructor Summary

CacheFactory()
Creates a default cache factory.

CacheFactory(Properties props)
Create a CacheFactory initialized with the given gemfire properties.

Method Summary

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() Gets an arbitrary open instance of Cache produced by an earlier call to create().
static Cache	getInstance(DistributedSystem system) Gets the instance of Cache produced by an earlier call to create().
static Cache	getInstanceCloseOk(DistributedSystem system) Gets the instance of Cache produced by an earlier call to create() even if it has been closed.
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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CacheFactory

public CacheFactory()

Creates a default cache factory.

Since:

6.5

CacheFactory

public CacheFactory(Properties props)

Create a CacheFactory initialized with the given gemfire properties. For a list of valid gemfire properties see DistributedSystem.

Parameters:

props - the gemfire properties to initialize the factory with.

Since:

6.5

Method Detail

set

public CacheFactory set(String name,
                        String value)

Sets a gemfire property that will be used when creating the Cache. For a list of valid gemfire properties see DistributedSystem.

Parameters:

name - the name of the gemfire property

value - the value of the gemfire property

Returns:

a reference to this CacheFactory object

Since:

6.5

create

@Deprecated
public static Cache create(DistributedSystem system)
                    throws CacheExistsException,
                           TimeoutException,
                           CacheWriterException,
                           GatewayException,
                           RegionExistsException

Deprecated. as of 6.5 use CacheFactory(Properties) instead.

Creates a new cache that uses the specified 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/cache6_5.dtd"> file. Note that when parsing the XML file Declarable classes are loaded using the current thread's context class loader.

Parameters:

system - a DistributedSystem obtained by calling DistributedSystem.connect(java.util.Properties).

Returns:

a Cache that uses the specified system for distribution.

Throws:

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).

create

public Cache create()
             throws TimeoutException,
                    CacheWriterException,
                    GatewayException,
                    RegionExistsException

Creates a new cache that uses the configured distributed system. If a connected distributed system already exists it will be used if it is compatible with the properties on this factory. Otherwise a a distributed system will be created with the configured properties. If a cache already exists it will be returned.

If the cache does need to be created it will also be initialized from cache.xml if it exists.

Returns:

the created or already existing singleton cache

Throws:

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).

Since:

6.5

getInstance

public static Cache getInstance(DistributedSystem system)

Gets the instance of Cache produced by an earlier call to create().

Parameters:

system - the DistributedSystem the cache was created with.

Returns:

the Cache associated with the specified system.

Throws:

CacheClosedException - if a cache has not been created or the created one is closed

getInstanceCloseOk

public static Cache getInstanceCloseOk(DistributedSystem system)

Gets the instance of Cache produced by an earlier call to create() even if it has been closed.

Parameters:

system - the DistributedSystem the cache was created with.

Returns:

the Cache associated with the specified system.

Throws:

CacheClosedException - if a cache has not been created

Since:

3.5

getAnyInstance

public static Cache getAnyInstance()

Gets an arbitrary open instance of Cache produced by an earlier call to create().

Throws:

CacheClosedException - if a cache has not been created or the only created one is closed

getVersion

public static String getVersion()

Returns the version of the cache implementation.

Returns:

the version of the cache implementation as a String