CacheFactory (Apache Geode 1.4.0)
Date: 2018-01-29

org.apache.geode.cache

## Class CacheFactory

- java.lang.Object
- - org.apache.geode.cache.CacheFactory

-     public class CacheFactory
      extends java.lang.Object

  Factory class used to create the singleton `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.

  Since:
    GemFire 3.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CacheFactory()` Creates a default cache factory.
    `CacheFactory(java.util.Properties props)` Create a CacheFactory initialized with the given gemfire properties.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 java.lang.String` | `getVersion()` Returns the version of the cache implementation.
    `CacheFactory` | `set(java.lang.String name, java.lang.String value)` Sets a gemfire property that will be used when creating the Cache.
    `CacheFactory` | `setPdxDiskStore(java.lang.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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CacheFactory

          public CacheFactory()

      Creates a default cache factory.
      Since:
        GemFire 6.5

    - #### CacheFactory

          public CacheFactory(java.util.Properties props)

      Create a CacheFactory initialized with the given gemfire properties. For a list of valid GemFire properties and their meanings see ConfigurationProperties.
      Parameters:
        `props` - the gemfire properties to initialize the factory with.
      Since:
        GemFire 6.5

  - ### Method Detail

    - #### set

          public CacheFactory set(java.lang.String name,
                                  java.lang.String value)

      Sets a gemfire property that will be used when creating the Cache. For a list of valid GemFire properties and their meanings see `ConfigurationProperties`.
      Parameters:
        `name` - the name of the gemfire property
        `value` - the value of the gemfire property
      Returns:
        a reference to this CacheFactory object
      Since:
        GemFire 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/cache8_0.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:
        `java.lang.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).
        `java.lang.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.
      Since:
        GemFire 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:
        GemFire 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 java.lang.String getVersion()

      Returns the version of the cache implementation.
      Returns:
        the version of the cache implementation as a `String`

    - #### setPdxReadSerialized

          public CacheFactory setPdxReadSerialized(boolean readSerialized)

      Sets the object preference to PdxInstance type. When a cached object that was serialized as a PDX is read from the cache a `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.

      Parameters:
        `readSerialized` - true to prefer PdxInstance
      Returns:
        this CacheFactory
      Since:
        GemFire 6.6
      See Also:
        `PdxInstance`

    - #### setSecurityManager

          public CacheFactory setSecurityManager(SecurityManager securityManager)

      Sets the securityManager for the cache. If this securityManager is set, it will override the security-manager property you set in your gemfire system properties. This is provided mostly for container to inject an already initialized securityManager. An object provided this way is expected to be initialized already. We are not calling the init method on this object
      Returns:
        this CacheFactory

    - #### setPostProcessor

          public CacheFactory setPostProcessor(PostProcessor postProcessor)

      Sets the postProcessor for the cache. If this postProcessor is set, it will override the security-post-processor setting in the gemfire system properties. This is provided mostly for container to inject an already initialized post processor. An object provided this way is expected to be initialized already. We are not calling the init method on this object
      Returns:
        this CacheFactory

    - #### setPdxSerializer

          public CacheFactory setPdxSerializer(PdxSerializer serializer)

      Set the PDX serializer for the cache. If this serializer is set, it will be consulted to see if it can serialize any domain classes which are added to the cache in portable data exchange format.
      Parameters:
        `serializer` - the serializer to use
      Returns:
        this CacheFactory
      Since:
        GemFire 6.6
      See Also:
        `PdxSerializer`

    - #### setPdxDiskStore

          public CacheFactory setPdxDiskStore(java.lang.String diskStoreName)

      Set the disk store that is used for PDX meta data. When serializing objects in the PDX format, the type definitions are persisted to disk. This setting controls which disk store is used for that persistence. If not set, the metadata will go in the default disk store.
      Parameters:
        `diskStoreName` - the name of the disk store to use for the PDX metadata.
      Returns:
        this CacheFactory
      Since:
        GemFire 6.6

    - #### setPdxPersistent

          public CacheFactory setPdxPersistent(boolean isPersistent)

      Control whether the type metadata for PDX objects is persisted to disk. The default for this setting is false. If you are using persistent regions with PDX then you must set this to true. If you are using a `GatewaySender` or `AsyncEventQueue` with PDX then you should set this to true.
      Parameters:
        `isPersistent` - true if the metadata should be persistent
      Returns:
        this CacheFactory
      Since:
        GemFire 6.6

    - #### setPdxIgnoreUnreadFields

          public CacheFactory setPdxIgnoreUnreadFields(boolean ignore)

      Control whether pdx ignores fields that were unread during deserialization. The default is to preserve unread fields be including their data during serialization. But if you configure the cache to ignore unread fields then their data will be lost during serialization.

      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.

      Parameters:
        `ignore` - `true` if fields not read during pdx deserialization should be ignored; `false`, the default, if they should be preserved.
      Returns:
        this CacheFactory
      Since:
        GemFire 6.6