com.marklogic.client.datamovement

Class HostAvailabilityListener

java.lang.Object

com.marklogic.client.datamovement.HostAvailabilityListener

All Implemented Interfaces:

BatchFailureListener<WriteBatch>, FailureListener<QueryBatchException>, QueryFailureListener, WriteFailureListener

public class HostAvailabilityListener
extends Object
implements QueryFailureListener, WriteFailureListener

HostAvailabilityListener is automatically registered with all QueryBatcher and WriteBatcher instances to monitor for failover scenarios. When HostAvailabilityListener detects that a host is unavailable (matches one of getHostUnavailableExceptions()), it black-lists the host for a period of time equal to getSuspendTimeForHostUnavailable(). After that time, it calls DataMovementManager.readForestConfig() then passes that updated ForestConfiguration to batcher.withForestConfig() so the batcher will fall back to using the hosts the server says are available. Directly after black-listing (and before updating the ForestConfiguration) this calls batcher.retry with the failed WriteBatch or QueryBatchException so the batch can succeed if possible. The main objective here is to gracefully handle a failover scenario by temporarily routing requests to hosts other than the failed host(s), retry-ing requests that failed, and eventually reverting to utilizing the full cluster that’s available. Nevertheless, there will definitely be failure scenarios not addressed by HostAvailabilityListener and therefore we recommend that production installations of Data Movement SDK use HostAvailabilityListener as an example and install their own failure-handling listeners complete with retry and updates to the batcher’s ForestConfiguration as appropriate.

If you would like to change the default settings, you can change them on the pre-registered HostAvailabilityListener which you can access via WriteBatcher.getBatchFailureListeners() or QueryBatcher.getQueryFailureListeners().

Constructor Summary

Constructors

Constructor and Description
HostAvailabilityListener(DataMovementManager moveMgr)

Method Summary

Modifier and Type	Method and Description
Throwable[]	getHostUnavailableExceptions()
int	getMinHosts()
Duration	getSuspendTimeForHostUnavailable()
void	processFailure(QueryBatchException queryBatch) This implements the QueryFailureListener interface
void	processFailure(WriteBatch batch, Throwable throwable) This implements the WriteFailureListener interface
HostAvailabilityListener	withHostUnavailableExceptions(Class<Throwable>... exceptionTypes) Overwrites the list of exceptions for which a host will be blacklisted
HostAvailabilityListener	withMinHosts(int numHosts) If less than minHosts are left, calls stopJob.
HostAvailabilityListener	withSuspendTimeForHostUnavailable(Duration duration) If a host becomes unavailable (NoHttpResponseException, SocketException, SSLException, UnknownHostException), adds it to the blacklist

Methods inherited from class java.lang.Object

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

Constructor Detail

HostAvailabilityListener

public HostAvailabilityListener(DataMovementManager moveMgr)

Parameters:

moveMgr - the DataMovementManager (used to call readForestConfig to reset after black-listing an unavailable host)

Method Detail

withSuspendTimeForHostUnavailable

public HostAvailabilityListener withSuspendTimeForHostUnavailable(Duration duration)

If a host becomes unavailable (NoHttpResponseException, SocketException, SSLException, UnknownHostException), adds it to the blacklist

Parameters:

duration - the amount of time an unavailable host will be suspended

Returns:

this instance (for method chaining)

withMinHosts

public HostAvailabilityListener withMinHosts(int numHosts)

If less than minHosts are left, calls stopJob.

Parameters:

numHosts - the minimum number of hosts before this will call dataMovementMangaer.stopJob(batcher)

Returns:

this instance (for method chaining)

withHostUnavailableExceptions

public HostAvailabilityListener withHostUnavailableExceptions(Class<Throwable>... exceptionTypes)

Overwrites the list of exceptions for which a host will be blacklisted

Parameters:

exceptionTypes - the list of types of Throwable, any of which constitute a host that’s unavailable

Returns:

this instance (for method chaining)

getHostUnavailableExceptions

public Throwable[] getHostUnavailableExceptions()

Returns:

the list of types of Throwable, any of which constitute a host that’s unavailable

getSuspendTimeForHostUnavailable

public Duration getSuspendTimeForHostUnavailable()

Returns:

the amount of time an unavailable host will be suspended

getMinHosts

public int getMinHosts()

Returns:

the minimum number of hosts before this will call dataMovementMangaer.stopJob(batcher)

processFailure

public void processFailure(WriteBatch batch,
                           Throwable throwable)

This implements the WriteFailureListener interface

Specified by:

processFailure in interface BatchFailureListener<WriteBatch>

Specified by:

processFailure in interface WriteFailureListener

Parameters:

batch - the batch of WriteEvents

throwable - the exception

processFailure

public void processFailure(QueryBatchException queryBatch)

This implements the QueryFailureListener interface

Specified by:

processFailure in interface FailureListener<QueryBatchException>

Specified by:

processFailure in interface QueryFailureListener

Parameters:

queryBatch - the exception with information about the failed query attempt