net.lightbody.bmp.proxy.dns

Class ChainedHostResolver

java.lang.Object

net.lightbody.bmp.proxy.dns.ChainedHostResolver

All Implemented Interfaces:

AdvancedHostResolver, HostResolver

public class ChainedHostResolver
extends Object
implements AdvancedHostResolver

An AdvancedHostResolver that applies the AdvancedHostResolver methods to multiple implementations. Methods are applied to the resolvers in the order specified when the ChainedHostResolver is constructed. AdvancedHostResolver methods that modify the resolver are guaranteed to complete atomically over all resolvers. For example, if one thread makes a call to resolve(String) while another thread is remapping hosts using remapHost(String, String), the call to resolve(String) is guaranteed to apply the newly-remapped hosts to all resolvers managed by this ChainedHostResolver, or to no resolvers, but the call to resolve(String) will never result in the host name remappings applied only to "some" of the chained resolvers.

For getter methods (all read-only methods except resolve(String)), the ChainedHostResolver returns results from the first chained resolver.

The atomic write methods specified by AdvancedHostResolver are:

• AdvancedHostResolver.remapHost(String, String)
• AdvancedHostResolver.remapHosts(java.util.Map)
• AdvancedHostResolver.removeHostRemapping(String)
• AdvancedHostResolver.clearHostRemappings()
• AdvancedHostResolver.setNegativeDNSCacheTimeout(int, java.util.concurrent.TimeUnit)
• AdvancedHostResolver.setPositiveDNSCacheTimeout(int, java.util.concurrent.TimeUnit)
• AdvancedHostResolver.clearDNSCache()

Constructor Summary

Constructors

Constructor and Description
ChainedHostResolver(Collection<? extends AdvancedHostResolver> resolvers) Creates a ChainedHostResolver that applies AdvancedHostResolver methods to the specified resolvers in the order specified by the collection's iterator.

Method Summary

Modifier and Type	Method and Description
void	clearDNSCache() Clears both the positive (successful DNS lookups) and negative (failed DNS lookups) cache.
void	clearHostRemappings() Removes all hostname remappings.
Map<String,String>	getHostRemappings() Returns all host remappings in effect.
Collection<String>	getOriginalHostnames(String remappedHost) Returns the original address or addresses that are remapped to the specified remappedHost.
Collection<? extends AdvancedHostResolver>	getResolvers() Returns the resolvers used by this ChainedHostResolver.
void	remapHost(String originalHost, String remappedHost) Remaps an individual host.
void	remapHosts(Map<String,String> hostRemappings) Replaces the host remappings in the existing list of remappings (if any) with the specified remappings.
void	removeHostRemapping(String originalHost) Removes the specified host remapping.
Collection<InetAddress>	resolve(String host) Resolves a hostname to one or more IP addresses.
void	setNegativeDNSCacheTimeout(int timeout, TimeUnit timeUnit) Sets the negative (failed DNS lookup) timeout when making DNS lookups.
void	setPositiveDNSCacheTimeout(int timeout, TimeUnit timeUnit) Sets the positive (successful DNS lookup) timeout when making DNS lookups.

Methods inherited from class java.lang.Object

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

Constructor Detail

ChainedHostResolver

public ChainedHostResolver(Collection<? extends AdvancedHostResolver> resolvers)

Creates a ChainedHostResolver that applies AdvancedHostResolver methods to the specified resolvers in the order specified by the collection's iterator.

Parameters:

resolvers - resolvers to invoke, in the order specified by the collection's iterator

Method Detail

getResolvers

public Collection<? extends AdvancedHostResolver> getResolvers()

Returns the resolvers used by this ChainedHostResolver. The iterator of the collection is guaranteed to return the resolvers in the order in which they are queried.

Returns:

resolvers used by this ChainedHostResolver

remapHosts

public void remapHosts(Map<String,String> hostRemappings)

Description copied from interface: AdvancedHostResolver

Replaces the host remappings in the existing list of remappings (if any) with the specified remappings. The remappings will be applied in the order specified by the Map's iterator.

Note: The original hostnames must exactly match the requested hostname. It is not a domain or regular expression match.

Specified by:

remapHosts in interface AdvancedHostResolver

Parameters:

hostRemappings - Map of <original hostname, remapped hostname>

remapHost

public void remapHost(String originalHost,
                      String remappedHost)

Description copied from interface: AdvancedHostResolver

Remaps an individual host. If there are any existing remappings, the new remapping will be applied last, after all existing remappings are applied. If there is already a remapping for the specified originalHost, it will be removed before the new remapping is added to the end of the host remapping list (and will therefore be the last remapping applied).

Specified by:

remapHost in interface AdvancedHostResolver

Parameters:

originalHost - Original host to remap. Must exactly match the requested hostname (not a domain or regular expression match).

remappedHost - hostname that will replace originalHost

removeHostRemapping

public void removeHostRemapping(String originalHost)

Description copied from interface: AdvancedHostResolver

Removes the specified host remapping. If the remapping does not exist, this method has no effect.

Specified by:

removeHostRemapping in interface AdvancedHostResolver

Parameters:

originalHost - currently-remapped hostname

clearHostRemappings

public void clearHostRemappings()

Description copied from interface: AdvancedHostResolver

Removes all hostname remappings.

Specified by:

clearHostRemappings in interface AdvancedHostResolver

getHostRemappings

public Map<String,String> getHostRemappings()

Description copied from interface: AdvancedHostResolver

Returns all host remappings in effect. Iterating over the returned Map is guaranteed to return remappings in the order in which the remappings are actually applied.

Specified by:

getHostRemappings in interface AdvancedHostResolver

Returns:

Map of <original hostname, remapped hostname>

getOriginalHostnames

public Collection<String> getOriginalHostnames(String remappedHost)

Description copied from interface: AdvancedHostResolver

Returns the original address or addresses that are remapped to the specified remappedHost. Iterating over the returned Collection is guaranteed to return original mappings in the order in which the remappings are applied.

Specified by:

getOriginalHostnames in interface AdvancedHostResolver

Parameters:

remappedHost - remapped hostname

Returns:

original hostnames that are remapped to the specified remappedHost, or an empty Collection if no remapping is defined to the remappedHost

clearDNSCache

public void clearDNSCache()

Description copied from interface: AdvancedHostResolver

Clears both the positive (successful DNS lookups) and negative (failed DNS lookups) cache.

Specified by:

clearDNSCache in interface AdvancedHostResolver

setPositiveDNSCacheTimeout

public void setPositiveDNSCacheTimeout(int timeout,
                                       TimeUnit timeUnit)

Description copied from interface: AdvancedHostResolver

Sets the positive (successful DNS lookup) timeout when making DNS lookups.

Note: The timeUnit parameter does not guarantee the specified precision; implementations may need to reduce precision, depending on the underlying DNS implementation. For example, the Oracle JVM's DNS cache only supports timeouts in whole seconds, so specifying a timeout of 1200ms will result in a timeout of 1 second.

Specified by:

setPositiveDNSCacheTimeout in interface AdvancedHostResolver

Parameters:

timeout - maximum lookup time

timeUnit - units of the timeout value

setNegativeDNSCacheTimeout

public void setNegativeDNSCacheTimeout(int timeout,
                                       TimeUnit timeUnit)

Description copied from interface: AdvancedHostResolver

Sets the negative (failed DNS lookup) timeout when making DNS lookups.

Note: The timeUnit parameter does not guarantee the specified precision; implementations may need to reduce precision, depending on the underlying DNS implementation. For example, the Oracle JVM's DNS cache only supports timeouts in whole seconds, so specifying a timeout of 1200ms will result in a timeout of 1 second.

Specified by:

setNegativeDNSCacheTimeout in interface AdvancedHostResolver

Parameters:

timeout - maximum lookup time

timeUnit - units of the timeout value

resolve

public Collection<InetAddress> resolve(String host)

Description copied from interface: HostResolver

Resolves a hostname to one or more IP addresses. The iterator over the returned Collection is recommended to reflect the ordering returned by the underlying name lookup service. For example, if a DNS server returns three IP addresses, 1.1.1.1, 2.2.2.2, and 3.3.3.3, corresponding to www.somehost.com, the returned Collection iterator is recommended to iterate in the order [1.1.1.1, 2.2.2.2, 3.3.3.3].

Specified by:

resolve in interface HostResolver

Parameters:

host - host to resolve

Returns:

resolved InetAddresses, or an empty collection if no addresses were found