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