package javax.naming.ldap;

import java.util.Hashtable;
import javax.naming.ldap.LdapDnsProviderResult;

/**
 * DNS provider abstract class whose concrete implementations are used by
 * {@code com.sun.jndi.ldap.LdapCtxFactory.getUsingURL()} to resolve ldap
 * server urls.
 *
 * The ServiceLoader is used to create and register implementations of
 * {@code LdapDnsProvider}.
 *
 * A DNS provider must subclass the {@link LdapDnsProvider} class.
 * In addition, the provider class must be public and must have a
 * public constructor that accepts no parameters.
 */
public abstract class LdapDnsProvider {

    /**
     * The {@code RuntimePermission("ldapDnsProvider")} is
     * necessary to subclass and instantiate the {@code LdapDnsProvider} class.
     */
    public static final RuntimePermission DNSPROVIDER_PERMISSION =
            new RuntimePermission("ldapDnsProvider");

    /**
     * Creates a new instance of {@code LdapDnsProvider}.
     *
     * @throws SecurityException if a security manager is present and its
     *         {@code checkPermission} method doesn't allow the
     *         {@code RuntimePermission("ldapDnsProvider")}.
     */
    protected LdapDnsProvider() {
        this(checkPermission());
    }

    private LdapDnsProvider(Void unused) {
        // nothing to do.
    }

    private static Void checkPermission() {
        final SecurityManager sm = System.getSecurityManager();
        if (sm != null) {
            sm.checkPermission(DNSPROVIDER_PERMISSION);
        }
        return null;
    }

    /**
     * The {@code lookupEndpoints(String url, Hashtable<?,?> env)} method
     * takes two parameters:
     *
     * @param url   The {@code Context.PROVIDER_URL}
     * @param env   The LdapCtx environment properties.
     *
     * @return  an {@link LdapDnsProviderResult}.
     */
    public abstract LdapDnsProviderResult lookupEndpoints(
            String url, Hashtable<?,?> env);

}