/*
 * Copied from the DnsJava project
 *
 * Copyright (c) 1998-2011, Brian Wellington.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   * Redistributions of source code must retain the above copyright notice,
 *     this list of conditions and the following disclaimer.
 *
 *   * Redistributions in binary form must reproduce the above copyright notice,
 *     this list of conditions and the following disclaimer in the documentation
 *     and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

package io.milton.dns.record;


import java.io.*;
import java.util.*;

/**
 * Interface describing a resolver.
 *
 * @author Brian Wellington
 */

public interface Resolver {

/**
 * Sets the port to communicate with on the server
 * @param port The port to send messages to
 */
void setPort(int port);

/**
 * Sets whether TCP connections will be sent by default
 * @param flag Indicates whether TCP connections are made
 */
void setTCP(boolean flag);

/**
 * Sets whether truncated responses will be ignored.  If not, a truncated
 * response over UDP will cause a retransmission over TCP.
 * @param flag Indicates whether truncated responses should be ignored.
 */
void setIgnoreTruncation(boolean flag);

/**
 * Sets the EDNS version used on outgoing messages.
 * @param level The EDNS level to use.  0 indicates EDNS0 and -1 indicates no
 * EDNS.
 * @throws IllegalArgumentException An invalid level was indicated.
 */
void setEDNS(int level);

/**
 * Sets the EDNS information on outgoing messages.
 * @param level The EDNS level to use.  0 indicates EDNS0 and -1 indicates no
 * EDNS.
 * @param payloadSize The maximum DNS packet size that this host is capable
 * of receiving over UDP.  If 0 is specified, the default (1280) is used.
 * @param flags EDNS extended flags to be set in the OPT record.
 * @param options EDNS options to be set in the OPT record, specified as a
 * List of OPTRecord.Option elements.
 * @throws IllegalArgumentException An invalid field was specified.
 * @see OPTRecord
 */
void setEDNS(int level, int payloadSize, int flags, List options);

/**
 * Specifies the TSIG key that messages will be signed with
 * @param key The key
 */
void setTSIGKey(TSIG key);

/**
 * Sets the amount of time to wait for a response before giving up.
 * @param secs The number of seconds to wait.
 * @param msecs The number of milliseconds to wait.
 */
void setTimeout(int secs, int msecs);

/**
 * Sets the amount of time to wait for a response before giving up.
 * @param secs The number of seconds to wait.
 */
void setTimeout(int secs);

/**
 * Sends a message and waits for a response.
 * @param query The query to send.
 * @return The response
 * @throws IOException An error occurred while sending or receiving.
 */
Message send(Message query) throws IOException;

/**
 * Asynchronously sends a message registering a listener to receive a callback
 * on success or exception.  Multiple asynchronous lookups can be performed
 * in parallel.  Since the callback may be invoked before the function returns,
 * external synchronization is necessary.
 * @param query The query to send
 * @param listener The object containing the callbacks.
 * @return An identifier, which is also a parameter in the callback
 */
Object sendAsync(final Message query, final ResolverListener listener);

}