1 /****************************************************************
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 ****************************************************************/
19
20
21
22 package org.apache.james.api.dnsservice;
23
24 import java.net.InetAddress;
25 import java.net.UnknownHostException;
26 import java.util.Collection;
27 import java.util.Iterator;
28
29
30 /**
31 * Provides abstraction for DNS resolutions. The interface is Mail specific.
32 * It may be a good idea to make the interface more generic or expose
33 * commonly needed DNS methods.
34 *
35 */
36 public interface DNSService {
37
38 /**
39 * The component role used by components implementing this service
40 */
41 String ROLE = "org.apache.james.api.dnsservice.DNSService";
42
43 /**
44 * <p>Return a prioritized unmodifiable list of host handling mail
45 * for the domain.</p>
46 *
47 * <p>First lookup MX hosts, then MX hosts of the CNAME adress, and
48 * if no server is found return the IP of the hostname</p>
49 *
50 * @param hostname domain name to look up
51 *
52 * @return a unmodifiable list of handling servers corresponding to
53 * this mail domain name
54 * @throws TemporaryResolutionException get thrown on temporary problems
55 */
56 Collection findMXRecords(String hostname) throws TemporaryResolutionException;
57
58 /**
59 * Get a collection of DNS TXT Records
60 *
61 * @param hostname The hostname to check
62 * @return collection of strings representing TXT record values
63 */
64 Collection findTXTRecords(String hostname);
65
66
67 /**
68 * Returns an Iterator over org.apache.mailet.HostAddress, a
69 * specialized subclass of javax.mail.URLName, which provides
70 * location information for servers that are specified as mail
71 * handlers for the given hostname. This is done using MX records,
72 * and the HostAddress instances are returned sorted by MX priority.
73 * If no host is found for domainName, the Iterator returned will be
74 * empty and the first call to hasNext() will return false. The
75 * Iterator is a nested iterator: the outer iteration is over the
76 * results of the MX record lookup, and the inner iteration is over
77 * potentially multiple A records for each MX record. DNS lookups
78 * are deferred until actually needed.
79 *
80 * @since v2.2.0a16-unstable
81 * @param domainName - the domain for which to find mail servers
82 * @return an Iterator over HostAddress instances, sorted by priority
83 * @throws TemporaryResolutionException get thrown on temporary problems
84 */
85 Iterator getSMTPHostAddresses(String domainName) throws TemporaryResolutionException;
86
87 /**
88 * @see java.net.InetAddress#getAllByName(String)
89 */
90 public InetAddress[] getAllByName(String host) throws UnknownHostException;
91
92 /**
93 * @see java.net.InetAddress#getByName(String)
94 */
95 public InetAddress getByName(String host) throws UnknownHostException;
96
97 /**
98 * @see org.xbill.DNS.Address#getHostName(InetAddress)
99 */
100 public String getHostName(InetAddress addr);
101
102 /**
103 */
104 public InetAddress getLocalHost() throws UnknownHostException;
105 }