001 /****************************************************************
002 * Licensed to the Apache Software Foundation (ASF) under one *
003 * or more contributor license agreements. See the NOTICE file *
004 * distributed with this work for additional information *
005 * regarding copyright ownership. The ASF licenses this file *
006 * to you under the Apache License, Version 2.0 (the *
007 * "License"); you may not use this file except in compliance *
008 * with the License. You may obtain a copy of the License at *
009 * *
010 * http://www.apache.org/licenses/LICENSE-2.0 *
011 * *
012 * Unless required by applicable law or agreed to in writing, *
013 * software distributed under the License is distributed on an *
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
015 * KIND, either express or implied. See the License for the *
016 * specific language governing permissions and limitations *
017 * under the License. *
018 ****************************************************************/
019
020
021
022 package org.apache.james.protocols.smtp;
023
024 import java.net.InetAddress;
025 import java.net.UnknownHostException;
026 import java.util.Collection;
027 import java.util.Iterator;
028
029 import org.apache.mailet.HostAddress;
030
031
032 /**
033 * Provides abstraction for DNS resolutions. The interface is Mail specific.
034 * It may be a good idea to make the interface more generic or expose
035 * commonly needed DNS methods.
036 *
037 */
038 public interface DNSService {
039
040 /**
041 * The component role used by components implementing this service
042 */
043 String ROLE = "org.apache.james.smtpserver.protocol.DNSService";
044
045 /**
046 * <p>Return a prioritized unmodifiable list of host handling mail
047 * for the domain.</p>
048 *
049 * <p>First lookup MX hosts, then MX hosts of the CNAME adress, and
050 * if no server is found return the IP of the hostname</p>
051 *
052 * @param hostname domain name to look up
053 *
054 * @return a unmodifiable list of handling servers corresponding to
055 * this mail domain name
056 * @throws TemporaryResolutionException get thrown on temporary problems
057 */
058 Collection<String> findMXRecords(String hostname) throws TemporaryResolutionException;
059
060 /**
061 * Get a collection of DNS TXT Records
062 *
063 * @param hostname The hostname to check
064 * @return collection of strings representing TXT record values
065 */
066 Collection<String> findTXTRecords(String hostname);
067
068
069 /**
070 * Returns an Iterator over org.apache.mailet.HostAddress, a
071 * specialized subclass of javax.mail.URLName, which provides
072 * location information for servers that are specified as mail
073 * handlers for the given hostname. This is done using MX records,
074 * and the HostAddress instances are returned sorted by MX priority.
075 * If no host is found for domainName, the Iterator returned will be
076 * empty and the first call to hasNext() will return false. The
077 * Iterator is a nested iterator: the outer iteration is over the
078 * results of the MX record lookup, and the inner iteration is over
079 * potentially multiple A records for each MX record. DNS lookups
080 * are deferred until actually needed.
081 *
082 * @since v2.2.0a16-unstable
083 * @param domainName - the domain for which to find mail servers
084 * @return an Iterator over HostAddress instances, sorted by priority
085 * @throws TemporaryResolutionException get thrown on temporary problems
086 */
087 Iterator<HostAddress> getSMTPHostAddresses(String domainName) throws TemporaryResolutionException;
088
089 /**
090 * @see java.net.InetAddress#getAllByName(String)
091 */
092 InetAddress[] getAllByName(String host) throws UnknownHostException;
093
094 /**
095 * @see java.net.InetAddress#getByName(String)
096 */
097 InetAddress getByName(String host) throws UnknownHostException;
098
099 /**
100 * Determines the hostname for an address
101 * @param addr
102 * the address record
103 * @return
104 * the hostname defined in the address record
105 */
106 String getHostName(InetAddress addr);
107
108
109 /**
110 * get the local hosts {@link InetAddress}
111 * @return
112 * the localhosts inet address
113 * @throws UnknownHostException
114 */
115 InetAddress getLocalHost() throws UnknownHostException;
116 }