001/*
002 * Copyright 2019-2024 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2019-2024 Ping Identity Corporation
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *    http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020/*
021 * Copyright (C) 2019-2024 Ping Identity Corporation
022 *
023 * This program is free software; you can redistribute it and/or modify
024 * it under the terms of the GNU General Public License (GPLv2 only)
025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
026 * as published by the Free Software Foundation.
027 *
028 * This program is distributed in the hope that it will be useful,
029 * but WITHOUT ANY WARRANTY; without even the implied warranty of
030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
031 * GNU General Public License for more details.
032 *
033 * You should have received a copy of the GNU General Public License
034 * along with this program; if not, see <http://www.gnu.org/licenses>.
035 */
036package com.unboundid.ldap.sdk;
037
038
039
040import java.net.InetAddress;
041import java.net.UnknownHostException;
042
043import com.unboundid.util.Extensible;
044import com.unboundid.util.NotNull;
045import com.unboundid.util.Nullable;
046import com.unboundid.util.StaticUtils;
047import com.unboundid.util.ThreadSafety;
048import com.unboundid.util.ThreadSafetyLevel;
049
050
051
052/**
053 * This class defines an API that the LDAP SDK can use to resolve host names to
054 * IP addresses, and vice versa.  The default implementations of the name
055 * resolution methods simply delegates to the corresponding methods provided in
056 * the {@code InetAddress} class.  Subclasses may override these methods to
057 * provide support for caching, improved instrumentation, or other
058 * functionality.  Any such methods that are not overridden will get the
059 * JVM-default behavior.
060 */
061@Extensible()
062@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
063public abstract class NameResolver
064{
065  /**
066   * The name of the system property that the JVM uses to specify how long (in
067   * seconds) to cache the results of successful name service lookups.
068   */
069  @NotNull private static final String
070       JVM_PROPERTY_POSITIVE_ADDRESS_CACHE_TTL_SECONDS =
071            "networkaddress.cache.ttl";
072
073
074
075  /**
076   * The name of the system property that the JVM uses to specify how long (in
077   * seconds) to cache the results of unsuccessful name service lookups (that
078   * is, lookups that return no mapping).
079   */
080  @NotNull private static final String
081       JVM_PROPERTY_NEGATIVE_ADDRESS_CACHE_TTL_SECONDS =
082            "networkaddress.cache.negative.ttl";
083
084
085
086  /**
087   * Creates a new instance of this default name resolver.
088   */
089  protected NameResolver()
090  {
091    // No implementation is required.
092  }
093
094
095
096  /**
097   * Retrieves an {@code InetAddress} that encapsulates an IP address associated
098   * with the provided host name.
099   *
100   * @param  host  The host name for which to retrieve a corresponding
101   *               {@code InetAddress} object.  It can be a resolvable name or
102   *               a textual representation of an IP address.  If the provided
103   *               name is the textual representation of an IPv6 address, then
104   *               it can use either the form described in RFC 2373 or RFC 2732,
105   *               or it can be an IPv6 scoped address.  If it is {@code null},
106   *               then the returned address should represent an address of the
107   *               loopback interface.
108   *
109   * @return  An {@code InetAddress} that encapsulates an IP address associated
110   *          with the provided host name.
111   *
112   * @throws  UnknownHostException  If the provided name cannot be resolved to
113   *                                its corresponding IP addresses.
114   *
115   * @throws  SecurityException  If a security manager prevents the name
116   *                             resolution attempt.
117   */
118  @NotNull()
119  public InetAddress getByName(@Nullable final String host)
120         throws UnknownHostException, SecurityException
121  {
122    return InetAddress.getByName(host);
123  }
124
125
126
127  /**
128   * Retrieves an array of {@code InetAddress} objects that encapsulate all
129   * known IP addresses associated with the provided host name.
130   *
131   * @param  host  The host name for which to retrieve the corresponding
132   *               {@code InetAddress} objects.  It can be a resolvable name or
133   *               a textual representation of an IP address.  If the provided
134   *               name is the textual representation of an IPv6 address, then
135   *               it can use either the form described in RFC 2373 or RFC 2732,
136   *               or it can be an IPv6 scoped address.  If it is {@code null},
137   *               then the returned address should represent an address of the
138   *               loopback interface.
139   *
140   * @return  An array of {@code InetAddress} objects that encapsulate all known
141   *          IP addresses associated with the provided host name.
142   *
143   * @throws  UnknownHostException  If the provided name cannot be resolved to
144   *                                its corresponding IP addresses.
145   *
146   * @throws  SecurityException  If a security manager prevents the name
147   *                             resolution attempt.
148   */
149  @NotNull()
150  public InetAddress[] getAllByName(@Nullable final String host)
151         throws UnknownHostException, SecurityException
152  {
153    return InetAddress.getAllByName(host);
154  }
155
156
157
158  /**
159   * Retrieves the host name for the provided {@code InetAddress} object.
160   *
161   * @param  inetAddress  The address for which to retrieve the host name.  It
162   *                      must not be {@code null}.
163   *
164   * @return  The host name for the provided {@code InetAddress} object, or a
165   *          textual representation of the IP address if the name cannot be
166   *          determined.
167   */
168  @NotNull()
169  public String getHostName(@NotNull final InetAddress inetAddress)
170  {
171    return inetAddress.getHostName();
172  }
173
174
175
176  /**
177   * Retrieves the canonical host name for the provided {@code InetAddress}
178   * object.
179   *
180   * @param  inetAddress  The address for which to retrieve the canonical host
181   *                      name.  It must not be {@code null}.
182   *
183   * @return  The canonical host name for the provided {@code InetAddress}
184   *          object, or a textual representation of the IP address if the name
185   *          cannot be determined.
186   */
187  @NotNull()
188  public String getCanonicalHostName(@NotNull final InetAddress inetAddress)
189  {
190    return inetAddress.getCanonicalHostName();
191  }
192
193
194
195  /**
196   * Retrieves the address of the local host.  This should be the name of the
197   * host obtained from the system, converted to an {@code InetAddress}.
198   *
199   * @return  The address of the local host.
200   *
201   * @throws  UnknownHostException  If the local host name cannot be resolved.
202   *
203   * @throws  SecurityException  If a security manager prevents the name
204   *                             resolution attempt.
205   */
206  @NotNull()
207  public InetAddress getLocalHost()
208         throws UnknownHostException, SecurityException
209  {
210    return InetAddress.getLocalHost();
211  }
212
213
214
215  /**
216   * Retrieves the loopback address for the system.  This should be either the
217   * IPv4 loopback address of 127.0.0.1, or the IPv6 loopback address of ::1.
218   *
219   * @return  The loopback address for the system.
220   */
221  @NotNull()
222  public InetAddress getLoopbackAddress()
223  {
224    return InetAddress.getLoopbackAddress();
225  }
226
227
228
229  /**
230   * Sets the length of time in seconds for which the JVM should cache the
231   * results of successful name service lookups.
232   * <BR><BR>
233   * Note that this timeout only applies to lookups performed by the JVM itself
234   * and may not apply to all name resolver implementations.  Some
235   * implementations may provide their own caching or their own lookup
236   * mechanisms that do not use this setting.
237   *
238   * @param  seconds  The length of time in seconds for which the JVM should
239   *                  cache the results of successful name service lookups.  A
240   *                  value that is less than zero indicates that values should
241   *                  be cached forever.
242   */
243  public static void setJVMSuccessfulLookupCacheTTLSeconds(final int seconds)
244  {
245    if (seconds < 0)
246    {
247      StaticUtils.setSystemProperty(
248           JVM_PROPERTY_POSITIVE_ADDRESS_CACHE_TTL_SECONDS, "-1");
249    }
250    else
251    {
252      StaticUtils.setSystemProperty(
253           JVM_PROPERTY_POSITIVE_ADDRESS_CACHE_TTL_SECONDS,
254           String.valueOf(seconds));
255    }
256  }
257
258
259
260  /**
261   * Sets the length of time in seconds for which the JVM should cache the
262   * results of unsuccessful name service lookups (that is, lookups in which no
263   * mapping is found).
264   * <BR><BR>
265   * Note that this timeout only applies to lookups performed by the JVM itself
266   * and may not apply to all name resolver implementations.  Some
267   * implementations may provide their own caching or their own lookup
268   * mechanisms that do not use this setting.
269   *
270   * @param  seconds  The length of time in seconds for which the JVM should
271   *                  cache the results of unsuccessful name service lookups.  A
272   *                  value that is less than zero indicates that values should
273   *                  be cached forever.
274   */
275  public static void setJVMUnsuccessfulLookupCacheTTLSeconds(final int seconds)
276  {
277    if (seconds < 0)
278    {
279      StaticUtils.setSystemProperty(
280           JVM_PROPERTY_NEGATIVE_ADDRESS_CACHE_TTL_SECONDS, "-1");
281    }
282    else
283    {
284      StaticUtils.setSystemProperty(
285           JVM_PROPERTY_NEGATIVE_ADDRESS_CACHE_TTL_SECONDS,
286           String.valueOf(seconds));
287    }
288  }
289
290
291
292  /**
293   * Retrieves a string representation of this name resolver.
294   *
295   * @return  A string representation of this name resolver.
296   */
297  @Override()
298  @NotNull()
299  public final String toString()
300  {
301    final StringBuilder buffer = new StringBuilder();
302    toString(buffer);
303    return buffer.toString();
304  }
305
306
307
308  /**
309   * Appends a string representation of this name resolver to the provided
310   * buffer.
311   *
312   * @param  buffer  A buffer to which the string representation should be
313   *                 appended.
314   */
315  public abstract void toString(@NotNull final StringBuilder buffer);
316}