1 /*
2  * Copyright (C) 2012 Square, Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package okhttp3;
17
18 import java.net.InetAddress;
19 import java.net.UnknownHostException;
20 import java.util.Arrays;
21 import java.util.List;
22
23 /**
24  * A domain name service that resolves IP addresses for host names. Most applications will use the
25  * {@linkplain #SYSTEM system DNS service}, which is the default. Some applications may provide
26  * their own implementation to use a different DNS server, to prefer IPv6 addresses, to prefer IPv4
27  * addresses, or to force a specific known IP address.
28  *
29  * <p>Implementations of this interface must be safe for concurrent use.
30  */
31 public interface Dns {
32   /**
33    * A DNS that uses {@link InetAddress#getAllByName} to ask the underlying operating system to
34    * lookup IP addresses. Most custom {@link Dns} implementations should delegate to this instance.
35    */
36   Dns SYSTEM = hostname -> {
37     if (hostname == null) throw new UnknownHostException("hostname == null");
38     try {
39       return Arrays.asList(InetAddress.getAllByName(hostname));
40     } catch (NullPointerException e) {
41       UnknownHostException unknownHostException =
42           new UnknownHostException("Broken system behaviour for dns lookup of " + hostname);
43       unknownHostException.initCause(e);
44       throw unknownHostException;
45     }
46   };
47
48   /**
49    * Returns the IP addresses of {@code hostname}, in the order they will be attempted by OkHttp. If
50    * a connection to an address fails, OkHttp will retry the connection with the next address until
51    * either a connection is made, the set of IP addresses is exhausted, or a limit is exceeded.
52    */
53   List<InetAddress> lookup(String hostname) throws UnknownHostException;
54 }
55