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.connector.NetworkSettings;
026import org.shredzone.acme4j.exception.AcmeException;
027import org.shredzone.acme4j.toolbox.JSON;
028
029/**
030 * An {@link AcmeProvider} provides methods to be used for communicating with the ACME
031 * server. Implementations handle individual features of each ACME server.
032 * <p>
033 * Provider implementations must be registered with Java's {@link ServiceLoader}.
034 */
035public interface AcmeProvider {
036
037    /**
038     * Checks if this provider accepts the given server URI.
039     *
040     * @param serverUri
041     *            Server URI to test
042     * @return {@code true} if this provider accepts the server URI, {@code false}
043     *         otherwise
044     */
045    boolean accepts(URI serverUri);
046
047    /**
048     * Resolves the server URI and returns the matching directory URL.
049     *
050     * @param serverUri
051     *            Server {@link URI}
052     * @return Resolved directory {@link URL}
053     * @throws IllegalArgumentException
054     *             if the server {@link URI} is not accepted
055     */
056    URL resolve(URI serverUri);
057
058    /**
059     * Creates a {@link Connection} for communication with the ACME server.
060     *
061     * @param serverUri
062     *         Server {@link URI}
063     * @param networkSettings
064     *         {@link NetworkSettings} to be used for the connection
065     * @return {@link Connection} that was generated
066     */
067    Connection connect(URI serverUri, NetworkSettings networkSettings);
068
069    /**
070     * Returns the provider's directory. The structure must contain resource URLs, and may
071     * optionally contain metadata.
072     * <p>
073     * The default implementation resolves the server URI and fetches the directory via
074     * HTTP request. Subclasses may override this method, e.g. if the directory is static.
075     *
076     * @param session
077     *            {@link Session} to be used
078     * @param serverUri
079     *            Server {@link URI}
080     * @return Directory data, as JSON object, or {@code null} if the directory has not
081     * been changed since the last request.
082     */
083    @Nullable
084    JSON directory(Session session, URI serverUri) throws AcmeException;
085
086    /**
087     * Creates a {@link Challenge} instance for the given challenge data.
088     *
089     * @param login
090     *            {@link Login} to bind the challenge to
091     * @param data
092     *            Challenge {@link JSON} data
093     * @return {@link Challenge} instance, or {@code null} if this provider is unable to
094     *         generate a matching {@link Challenge} instance.
095     */
096    @Nullable
097    Challenge createChallenge(Login login, JSON data);
098
099}