com.gemstone.gemfire.cache.util
Class BridgeWriter

java.lang.Object
  com.gemstone.gemfire.cache.util.BridgeWriter

All Implemented Interfaces:

CacheCallback, CacheWriter, Declarable

Direct Known Subclasses:

BridgeClient

public class BridgeWriter
extends Object
implements CacheWriter, Declarable

A CacheWriter that writes data to one or more remote CacheServer processes. This allows for a hierarchical caching scheme in which one cache ('client' cache) delegates a request to another cache ('server' cache). When using the BridgeWriter, at least two GemFire Caches must exist in a client/server mode (they should not be part of the same distributed system). The 'server' cache must be running a gemfire CacheServer process, while the 'client' cache must have a BridgeWriter installed in one or more of its Regions. If a BridgeWriter is defined in a client Region, there must also be a Region defined in the 'server' cache with the same exact name.

The BridgeWriter performs put() operations on the remote server cache, and does not provide the distribution behavior that can be enabled by using a DISTRIBUTED or DISTRIBUTED_NO_ACK Region. This mechanism is designed as a more targeted alternative to netSearch, in which the 'client' cache completely delegates the loading of the data to the 'server' cache if it is not yet cached in the client. This directed behavior enables a remote network put() operation to be performed much more efficiently in a scenario where there is a hierarchical cache topology. Updates and invalidation remain local, in fact the Regions that are used for this loosely coupled cache may even be LOCAL in scope. The BridgeWriter may be used to configure caches with multi-layer hierarchies.

Load Balancing:

The BridgeWriter supports these load balancing mechanisms (specified by the LBPolicy config attribute):

• Sticky
  In this mode, the client writer picks the first server from the list of servers and establishes a connection to it. Once this connection has been established, every request from that particular 'client' cache is sent on that connection. If requests time out or produce exceptions, the BridgeWriter picks another server and then sends further requests to that server. This achieves a level of load balancing by redirecting requests away from servers that produce timeouts.
• RandomSticky
  The behavior is the same as Sticky, however the initial assignment of the connection is randomly selected from the list of servers.
• RoundRobin
  In this mode, the client establishes connections to all the servers in the server list and then randomly picks a server for each given request. For the next request, it picks the next server in the list.
• Random :
  In this mode, the edge establishes connections to all the servers in the server list and then randomly picks a server for every request.

Failover:

If a remote server cache throws an exception or times out, the client will retry based on the configured retryCount parameter. If the retryCount is exceeded, the server in question will be added to a failed server list, and the client will select another server to connect to. The servers in the failed server list will be periodically pinged with an intelligent ping that ensures cache health. If a server is determined to be healthy again, it will be promoted back to the healthy server list. The time period between failed server pings is configurable via the retryInterval parameter.

Configuration:

The BridgeWriter is configurable declaratively or programmatically. Declarative configuration is achieved through defining the configuration parameters in a cache.xml file. Programmatic configuration may be achieved by first instantiating a BridgeWriter object and subsequently calling init(Properties)with a Properties object containing each desired parameter and value.

The supported parameters are:

• endpoints (required)
  A comma delimited list of logical names, hostnames, and ports of 'server' caches to connect to
  The endpoints parameter follows this syntax: logicalName=host:port,logicalName2=host2:port2,....
  Example:

  
   <parameter name="endpoints">
     <string>MyPrimaryServer=hostsrv:40404,MySecondary=hostsrv2:40404</string>
   </parameter>
   
  

• readTimeout (optional: default 10000)
  A millisecond value representing the amount of time to wait for a response from a cache server.
  Example:

  
   <parameter name="readTimeout">
     <string>5000</string>
   </parameter>
   
  

• allowableServerTimeouts (optional: default 7 timeouts)
  The number of times a cache server is allowed to exceed the readTimeout configuration, within the allowableServerTimeoutPeriod, before being placed in the dead server list.
  Example:

    
   <parameter name="allowableServerTimeouts">
    <string>13</string>
   </parameter>
   
   

• allowableServerTimeoutPeriod (optional: default: 10000 milliseconds)
  The window of milliseconds a cache server is allowed to exceed the readTimeout configuration allowableServerTimeout times before being placed in the dead server list.
  Example:

    
   <parameter name="allowableServerTimeoutPeriod">
    <string>20000</string>
   </parameter>
   
   

• retryAttempts (optional: default 5)
  The number of times to retry a request after timeout/exception.
  Example:

  
   <parameter name="retryAttempts">
     <string>5</string>
   </parameter>
   
  

• retryInterval (optional: default 10000)
  A millisecond value representing the amount of time to wait between attempts by the ServerMonitor to ping living servers to verify that they are still alive and dead servers to verify that they are still dead.
  Example:

 <parameter name="retryInterval">
   <string>10000</string>
 </parameter>
 

• LBPolicy (optional: default "Sticky")
  A String value representing the load balancing policy to use. See above for more details.
  Options are:
  • "Sticky"
  • "RandomSticky"
  • "RoundRobin"
  • "Random"
  Example:

  
   <parameter name="LBPolicy">
     <string>Sticky</string>
   </parameter>
   
  

• connectionsPerServer (optional: default 1)
  The number of initial connections created to each time it is determined to be alive. The minimum of 0 causes no initial connections to be created (they are only created on demand).
  Example:

  
   <parameter name="connectionsPerServer">
     <string>10</string>
   </parameter>
   
  

• establishCallbackConnection (optional: default false)
  Instruct the server to make a connection back to this edge client through which the client receives cache updates.
  Example:

  
   <parameter name="establishCallbackConnection">
     <string>true</string>
   </parameter>
   
  

• redundancyLevel (optional: default 0)
  The number of secondary servers set for backup to the primary server for the high availability of client queue.
  Example:

  
   <parameter name="redundancyLevel">
     <string>1</string>
   </parameter>
   
  

• socketBufferSize (optional: default 32768)
  The size of the socket buffers in bytes.
  Example:

  
   <parameter name="socketBufferSize">
     <string>32768</string>
   </parameter>
   
  

• messageTrackingTimeout (optional: default 300000 milliseconds)
  messageTrackingTimeout property specifies the time-to-live period, in milliseconds, for entries in the client's message tracking list, to minimize duplicate events. Entries that have not been modified for this amount of time are expired from the list
  Example:

  
   <parameter name="messageTrackingTimeout">
     <string>300000</string>
   </parameter>
   
  

• useLiveServerMonitorThread (optional: default true )
  Whether to use a thread and a connection to monitor live servers
  Example:

  
   <parameter name="useLiveServerMonitorThread">
     <string>true</string>
   </parameter>
  
   

• clientAckInterval (optional: default 500 milliseconds)
  Bridge client sends an acknowledgement to its primary server for the events it has got after every ClientAckInterval time.Client will send an ack to the primary server only when redundancy level is greater than 0 or -1.
  Example:

  
   <parameter name="clientAckInterval">
     <string>5000</string>
   </parameter>
   
  

If you are using a cache.xml file to create a Region declaratively, you can include the following to associate a BridgeWriter with a Region (default values shown for optional parameters):

 
 <cache-writer>
   <classname>com.gemstone.gemfire.cache.util.BridgeWriter</classname>
   <parameter name="endpoints">
     <string>MyHost=ninja.gemstone.com:40404</string>
   </parameter>
   <parameter name="readTimeout">
     <string>10000</string>
   </parameter>
   <parameter name="retryAttempts">
     <string>5</string>
   </parameter>
   <parameter name="retryInterval">
     <string>10000</string>
   </parameter>
   <parameter name="LBPolicy">
     <string>Sticky</string>
   </parameter>
   <parameter name="establishCallbackConnection">
     <string>false</string>
   </parameter>
   <parameter name="socketBufferSize">
     <string>32768</string>
   </parameter>
   </parameter>
   <parameter name="messageTrackingTimeout">
     <string>300000</string>
   </parameter>
   </parameter>
   <parameter name="useLiveServerMonitorThread">
     <string>true</string>
   </parameter>
   </parameter>
   <parameter name="clientAckInterval">
      <string>5000</string>
    </parameter>
 </cache-writer>
 

Since:

3.5

Constructor Summary

BridgeWriter()

Method Summary

void	addEndpoint(String name, String host, int port) Add an Endpoint to the known Endpoints.
void	attach(Region r) Notify the BridgeWriter that the given Region will begin delivering events to this BridgeWriter.
void	beforeCreate(EntryEvent event) Called before an entry is created.
void	beforeDestroy(EntryEvent event) Called before an entry is destroyed.
void	beforeRegionClear(RegionEvent event) Called before a region is cleared.
void	beforeRegionDestroy(RegionEvent event) Called before a region is destroyed.
void	beforeUpdate(EntryEvent event) Called before an entry is updated.
void	close() Called when a region using this BridgeWriter is destroyed, when the cache is closed, or when a callback is removed from a region using an AttributesMutator.
boolean	containsKey(Region region, Object key) Performs a containsKey on a key of a region on the cache server at the remote end of this connection.
void	createRegionOnServer(String parentRegionName, String regionName)
void	detach(Region r) Notify the BridgeWriter that the given region is no longer relevant.
static void	emergencyClose()
Set	getActiveServers() Returns the list of names of servers that are currently marked active and connected to.
Object	getConnectionProxy() Returns the ConnectionProxy associated with this BridgeLoader.
Object	getCurrentServer() Returns the currently used Endpoint.
Set	getDeadServers() Returns the list of names of servers that are currently marked dead.
Object[]	getEndpoints() Returns the list of end points passed to the bridge writer In release 5.0, the signature of this method was changed from public Endpoint[] getEndpoints() to public Object[] getEndpoints()
List	getInterestList(Region r, int interestType) Returns the interest list for a particular region.
String	getLBPolicy() Returns the load balancing policy being used by the bridge writer Internal use only
Object	getObjectFromPrimaryServer(Region r, Object key) For internal use only.
Object	getPrimaryEndpoint() Returns the Endpoint used to obtain the interest list.
Properties	getProperties() Returns the properties that defined this BridgeWriter.
int	getReadTimeout() Returns the read timeout being used to time out requests to the server Internal use only.
int	getRetryAttempts() Returns the number of times the bridge writer tries to write data on encountering certain types of exceptions.
int	getRetryInterval() Returns the retry interval in use.
void	handleMarker() Handle the marker message by invoking CacheListener.afterRegionLive on all connected Regions
boolean	hasEstablishCallbackConnection() Return true if this writer has not been closed and it was configured to establish a callback connection.
void	init(BridgeWriter bridgeWriter) Initializes this writer from an existing BridgeWriter.
void	init(Properties p) Initializes the writer with supplied config parameters.
boolean	isClosed() Returns true if this BridgeWriter has been closed.
Set	keySet(Region region) Performs a keySet of a region on the cache server at the remote end of this connection.
static void	loadEmergencyClasses() Ensure that the BridgeClient and ConnectionProxyImpl classes get loaded.
List	registerInterest(Region r, Object key, int interestType, InterestResultPolicy policy, boolean isDurable) Register interest in a particular region and key.
void	release() For speed optimizations, a connection to a server may be assigned to the calling thread when the BridgeWriter is used to do an operation.
void	removeEndpoint(String name, String host, int port) Remove an Endpoint from the dead Endpoints.
void	terminate() This method should be invoked when the BridgeWriter mechanism is to be shut down explicitly , outside of closing the cache.
String	toString() Returns a brief description of this BridgeWriter
void	unregisterInterest(Region r, Object key, int interestType) Unregister interest in a particular region and key.

Methods inherited from class java.lang.Object

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

Constructor Detail

BridgeWriter

public BridgeWriter()

Method Detail

init

public void init(Properties p)

Initializes the writer with supplied config parameters. If instantiating the writer programmatically, this method must be called with a Properties object that at a minimum contains the 'endpoints' parameter before the writer can be used. If init fails with a LicenseException, the resulting BridgeWriter will throw IllegalStateException until it is properly initialized.

Specified by:

init in interface Declarable

Parameters:

p - configuration data such as 'endpoint' definitions

Throws:

LicenseException

IllegalStateException - if the writer is already initialized

init

public void init(BridgeWriter bridgeWriter)

Initializes this writer from an existing BridgeWriter. This method reuses the existing BridgeWriter's proxy.

Parameters:

bridgeWriter - The existing BridgeWriter

Throws:

IllegalStateException - if the writer is already initialized

Since:

4.2

loadEmergencyClasses

public static void loadEmergencyClasses()

Ensure that the BridgeClient and ConnectionProxyImpl classes get loaded.

See Also:

SystemFailure.loadEmergencyClasses()

emergencyClose

public static void emergencyClose()

See Also:

SystemFailure.emergencyClose()

close

public void close()

Called when a region using this BridgeWriter is destroyed, when the cache is closed, or when a callback is removed from a region using an AttributesMutator. Closes connections to BridgeServerswhen all Regionsare finished using this BridgeWriter,

Specified by:

close in interface CacheCallback

See Also:

attach(Region), detach(Region)

handleMarker

public void handleMarker()

Handle the marker message by invoking CacheListener.afterRegionLive on all connected Regions

isClosed

public boolean isClosed()

Returns true if this BridgeWriter has been closed.

detach

public void detach(Region r)

Notify the BridgeWriter that the given region is no longer relevant. This method is used internally during Region destructionand closure. This method effects the behavor of close().

Parameters:

r - the Region which will no longer use this BridgeWriter

Since:

4.3

See Also:

attach(Region), close()

release

public void release()

For speed optimizations, a connection to a server may be assigned to the calling thread when the BridgeWriter is used to do an operation. When the application thread is done doing its work it can invoke the BridgeWriter release method to make the connection available to other application threads.

terminate

public void terminate()

This method should be invoked when the BridgeWriter mechanism is to be shut down explicitly , outside of closing the cache.

beforeUpdate

public void beforeUpdate(EntryEvent event)
                  throws CacheWriterException

Called before an entry is updated. The entry update is initiated by a put or a get that causes the writer to update an existing entry. The entry previously existed in the cache where the operation was initiated, although the old value may have been null. The entry being updated may or may not exist in the local cache where the CacheWriter is installed.

Specified by:

beforeUpdate in interface CacheWriter

Parameters:

event - an EntryEvent that provides information about the operation in progress

Throws:

CacheWriterException - if thrown will abort the operation in progress, and the exception will be propagated back to caller that initiated the operation

See Also:

Region.put(Object, Object), Region.get(Object)

beforeCreate

public void beforeCreate(EntryEvent event)
                  throws CacheWriterException

Called before an entry is created. Entry creation is initiated by a create, a put, or a get. The CacheWriter can determine whether this value comes from a get or not from EntryEvent.isLoad(). The entry being created may already exist in the local cache where this CacheWriter is installed, but it does not yet exist in the cache where the operation was initiated.

Specified by:

beforeCreate in interface CacheWriter

Parameters:

event - an EntryEvent that provides information about the operation in progress

Throws:

CacheWriterException - if thrown will abort the operation in progress, and the exception will be propagated back to caller that initiated the operation

See Also:

Region.create(Object, Object), Region.put(Object, Object), Region.get(Object)

beforeDestroy

public void beforeDestroy(EntryEvent event)
                   throws CacheWriterException

Called before an entry is destroyed. The entry being destroyed may or may not exist in the local cache where the CacheWriter is installed. This method is not called as a result of expiration or Region.localDestroy(Object).

Specified by:

beforeDestroy in interface CacheWriter

Parameters:

event - an EntryEvent that provides information about the operation in progress

Throws:

CacheWriterException - if thrown will abort the operation in progress, and the exception will be propagated back to caller that initiated the operation

See Also:

Region.destroy(Object)

beforeRegionDestroy

public void beforeRegionDestroy(RegionEvent event)
                         throws CacheWriterException

Called before a region is destroyed. The CacheWriter will not additionally be called for each entry that is destroyed in the region as a result of a region destroy. If the region's subregions have CacheWriter s installed, then they will be called for the cascading subregion destroys. This method is not called as a result of expiration or Region.localDestroyRegion(). However, the close()method is invoked regardless of whether a region is destroyed locally. A non-local region destroy results in an invocation of beforeRegionDestroy(com.gemstone.gemfire.cache.RegionEvent)followed by an invocation of close().

WARNING: This method should not destroy or create any regions itself or a deadlock will occur.

Specified by:

beforeRegionDestroy in interface CacheWriter

Parameters:

event - a RegionEvent that provides information about the

Throws:

CacheWriterException - if thrown, will abort the operation in progress, and the exception will be propagated back to the caller that initiated the operation

See Also:

Region.destroyRegion()

beforeRegionClear

public void beforeRegionClear(RegionEvent event)
                       throws CacheWriterException

Called before a region is cleared. The CacheWriter will not additionally be called for each entry that is cleared in the region as a result of a region clear. If the region's subregions have CacheWriter s installed, then they will be called for the cascading subregion clears. This method is not called as a result of expiration or Region.localDestroyRegion(). However, the close()method is invoked regardless of whether a region is cleared locally. A non-local region clear results in an invocation of beforeRegionClear(com.gemstone.gemfire.cache.RegionEvent)followed by an invocation of close().

WARNING: This method should not destroy or create or clear any regions itself or a deadlock will occur.

Specified by:

beforeRegionClear in interface CacheWriter

Parameters:

event - a RegionEvent that provides information about the

Throws:

CacheWriterException - if thrown, will abort the operation in progress, and the exception will be propagated back to the caller that initiated the operation

See Also:

Region.clear()

createRegionOnServer

public void createRegionOnServer(String parentRegionName,
                                 String regionName)
                          throws CacheWriterException

Throws:

CacheWriterException

registerInterest

public List registerInterest(Region r,
                             Object key,
                             int interestType,
                             InterestResultPolicy policy,
                             boolean isDurable)
                      throws CacheWriterException

Register interest in a particular region and key.

Parameters:

r - The region in which to register interest

key - The key in which to register interest

interestType - The type of interest (e.g. regular expression)

policy - The interest result policy. This can be one of:

• InterestResultPolicy.NONE - does not initialize the local cache
• InterestResultPolicy.KEYS - initializes the local cache with the keys satisfying the request
• InterestResultPolicy.KEYS_VALUES - initializes the local cache with the keys and current values satisfying the request

isDurable - true if the register interest is durable

Returns:

An array containing the key and current value

Throws:

CacheWriterException

Since:

4.2

hasEstablishCallbackConnection

public boolean hasEstablishCallbackConnection()

Return true if this writer has not been closed and it was configured to establish a callback connection.

Since:

4.3

unregisterInterest

public void unregisterInterest(Region r,
                               Object key,
                               int interestType)
                        throws CacheWriterException

Unregister interest in a particular region and key.

Parameters:

r - The region in which to unregister interest

key - The key in which to unregister interest

Throws:

CacheWriterException

Since:

4.2

getInterestList

public List getInterestList(Region r,
                            int interestType)
                     throws CacheWriterException

Returns the interest list for a particular region.

Parameters:

r - the region whose interest list to provide

Returns:

the interest list for a particular region

Throws:

CacheWriterException

Since:

4.2

getObjectFromPrimaryServer

public Object getObjectFromPrimaryServer(Region r,
                                         Object key)
                                  throws CacheWriterException

For internal use only. Fetch an object from the primary server. Used by registerInterest(Region, Object, int, InterestResultPolicy, boolean)to restore coherence in the client cache.

Throws:

CacheWriterException

keySet

public Set keySet(Region region)
           throws CacheWriterException

Performs a keySet of a region on the cache server at the remote end of this connection.

Parameters:

region - The region on which to perform keySet.

Throws:

CacheWriterException

Since:

5.0.2

containsKey

public boolean containsKey(Region region,
                           Object key)
                    throws CacheWriterException

Performs a containsKey on a key of a region on the cache server at the remote end of this connection.

Parameters:

region - The region on which to perform containsKey.

key - The key on which to perform containsKey.

Throws:

CacheWriterException

Since:

5.0.2

getRetryInterval

public int getRetryInterval()

Returns the retry interval in use. Retry interval refers to the interval at which dead servers are attempted to be reconnected. Internal use only.

getReadTimeout

public int getReadTimeout()

Returns the read timeout being used to time out requests to the server Internal use only.

getRetryAttempts

public int getRetryAttempts()

Returns the number of times the bridge writer tries to write data on encountering certain types of exceptions. Internal use only

getEndpoints

public Object[] getEndpoints()

Returns the list of end points passed to the bridge writer In release 5.0, the signature of this method was changed from public Endpoint[] getEndpoints()
to
public Object[] getEndpoints()

getLBPolicy

public String getLBPolicy()

Returns the load balancing policy being used by the bridge writer Internal use only

getDeadServers

public Set getDeadServers()

Returns the list of names of servers that are currently marked dead. Names refer to the logical names specified for endpoints in the configuration.

getActiveServers

public Set getActiveServers()

Returns the list of names of servers that are currently marked active and connected to. Names refer to the logical names specified for servers in the configuration.

getCurrentServer

public Object getCurrentServer()

Returns the currently used Endpoint. This method only answers an Endpoint in certain load balancing policies (e.g. STICKY).

getProperties

public Properties getProperties()

Returns the properties that defined this BridgeWriter.

Returns:

the properties that defined this BridgeWriter

Since:

4.2

getPrimaryEndpoint

public Object getPrimaryEndpoint()

Returns the Endpoint used to obtain the interest list.

Returns:

the Endpoint used to obtain the interest list; null if no interest has been registered or an interest list endpoint currently does not exist.

Since:

4.3

addEndpoint

public void addEndpoint(String name,
                        String host,
                        int port)
                 throws EndpointExistsException

Add an Endpoint to the known Endpoints.

Parameters:

name - The name of the endpoint to add

host - The host name or ip address of the endpoint to add

port - The port of the endpoint to add

Throws:

EndpointExistsException - if the Endpoint to be added already exists.

Since:

5.0.2

removeEndpoint

public void removeEndpoint(String name,
                           String host,
                           int port)
                    throws EndpointDoesNotExistException,
                           EndpointInUseException

Remove an Endpoint from the dead Endpoints. The specified Endpoint must be dead.

Parameters:

name - The name of the endpoint to remove

host - The host name or ip address of the endpoint to remove

port - The port of the endpoint to remove

Throws:

EndpointDoesNotExistException - if the Endpoint to be removed doesn't exist.

EndpointInUseException - if the Endpoint to be removed contains Connections

Since:

5.0.2

toString

public String toString()

Returns a brief description of this BridgeWriter

Overrides:

toString in class Object

Since:

4.0

attach

public void attach(Region r)

Notify the BridgeWriter that the given Region will begin delivering events to this BridgeWriter. This method effects the behavior of close() This is called internally when the BridgeWriter is added to a Region via AttributesFactory.setCacheWriter(CacheWriter)}

Parameters:

r - the Region which will begin use this BridgeWriter.

Since:

4.3

See Also:

detach(Region), close()

getConnectionProxy

public Object getConnectionProxy()

Returns the ConnectionProxy associated with this BridgeLoader. For internal use only.

Returns:

the ConnectionProxy associated with this BridgeLoader