com.ca.commons.jndi.beans
Class ResilientDirContextFactory

java.lang.Object
  com.ca.commons.jndi.beans.ResilientDirContextFactory

All Implemented Interfaces:

DirContextFactory, InvocationHandler

Direct Known Subclasses:

FailureSimulateDirContextFactory, MappingDummyDirContextFactory

public class ResilientDirContextFactory
extends Object
implements DirContextFactory, InvocationHandler

A factory that produces a directory context that can automatically recover from communication failures. The DirContext object returned by the getContext method is a proxy that wraps the real DirContext object. The proxy will catch any CommunicationExceptions or ServiceUnavailableExceptions thrown by the real context, and attempt to automatically retry the failed operation. Such an occurrence is termed a transient failure. A retry involves discarding the context that threw the exception, waiting for a period of time, then attempting to create a new context and re-issuing the original call using the new context. If a transient failure occurs when retrying an operation, a retry will again be attempted, until the limit on the number of retries has been reached. If the retry limit is reached, the exception is thrown to the caller and no more retry attempts are made. The retry limit and the delay between retries can both be configured.

Failover

Instances of this class can be configured to automatically switch to alternate hosts whenever a transient failure occurs. This is useful if you have several identical hosts available and one of them goes down, in which case the context proxy will catch the failure and automatically switch to an alternate server.

To enable failover support, supply a list of available hosts via the setFailoverList(java.util.List) method. This list should be sorted with the preferred hosts first. If the value provided to the setRetries(int) method is less than the size of the failover list, then it is ignored. Therefore, each server in the failover list is always tried at least once before giving up and throwing the exception to the caller.

Note that failover support assumes that the JNDI environment contains a Context.PROVIDER_URL property. The host name component of this URL is replaced by the next value from the failover list when a retry is performed.

Field Summary

protected int	defaultPort
protected long	delay
protected Properties	jndiEnv
static Logger	LOGGER
protected DirContext	realCtx

Constructor Summary

ResilientDirContextFactory()

ResilientDirContextFactory(int defaultPort)

Method Summary

void	close() Indicates that the JNDIBeanStore using this factory has been closed down.
protected Object	doInvoke(Method method, Object[] args)
DirContext	getContext() Returns a DirContext instance that is ready for use.
List<String>	getFailoverList() Returns the list of host names being used for failover.
Properties	getJNDIEnv()
int	getRetries()
long	getRetryDelay() Returns the delay between retries, in milliseconds.
Object	invoke(Object proxy, Method method, Object[] args)
void	returnContext(DirContext ctx) Called to indicate that a DirContext previously provided by this factory is no longer needed.
void	setFailoverList(List<String> failoverList) Sets the list of hosts names to use for failover.
void	setJNDIEnv(Properties jndiEnv) Sets the JNDI environment to use to create directory contexts.
void	setRetries(int retries) Sets the number of times an operation will be retried before giving up.
void	setRetryDelay(long retryDelay) Sets the delay in milliseconds between retries.
protected void	testContexts() Step through all hosts from most preferred to least, setting realCtx to first host that can be contacted.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

LOGGER

public static final Logger LOGGER

jndiEnv

protected Properties jndiEnv

delay

protected long delay

realCtx

protected volatile DirContext realCtx

defaultPort

protected final int defaultPort

Constructor Detail

ResilientDirContextFactory

public ResilientDirContextFactory(int defaultPort)

ResilientDirContextFactory

public ResilientDirContextFactory()

Method Detail

toString

public String toString()

Overrides:

toString in class Object

setJNDIEnv

public final void setJNDIEnv(Properties jndiEnv)

Sets the JNDI environment to use to create directory contexts. An environment must be provided before this factory is used.

Parameters:

jndiEnv - The environment to pass to the InitialDirContext.InitialDirContext(java.util.Hashtable) method.

getJNDIEnv

public final Properties getJNDIEnv()

setRetries

public final void setRetries(int retries)

Sets the number of times an operation will be retried before giving up. If this value is less than the size of the list of failover hosts, then it is ignored, and each host in the failover list is tried once before giving up. If this value is greater than the size of the failover list, then some hosts may be tried more than once before giving up. The default value for the number of retries is 0.

See Also:

setFailoverList(java.util.List)

getRetries

public final int getRetries()

setRetryDelay

public final void setRetryDelay(long retryDelay)

Sets the delay in milliseconds between retries. The default value is 1000 (1 second).

Parameters:

retryDelay - The delay, in milliseconds.

getRetryDelay

public final long getRetryDelay()

Returns the delay between retries, in milliseconds.

setFailoverList

public final void setFailoverList(List<String> failoverList)

Sets the list of hosts names to use for failover. If this list is not specified, all retries use the same host until the retry limit is reached.

Parameters:

failoverList - A list of host name strings.

getFailoverList

public final List<String> getFailoverList()

Returns the list of host names being used for failover.

Returns:

A list of host name strings.

getContext

public final DirContext getContext()

Description copied from interface: DirContextFactory

Returns a DirContext instance that is ready for use. The object returned by this method will always be passed back as a parameter to the returnContext method.

Specified by:

getContext in interface DirContextFactory

See Also:

DirContextFactory.returnContext(javax.naming.directory.DirContext)

returnContext

public final void returnContext(DirContext ctx)

Description copied from interface: DirContextFactory

Called to indicate that a DirContext previously provided by this factory is no longer needed.

Specified by:

returnContext in interface DirContextFactory

Parameters:

ctx - The DirContext previously returned by the getContext method.

See Also:

DirContextFactory.getContext()

close

public final void close()
                 throws NamingException

Description copied from interface: DirContextFactory

Indicates that the JNDIBeanStore using this factory has been closed down. An implementation should free up any resources it is using.

Specified by:

close in interface DirContextFactory

Throws:

NamingException - If there was a problem when freeing resources.

See Also:

JNDIBeanStore.close()

testContexts

protected void testContexts()
                     throws NamingException

Step through all hosts from most preferred to least, setting realCtx to first host that can be contacted.

Throws:

NamingException

doInvoke

protected Object doInvoke(Method method,
                          Object[] args)
                   throws IllegalAccessException,
                          InterruptedException,
                          NamingException,
                          InvocationTargetException

Throws:

IllegalAccessException

InterruptedException

NamingException

InvocationTargetException

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] args)
              throws Throwable

Specified by:

invoke in interface InvocationHandler

Throws:

Throwable