com.marklogic.client.datamovement

Class HostAvailabilityListener

java.lang.Object

com.marklogic.client.datamovement.HostAvailabilityListener

All Implemented Interfaces:

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

Direct Known Subclasses:

NoResponseListener

public class HostAvailabilityListener
extends java.lang.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 blacklists the MarkLogic 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) Manages refreshing the forests and hosts and retrying events after a host becomes unavailable.

Method Summary

Modifier and Type	Method and Description
java.lang.Throwable[]	getHostUnavailableExceptions()
static HostAvailabilityListener	getInstance(Batcher batcher) Returns the first HostAvailabilityListener instance registered with the Batcher.
int	getMinHosts()
java.time.Duration	getSuspendTimeForHostUnavailable()
BatchFailureListener<QueryBatch>	initializeRetryListener(QueryBatchListener queryBatchListener) Initializes the RetryListener for the given QueryBatchListener.
protected boolean	isHostUnavailableException(java.lang.Throwable throwable, java.util.Set<java.lang.Throwable> path)
void	processFailure(QueryBatchException queryBatch) This implements the QueryFailureListener interface
void	processFailure(WriteBatch batch, java.lang.Throwable throwable) This implements the WriteFailureListener interface
HostAvailabilityListener	withHostUnavailableExceptions(java.lang.Class<java.lang.Throwable>... exceptionTypes) Overwrites the list of exceptions for which a request can be retried and a MarkLogic host can be blacklisted
HostAvailabilityListener	withMinHosts(int numHosts) If less than minHosts are left, calls stopJob.
HostAvailabilityListener	withSuspendTimeForHostUnavailable(java.time.Duration duration) If a host becomes unavailable (SocketException, SSLException, UnknownHostException), adds it to the blacklist

Methods inherited from class java.lang.Object

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

Constructor Detail

HostAvailabilityListener

public HostAvailabilityListener(DataMovementManager moveMgr)

Manages refreshing the forests and hosts and retrying events after a host becomes unavailable.

Parameters:

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

Method Detail

withSuspendTimeForHostUnavailable

public HostAvailabilityListener withSuspendTimeForHostUnavailable(java.time.Duration duration)

If a host becomes unavailable (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(java.lang.Class<java.lang.Throwable>... exceptionTypes)

Overwrites the list of exceptions for which a request can be retried and a MarkLogic host can 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 java.lang.Throwable[] getHostUnavailableExceptions()

Returns:

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

getSuspendTimeForHostUnavailable

public java.time.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,
                           java.lang.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

isHostUnavailableException

protected boolean isHostUnavailableException(java.lang.Throwable throwable,
                                             java.util.Set<java.lang.Throwable> path)

initializeRetryListener

public BatchFailureListener<QueryBatch> initializeRetryListener(QueryBatchListener queryBatchListener)

Initializes the RetryListener for the given QueryBatchListener.

Parameters:

queryBatchListener - the QueryBatchListener for which the RetryListener has to be initialized.

Returns:

the RetryListener if not initialized and null if already initialized.

getInstance

public static HostAvailabilityListener getInstance(Batcher batcher)

Returns the first HostAvailabilityListener instance registered with the Batcher.

You can customize the HostAvailabilityListener instance registered with the Batcher like:

    HostAvailabilityListener.getInstance(Batcher)
      .withSuspendTimeForHostUnavailable(Duration.ofMinutes(60))
      .withMinHosts(2)

Parameters:

batcher - the Batcher instance for which the registered HostAvailabilityListener is returned

Returns:

the first HostAvailabilityListener instance with the batcher or null if there is no HostAvailabilityListener registered