Class NameResolver

  • Direct Known Subclasses:
    CachingNameResolver, DefaultNameResolver

    @Extensible
    @ThreadSafety(level=INTERFACE_THREADSAFE)
    public abstract class NameResolver
    extends java.lang.Object
    This class defines an API that the LDAP SDK can use to resolve host names to IP addresses, and vice versa. The default implementations of the name resolution methods simply delegates to the corresponding methods provided in the InetAddress class. Subclasses may override these methods to provide support for caching, improved instrumentation, or other functionality. Any such methods that are not overridden will get the JVM-default behavior.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected NameResolver()
      Creates a new instance of this default name resolver.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      java.net.InetAddress[] getAllByName​(java.lang.String host)
      Retrieves an array of InetAddress objects that encapsulate all known IP addresses associated with the provided host name.
      java.net.InetAddress getByName​(java.lang.String host)
      Retrieves an InetAddress that encapsulates an IP address associated with the provided host name.
      java.lang.String getCanonicalHostName​(java.net.InetAddress inetAddress)
      Retrieves the canonical host name for the provided InetAddress object.
      java.lang.String getHostName​(java.net.InetAddress inetAddress)
      Retrieves the host name for the provided InetAddress object.
      java.net.InetAddress getLocalHost()
      Retrieves the address of the local host.
      java.net.InetAddress getLoopbackAddress()
      Retrieves the loopback address for the system.
      static void setJVMSuccessfulLookupCacheTTLSeconds​(int seconds)
      Sets the length of time in seconds for which the JVM should cache the results of successful name service lookups.
      static void setJVMUnsuccessfulLookupCacheTTLSeconds​(int seconds)
      Sets the length of time in seconds for which the JVM should cache the results of unsuccessful name service lookups (that is, lookups in which no mapping is found).
      java.lang.String toString()
      Retrieves a string representation of this name resolver.
      abstract void toString​(java.lang.StringBuilder buffer)
      Appends a string representation of this name resolver to the provided buffer.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • NameResolver

        protected NameResolver()
        Creates a new instance of this default name resolver.
    • Method Detail

      • getByName

        @NotNull
        public java.net.InetAddress getByName​(@Nullable
                                              java.lang.String host)
                                       throws java.net.UnknownHostException,
                                              java.lang.SecurityException
        Retrieves an InetAddress that encapsulates an IP address associated with the provided host name.
        Parameters:
        host - The host name for which to retrieve a corresponding InetAddress object. It can be a resolvable name or a textual representation of an IP address. If the provided name is the textual representation of an IPv6 address, then it can use either the form described in RFC 2373 or RFC 2732, or it can be an IPv6 scoped address. If it is null, then the returned address should represent an address of the loopback interface.
        Returns:
        An InetAddress that encapsulates an IP address associated with the provided host name.
        Throws:
        java.net.UnknownHostException - If the provided name cannot be resolved to its corresponding IP addresses.
        java.lang.SecurityException - If a security manager prevents the name resolution attempt.
      • getAllByName

        @NotNull
        public java.net.InetAddress[] getAllByName​(@Nullable
                                                   java.lang.String host)
                                            throws java.net.UnknownHostException,
                                                   java.lang.SecurityException
        Retrieves an array of InetAddress objects that encapsulate all known IP addresses associated with the provided host name.
        Parameters:
        host - The host name for which to retrieve the corresponding InetAddress objects. It can be a resolvable name or a textual representation of an IP address. If the provided name is the textual representation of an IPv6 address, then it can use either the form described in RFC 2373 or RFC 2732, or it can be an IPv6 scoped address. If it is null, then the returned address should represent an address of the loopback interface.
        Returns:
        An array of InetAddress objects that encapsulate all known IP addresses associated with the provided host name.
        Throws:
        java.net.UnknownHostException - If the provided name cannot be resolved to its corresponding IP addresses.
        java.lang.SecurityException - If a security manager prevents the name resolution attempt.
      • getHostName

        @NotNull
        public java.lang.String getHostName​(@NotNull
                                            java.net.InetAddress inetAddress)
        Retrieves the host name for the provided InetAddress object.
        Parameters:
        inetAddress - The address for which to retrieve the host name. It must not be null.
        Returns:
        The host name for the provided InetAddress object, or a textual representation of the IP address if the name cannot be determined.
      • getCanonicalHostName

        @NotNull
        public java.lang.String getCanonicalHostName​(@NotNull
                                                     java.net.InetAddress inetAddress)
        Retrieves the canonical host name for the provided InetAddress object.
        Parameters:
        inetAddress - The address for which to retrieve the canonical host name. It must not be null.
        Returns:
        The canonical host name for the provided InetAddress object, or a textual representation of the IP address if the name cannot be determined.
      • getLocalHost

        @NotNull
        public java.net.InetAddress getLocalHost()
                                          throws java.net.UnknownHostException,
                                                 java.lang.SecurityException
        Retrieves the address of the local host. This should be the name of the host obtained from the system, converted to an InetAddress.
        Returns:
        The address of the local host.
        Throws:
        java.net.UnknownHostException - If the local host name cannot be resolved.
        java.lang.SecurityException - If a security manager prevents the name resolution attempt.
      • getLoopbackAddress

        @NotNull
        public java.net.InetAddress getLoopbackAddress()
        Retrieves the loopback address for the system. This should be either the IPv4 loopback address of 127.0.0.1, or the IPv6 loopback address of ::1.
        Returns:
        The loopback address for the system.
      • setJVMSuccessfulLookupCacheTTLSeconds

        public static void setJVMSuccessfulLookupCacheTTLSeconds​(int seconds)
        Sets the length of time in seconds for which the JVM should cache the results of successful name service lookups.

        Note that this timeout only applies to lookups performed by the JVM itself and may not apply to all name resolver implementations. Some implementations may provide their own caching or their own lookup mechanisms that do not use this setting.
        Parameters:
        seconds - The length of time in seconds for which the JVM should cache the results of successful name service lookups. A value that is less than zero indicates that values should be cached forever.
      • setJVMUnsuccessfulLookupCacheTTLSeconds

        public static void setJVMUnsuccessfulLookupCacheTTLSeconds​(int seconds)
        Sets the length of time in seconds for which the JVM should cache the results of unsuccessful name service lookups (that is, lookups in which no mapping is found).

        Note that this timeout only applies to lookups performed by the JVM itself and may not apply to all name resolver implementations. Some implementations may provide their own caching or their own lookup mechanisms that do not use this setting.
        Parameters:
        seconds - The length of time in seconds for which the JVM should cache the results of unsuccessful name service lookups. A value that is less than zero indicates that values should be cached forever.
      • toString

        @NotNull
        public final java.lang.String toString()
        Retrieves a string representation of this name resolver.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of this name resolver.
      • toString

        public abstract void toString​(@NotNull
                                      java.lang.StringBuilder buffer)
        Appends a string representation of this name resolver to the provided buffer.
        Parameters:
        buffer - A buffer to which the string representation should be appended.