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}