org.apache.geode.cache.client

## Interface ClientRegionFactory<K,V>

-     public interface ClientRegionFactory<K,V>

  A factory for constructing `client cache` `regions`. Instances of this interface can be created using region shortcuts by calling `ClientCache.createClientRegionFactory(ClientRegionShortcut)` or using named region attributes by calling `ClientCache.createClientRegionFactory(String)`.

  The factory can then be customized using its methods.

  The final step is to produce a `Region` by calling `create(String)`.

  Client regions may be:

  - PROXY: which pass through to server and have no local data.
  - CACHING_PROXY: which fetch data from servers and cache it locally.
  - LOCAL: which only have local data; they do not communicate with the servers.
  See `ClientRegionShortcut` for the shortcuts for these three types of client regions.

  Example: Create a client region with a CacheListener

       ClientCache c = new ClientCacheFactory().addLocator(host, port).create();
       // Create local caching region that is connected to a server side region
       // Add a cache listener before creating region
       Region r =
           c.createClientRegionFactory(CACHING_PROXY).addCacheListener(myListener).create("customers");

  Since:
    GemFire 6.5

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `ClientRegionFactory<K,V>` | `addCacheListener(CacheListener<K,V> aListener)` Adds a cache listener to the end of the list of cache listeners on this factory.
    `Region<K,V>` | `create(java.lang.String name)` Creates a region in the `ClientCache` using the configuration contained in this ClientRegionFactory.
    `Region<K,V>` | `createSubregion(Region<?,?> parent, java.lang.String name)` Creates a sub-region in the `ClientCache` using the configuration contained in this ClientRegionFactory.
    `ClientRegionFactory<K,V>` | `initCacheListeners(CacheListener<K,V>[] newListeners)` Removes all cache listeners and then adds each listener in the specified array.
    `ClientRegionFactory<K,V>` | `setCloningEnabled(boolean cloningEnable)` Sets cloning on region Note: off-heap regions always behave as if cloning is enabled.
    `ClientRegionFactory<K,V>` | `setCompressor(Compressor compressor)` Set the compressor to be used by this region for compressing region entry values.
    `void` | `setConcurrencyChecksEnabled(boolean concurrencyChecksEnabled)` Enables or disabled concurrent modification checks
    `ClientRegionFactory<K,V>` | `setConcurrencyLevel(int concurrencyLevel)` Sets the concurrency level tof the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setCustomEntryIdleTimeout(CustomExpiry<K,V> custom)` Sets the custom idleTimeout for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setCustomEntryTimeToLive(CustomExpiry<K,V> custom)` Sets the custom timeToLive expiration method for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setDiskStoreName(java.lang.String name)` Sets the DiskStore name attribute.
    `ClientRegionFactory<K,V>` | `setDiskSynchronous(boolean isSynchronous)` Sets whether or not the writing to the disk is synchronous.
    `ClientRegionFactory<K,V>` | `setEntryIdleTimeout(ExpirationAttributes idleTimeout)` Sets the idleTimeout expiration attributes for region entries for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setEntryTimeToLive(ExpirationAttributes timeToLive)` Sets the timeToLive expiration attributes for region entries for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setEvictionAttributes(EvictionAttributes evictionAttributes)` Sets the eviction attributes that controls growth of the Region to be created.
    `ClientRegionFactory<K,V>` | `setInitialCapacity(int initialCapacity)` Sets the entry initial capacity for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setKeyConstraint(java.lang.Class<K> keyConstraint)` Sets the key constraint for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setLoadFactor(float loadFactor)` Sets the entry load factor for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setPoolName(java.lang.String poolName)` Sets the pool name attribute.
    `ClientRegionFactory<K,V>` | `setRegionIdleTimeout(ExpirationAttributes idleTimeout)` Sets the idleTimeout expiration attributes for the region itself for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setRegionTimeToLive(ExpirationAttributes timeToLive)` Sets the timeToLive expiration attributes for the region itself for the next `RegionAttributes` created.
    `ClientRegionFactory<K,V>` | `setStatisticsEnabled(boolean statisticsEnabled)` Sets whether statistics are enabled for this region and its entries.
    `ClientRegionFactory<K,V>` | `setValueConstraint(java.lang.Class<V> valueConstraint)` Sets the value constraint for the next `RegionAttributes` created.

- - ### Method Detail

    - #### addCacheListener

          ClientRegionFactory<K,V> addCacheListener(CacheListener<K,V> aListener)

      Adds a cache listener to the end of the list of cache listeners on this factory.
      Parameters:
        `aListener` - the cache listener to add
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if `aListener` is null
      See Also:
        `AttributesFactory.addCacheListener(org.apache.geode.cache.CacheListener<K, V>)`

    - #### initCacheListeners

          ClientRegionFactory<K,V> initCacheListeners(CacheListener<K,V>[] newListeners)

      Removes all cache listeners and then adds each listener in the specified array. for the next `RegionAttributes` created.
      Parameters:
        `newListeners` - a possibly null or empty array of listeners to add to this factory.
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if the `newListeners` array has a null element
      See Also:
        `AttributesFactory.initCacheListeners(org.apache.geode.cache.CacheListener<K, V>[])`

    - #### setEvictionAttributes

          ClientRegionFactory<K,V> setEvictionAttributes(EvictionAttributes evictionAttributes)

      Sets the eviction attributes that controls growth of the Region to be created.
      Parameters:
        `evictionAttributes` - for the Region to create
      Returns:
        a reference to this ClientRegionFactory object

    - #### setEntryIdleTimeout

          ClientRegionFactory<K,V> setEntryIdleTimeout(ExpirationAttributes idleTimeout)

      Sets the idleTimeout expiration attributes for region entries for the next `RegionAttributes` created.
      Parameters:
        `idleTimeout` - the idleTimeout ExpirationAttributes for entries in this region
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if idleTimeout is null
      See Also:
        `AttributesFactory.setEntryIdleTimeout(org.apache.geode.cache.ExpirationAttributes)`

    - #### setCustomEntryIdleTimeout

          ClientRegionFactory<K,V> setCustomEntryIdleTimeout(CustomExpiry<K,V> custom)

      Sets the custom idleTimeout for the next `RegionAttributes` created.
      Parameters:
        `custom` - the custom method
      Returns:
        the receiver
      See Also:
        `AttributesFactory.setCustomEntryIdleTimeout(CustomExpiry)`

    - #### setEntryTimeToLive

          ClientRegionFactory<K,V> setEntryTimeToLive(ExpirationAttributes timeToLive)

      Sets the timeToLive expiration attributes for region entries for the next `RegionAttributes` created.
      Parameters:
        `timeToLive` - the timeToLive ExpirationAttributes for entries in this region
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if timeToLive is null
      See Also:
        `AttributesFactory.setEntryTimeToLive(org.apache.geode.cache.ExpirationAttributes)`

    - #### setCustomEntryTimeToLive

          ClientRegionFactory<K,V> setCustomEntryTimeToLive(CustomExpiry<K,V> custom)

      Sets the custom timeToLive expiration method for the next `RegionAttributes` created.
      Parameters:
        `custom` - the custom method
      Returns:
        the receiver
      See Also:
        `AttributesFactory.setCustomEntryTimeToLive(CustomExpiry)`

    - #### setRegionIdleTimeout

          ClientRegionFactory<K,V> setRegionIdleTimeout(ExpirationAttributes idleTimeout)

      Sets the idleTimeout expiration attributes for the region itself for the next `RegionAttributes` created.
      Parameters:
        `idleTimeout` - the ExpirationAttributes for this region idleTimeout
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if idleTimeout is null
      See Also:
        `AttributesFactory.setRegionIdleTimeout(org.apache.geode.cache.ExpirationAttributes)`

    - #### setRegionTimeToLive

          ClientRegionFactory<K,V> setRegionTimeToLive(ExpirationAttributes timeToLive)

      Sets the timeToLive expiration attributes for the region itself for the next `RegionAttributes` created.
      Parameters:
        `timeToLive` - the ExpirationAttributes for this region timeToLive
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if timeToLive is null
      See Also:
        `AttributesFactory.setRegionTimeToLive(org.apache.geode.cache.ExpirationAttributes)`

    - #### setKeyConstraint

          ClientRegionFactory<K,V> setKeyConstraint(java.lang.Class<K> keyConstraint)

      Sets the key constraint for the next `RegionAttributes` created. Keys in the region will be constrained to this class (or subclass). Any attempt to store a key of an incompatible type in the region will cause a `ClassCastException` to be thrown.
      Parameters:
        `keyConstraint` - The Class to constrain the keys to, or null if no constraint
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if `keyConstraint` is a class denoting a primitive type
      See Also:
        `AttributesFactory.setKeyConstraint(java.lang.Class<K>)`

    - #### setValueConstraint

          ClientRegionFactory<K,V> setValueConstraint(java.lang.Class<V> valueConstraint)

      Sets the value constraint for the next `RegionAttributes` created. Values in the region will be constrained to this class (or subclass). Any attempt to store a value of an incompatible type in the region will cause a `ClassCastException` to be thrown.
      Parameters:
        `valueConstraint` - The Class to constrain the values to, or null if no constraint
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if `valueConstraint` is a class denoting a primitive type
      See Also:
        `AttributesFactory.setValueConstraint(java.lang.Class<V>)`

    - #### setInitialCapacity

          ClientRegionFactory<K,V> setInitialCapacity(int initialCapacity)

      Sets the entry initial capacity for the next `RegionAttributes` created. This value is used in initializing the map that holds the entries.
      Parameters:
        `initialCapacity` - the initial capacity of the entry map
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if initialCapacity is negative.
      See Also:
        `HashMap`, `AttributesFactory.setInitialCapacity(int)`

    - #### setLoadFactor

          ClientRegionFactory<K,V> setLoadFactor(float loadFactor)

      Sets the entry load factor for the next `RegionAttributes` created. This value is used in initializing the map that holds the entries.
      Parameters:
        `loadFactor` - the load factor of the entry map
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if loadFactor is nonpositive
      See Also:
        `HashMap`, `AttributesFactory.setLoadFactor(float)`

    - #### setConcurrencyLevel

          ClientRegionFactory<K,V> setConcurrencyLevel(int concurrencyLevel)

      Sets the concurrency level tof the next `RegionAttributes` created. This value is used in initializing the map that holds the entries.
      Parameters:
        `concurrencyLevel` - the concurrency level of the entry map
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalArgumentException` - if concurrencyLevel is nonpositive
      See Also:
        `AttributesFactory.setConcurrencyLevel(int)`

    - #### setConcurrencyChecksEnabled

          void setConcurrencyChecksEnabled(boolean concurrencyChecksEnabled)

      Enables or disabled concurrent modification checks
      Parameters:
        `concurrencyChecksEnabled` - whether to perform concurrency checks on operations
      Since:
        GemFire 7.0

    - #### setDiskStoreName

          ClientRegionFactory<K,V> setDiskStoreName(java.lang.String name)

      Sets the DiskStore name attribute. This causes the region to belong to the DiskStore.
      Parameters:
        `name` - the name of the diskstore
      Returns:
        a reference to this ClientRegionFactory object
      See Also:
        `AttributesFactory.setDiskStoreName(java.lang.String)`

    - #### setDiskSynchronous

          ClientRegionFactory<K,V> setDiskSynchronous(boolean isSynchronous)

      Sets whether or not the writing to the disk is synchronous.
      Parameters:
        `isSynchronous` - boolean if true indicates synchronous writes
      Returns:
        a reference to this ClientRegionFactory object

    - #### setStatisticsEnabled

          ClientRegionFactory<K,V> setStatisticsEnabled(boolean statisticsEnabled)

      Sets whether statistics are enabled for this region and its entries.
      Parameters:
        `statisticsEnabled` - whether statistics are enabled
      Returns:
        a reference to this ClientRegionFactory object
      See Also:
        `AttributesFactory.setStatisticsEnabled(boolean)`

    - #### setCloningEnabled

          ClientRegionFactory<K,V> setCloningEnabled(boolean cloningEnable)

      Sets cloning on region Note: off-heap regions always behave as if cloning is enabled.
      Parameters:
        `cloningEnable` -
      Returns:
        a reference to this ClientRegionFactory object
      See Also:
        `AttributesFactory.setCloningEnabled(boolean)`

    - #### setPoolName

          ClientRegionFactory<K,V> setPoolName(java.lang.String poolName)

      Sets the pool name attribute. This causes regions that use these attributes to be a client region which communicates with the servers that the connection pool communicates with.

      The named connection pool must exist on the cache at the time these attributes are used to create a region. See `PoolManager.createFactory()` for how to create a connection pool.

      Parameters:
        `poolName` - the name of the connection pool to use
      Returns:
        a reference to this ClientRegionFactory object
      Throws:
        `java.lang.IllegalStateException` - if a cache loader or cache writer has already been set.
      See Also:
        `PoolManager`

    - #### setCompressor

          ClientRegionFactory<K,V> setCompressor(Compressor compressor)

      Set the compressor to be used by this region for compressing region entry values.
      Parameters:
        `compressor` - a compressor
      Returns:
        a reference to this RegionFactory instance
      Since:
        GemFire 8.0

    - #### create

          Region<K,V> create(java.lang.String name)
                      throws RegionExistsException

      Creates a region in the `ClientCache` using the configuration contained in this ClientRegionFactory. Validation of the provided attributes may cause exceptions to be thrown if there are problems with the configuration data.
      Parameters:
        `name` - the name of the region to create
      Returns:
        the region object
      Throws:
        `RegionExistsException` - if a region with the given name already exists in this cache
        `CacheClosedException` - if the cache is closed

    - #### createSubregion

          Region<K,V> createSubregion(Region<?,?> parent,
                                      java.lang.String name)
                               throws RegionExistsException

      Creates a sub-region in the `ClientCache` using the configuration contained in this ClientRegionFactory. Validation of the provided attributes may cause exceptions to be thrown if there are problems with the configuration data.
      Parameters:
        `parent` - the existing region that will contain the created sub-region
        `name` - the name of the region to create
      Returns:
        the region object
      Throws:
        `RegionExistsException` - if a region with the given name already exists in this cache
        `RegionDestroyedException` - if the parent region has been closed or destroyed
        `CacheClosedException` - if the cache is closed
      Since:
        GemFire 7.0