com.gemstone.gemfire.cache.client.ClientRegionFactory Maven / Gradle / Ivy
/*
* Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you
* may not use this file except in compliance with the License. You
* may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
* implied. See the License for the specific language governing
* permissions and limitations under the License. See accompanying
* LICENSE file.
*/
package com.gemstone.gemfire.cache.client;
import com.gemstone.gemfire.cache.AttributesFactory;
import com.gemstone.gemfire.cache.CacheClosedException;
import com.gemstone.gemfire.cache.CacheListener;
import com.gemstone.gemfire.cache.CustomExpiry;
import com.gemstone.gemfire.cache.EvictionAttributes;
import com.gemstone.gemfire.cache.EvictionCriteria;
import com.gemstone.gemfire.cache.ExpirationAttributes;
import com.gemstone.gemfire.cache.Region;
import com.gemstone.gemfire.cache.RegionDestroyedException;
import com.gemstone.gemfire.cache.RegionExistsException;
import com.gemstone.gemfire.compression.Compressor;
/**
* A factory for constructing {@link ClientCache client cache} {@link Region
* regions}. Instances of this interface can be created using region shortcuts
* by calling
* {@link ClientCache#createClientRegionFactory(ClientRegionShortcut)} or using
* named region attributes by calling
* {@link ClientCache#createClientRegionFactory(String)}.
*
* The factory can then be customized using its methods.
*
* The final step is to produce a {@link Region} by calling
* {@link #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 {@link 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");
*
*
* @author darrel
* @since 6.5
*/
public interface ClientRegionFactory {
/**
* Adds a cache listener to the end of the list of cache listeners on this factory.
* @param aListener the cache listener to add
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException if aListener is null
* @see AttributesFactory#addCacheListener
*/
public ClientRegionFactory addCacheListener(CacheListener aListener);
/**
* Removes all cache listeners and then adds each listener in the specified array.
* for the next RegionAttributes created.
* @param newListeners a possibly null or empty array of listeners to add to this factory.
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException if the newListeners array has a null element
* @see AttributesFactory#initCacheListeners
*/
public ClientRegionFactory initCacheListeners(CacheListener[] newListeners);
/**
* Sets the eviction attributes that controls growth of the Region to be created.
*
* @param evictionAttributes for the Region to create
* @return a reference to this ClientRegionFactory object
*/
public ClientRegionFactory setEvictionAttributes(EvictionAttributes evictionAttributes);
/**
* Set custom {@link EvictionCriteria} for the region with start time and
* interval of evictor task to be run in milliseconds, or evict incoming rows
* in case both start and frequency are specified as zero.
*
* @param criteria
* an {@link EvictionCriteria} to be used for eviction for HDFS
* persistent regions
* @param start
* the start time at which periodic evictor task should be first
* fired to apply the provided {@link EvictionCriteria}; if this is
* zero then current time is used for the first invocation of evictor
* @param interval
* the periodic frequency at which to run the evictor task after the
* initial start; if this is if both start and frequency are zero
* then {@link EvictionCriteria} is applied on incoming insert/update
* to determine whether it is to be retained
*/
public ClientRegionFactory setCustomEvictionAttributes(
EvictionCriteria criteria, long start, long interval);
/**
* Sets the idleTimeout expiration attributes for region entries for the next
* RegionAttributes created.
*
* @param idleTimeout
* the idleTimeout ExpirationAttributes for entries in this region
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException
* if idleTimeout is null
* @see AttributesFactory#setEntryIdleTimeout
*/
public ClientRegionFactory setEntryIdleTimeout(ExpirationAttributes idleTimeout);
/**
* Sets the custom idleTimeout for the next RegionAttributes
* created.
*
* @param custom the custom method
* @return the receiver
* @see AttributesFactory#setCustomEntryIdleTimeout(CustomExpiry)
*/
public ClientRegionFactory setCustomEntryIdleTimeout(CustomExpiry custom);
/**
* Sets the timeToLive expiration attributes for region entries for the next
* RegionAttributes created.
*
* @param timeToLive
* the timeToLive ExpirationAttributes for entries in this region
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException
* if timeToLive is null
* @see AttributesFactory#setEntryTimeToLive
*/
public ClientRegionFactory setEntryTimeToLive(ExpirationAttributes timeToLive);
/**
* Sets the custom timeToLive expiration method for the next
* RegionAttributes created.
* @param custom the custom method
* @return the receiver
* @see AttributesFactory#setCustomEntryTimeToLive(CustomExpiry)
*/
public ClientRegionFactory setCustomEntryTimeToLive(CustomExpiry custom);
/**
* Sets the idleTimeout expiration attributes for the region itself for the
* next RegionAttributes created.
*
* @param idleTimeout
* the ExpirationAttributes for this region idleTimeout
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException
* if idleTimeout is null
* @see AttributesFactory#setRegionIdleTimeout
*/
public ClientRegionFactory setRegionIdleTimeout(ExpirationAttributes idleTimeout);
/**
* Sets the timeToLive expiration attributes for the region itself for the
* next RegionAttributes created.
*
* @param timeToLive
* the ExpirationAttributes for this region timeToLive
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException
* if timeToLive is null
* @see AttributesFactory#setRegionTimeToLive
*/
public ClientRegionFactory setRegionTimeToLive(ExpirationAttributes timeToLive);
/**
* 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.
*
* @param keyConstraint
* The Class to constrain the keys to, or null if no constraint
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException
* if keyConstraint is a class denoting a primitive
* type
* @see AttributesFactory#setKeyConstraint
*/
public ClientRegionFactory setKeyConstraint(Class keyConstraint);
/**
* 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.
*
* @param valueConstraint
* The Class to constrain the values to, or null if no constraint
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException
* if valueConstraint is a class denoting a primitive
* type
* @see AttributesFactory#setValueConstraint
*/
public ClientRegionFactory setValueConstraint(Class valueConstraint);
/**
* Sets the entry initial capacity for the next RegionAttributes
* created. This value is used in initializing the map that holds the entries.
*
* @param initialCapacity
* the initial capacity of the entry map
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException if initialCapacity is negative.
* @see java.util.HashMap
* @see AttributesFactory#setInitialCapacity
*/
public ClientRegionFactory setInitialCapacity(int initialCapacity);
/**
* Sets the entry load factor for the next RegionAttributes
* created. This value is used in initializing the map that holds the entries.
*
* @param loadFactor
* the load factor of the entry map
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException
* if loadFactor is nonpositive
* @see java.util.HashMap
* @see AttributesFactory#setLoadFactor
*/
public ClientRegionFactory setLoadFactor(float loadFactor);
/**
* Sets the concurrency level tof the next RegionAttributes
* created. This value is used in initializing the map that holds the entries.
*
* @param concurrencyLevel
* the concurrency level of the entry map
* @return a reference to this ClientRegionFactory object
* @throws IllegalArgumentException
* if concurrencyLevel is nonpositive
* @see AttributesFactory#setConcurrencyLevel
*/
public ClientRegionFactory setConcurrencyLevel(int concurrencyLevel);
/**
* Enables or disabled concurrent modification checks
* @since 7.0
* @param concurrencyChecksEnabled whether to perform concurrency checks on operations
*/
public void setConcurrencyChecksEnabled(boolean concurrencyChecksEnabled);
/**
* Sets the DiskStore name attribute.
* This causes the region to belong to the DiskStore.
* @param name the name of the diskstore
* @return a reference to this ClientRegionFactory object
*
* @see AttributesFactory#setDiskStoreName
*/
public ClientRegionFactory setDiskStoreName(String name);
/**
* Sets whether or not the writing to the disk is synchronous.
*
* @param isSynchronous
* boolean if true indicates synchronous writes
* @return a reference to this ClientRegionFactory object
*/
public ClientRegionFactory setDiskSynchronous(boolean isSynchronous);
/**
* Sets whether statistics are enabled for this region and its entries.
*
* @param statisticsEnabled
* whether statistics are enabled
* @return a reference to this ClientRegionFactory object
* @see AttributesFactory#setStatisticsEnabled
*/
public ClientRegionFactory setStatisticsEnabled(boolean statisticsEnabled);
/**
* Sets cloning on region
* @param cloningEnable
* @return a reference to this ClientRegionFactory object
* @see AttributesFactory#setCloningEnabled
*/
public ClientRegionFactory setCloningEnabled(boolean cloningEnable);
/**
* 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 {@link PoolManager#createFactory}
* for how to create a connection pool.
* @param poolName the name of the connection pool to use
* @return a reference to this ClientRegionFactory object
* @throws IllegalStateException if a cache loader or cache writer has already
* been set.
* @see PoolManager
*/
public ClientRegionFactory setPoolName(String poolName);
/**
* Set the compressor to be used by this region for compressing
* region entry values.
* @param compressor a compressor
* @return a reference to this RegionFactory instance
* @since 7.5
*/
public ClientRegionFactory setCompressor(Compressor compressor);
/**
* Creates a region in the {@link 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.
*
* @param name
* the name of the region to create
*
* @return the region object
* @throws RegionExistsException
* if a region with the given name already exists in this cache
* @throws CacheClosedException
* if the cache is closed
*/
public Region create(String name) throws RegionExistsException;
/**
* Creates a sub-region in the {@link 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.
*
* @param parent
* the existing region that will contain the created sub-region
* @param name
* the name of the region to create
*
* @return the region object
* @throws RegionExistsException
* if a region with the given name already exists in this cache
* @throws RegionDestroyedException
* if the parent region has been closed or destroyed
* @throws CacheClosedException
* if the cache is closed
* @since 7.0
*/
public Region createSubregion(Region parent, String name) throws RegionExistsException;
}