001/*
002 * acme4j - Java ACME client
003 *
004 * Copyright (C) 2015 Richard "Shred" K├Ârber
005 *   http://acme4j.shredzone.org
006 *
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
013 */
014package org.shredzone.acme4j.provider;
015
016import java.net.URI;
017import java.net.URL;
018import java.util.ServiceLoader;
019
020import edu.umd.cs.findbugs.annotations.Nullable;
021import org.shredzone.acme4j.Login;
022import org.shredzone.acme4j.Session;
023import org.shredzone.acme4j.challenge.Challenge;
024import org.shredzone.acme4j.connector.Connection;
025import org.shredzone.acme4j.exception.AcmeException;
026import org.shredzone.acme4j.toolbox.JSON;
027
028/**
029 * An {@link AcmeProvider} provides methods to be used for communicating with the ACME
030 * server. Implementations handle individual features of each ACME server.
031 * <p>
032 * Provider implementations must be registered with Java's {@link ServiceLoader}.
033 */
034public interface AcmeProvider {
035
036    /**
037     * Checks if this provider accepts the given server URI.
038     *
039     * @param serverUri
040     *            Server URI to test
041     * @return {@code true} if this provider accepts the server URI, {@code false}
042     *         otherwise
043     */
044    boolean accepts(URI serverUri);
045
046    /**
047     * Resolves the server URI and returns the matching directory URL.
048     *
049     * @param serverUri
050     *            Server {@link URI}
051     * @return Resolved directory {@link URL}
052     * @throws IllegalArgumentException
053     *             if the server {@link URI} is not accepted
054     */
055    URL resolve(URI serverUri);
056
057    /**
058     * Creates a {@link Connection} for communication with the ACME server.
059     *
060     * @param serverUri
061     *            Server {@link URI}
062     * @return {@link Connection} that was generated
063     */
064    Connection connect(URI serverUri);
065
066    /**
067     * Returns the provider's directory. The structure must contain resource URLs, and may
068     * optionally contain metadata.
069     * <p>
070     * The default implementation resolves the server URI and fetches the directory via
071     * HTTP request. Subclasses may override this method, e.g. if the directory is static.
072     *
073     * @param session
074     *            {@link Session} to be used
075     * @param serverUri
076     *            Server {@link URI}
077     * @return Directory data, as JSON object, or {@code null} if the directory has not
078     * been changed since the last request.
079     */
080    @Nullable
081    JSON directory(Session session, URI serverUri) throws AcmeException;
082
083    /**
084     * Creates a {@link Challenge} instance for the given challenge data.
085     *
086     * @param login
087     *            {@link Login} to bind the challenge to
088     * @param data
089     *            Challenge {@link JSON} data
090     * @return {@link Challenge} instance, or {@code null} if this provider is unable to
091     *         generate a matching {@link Challenge} instance.
092     */
093    @Nullable
094    Challenge createChallenge(Login login, JSON data);
095
096}