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.connector; 015 016import java.net.URI; 017import java.net.URL; 018import java.security.cert.X509Certificate; 019 020import org.shredzone.acme4j.Session; 021import org.shredzone.acme4j.exception.AcmeException; 022import org.shredzone.acme4j.exception.AcmeRetryAfterException; 023import org.shredzone.acme4j.toolbox.JSON; 024import org.shredzone.acme4j.toolbox.JSONBuilder; 025 026/** 027 * Connects to the ACME server and offers different methods for invoking the API. 028 */ 029public interface Connection extends AutoCloseable { 030 031 /** 032 * Sends a simple GET request. 033 * 034 * @param url 035 * {@link URL} to send the request to. 036 * @param session 037 * {@link Session} instance to be used for tracking 038 */ 039 void sendRequest(URL url, Session session) throws AcmeException; 040 041 /** 042 * Sends a signed POST request. 043 * 044 * @param url 045 * {@link URL} to send the request to. 046 * @param claims 047 * {@link JSONBuilder} containing claims. Must not be {@code null}. 048 * @param session 049 * {@link Session} instance to be used for signing and tracking 050 */ 051 void sendSignedRequest(URL url, JSONBuilder claims, Session session) throws AcmeException; 052 053 /** 054 * Checks if the HTTP response status is in the given list of acceptable HTTP states, 055 * otherwise raises an {@link AcmeException} matching the error. 056 * 057 * @param httpStatus 058 * Acceptable HTTP states 059 * @return Actual HTTP status that was accepted 060 */ 061 int accept(int... httpStatus) throws AcmeException; 062 063 /** 064 * Reads a server response as JSON data. 065 * 066 * @return The JSON response 067 */ 068 JSON readJsonResponse() throws AcmeException; 069 070 /** 071 * Reads a certificate. 072 * 073 * @return {@link X509Certificate} that was read. 074 */ 075 X509Certificate readCertificate() throws AcmeException; 076 077 /** 078 * Throws an {@link AcmeRetryAfterException} if the last status was HTTP Accepted and 079 * a Retry-After header was received. 080 * 081 * @param message 082 * Message to be sent along with the {@link AcmeRetryAfterException} 083 */ 084 void handleRetryAfter(String message) throws AcmeException; 085 086 /** 087 * Updates a {@link Session} by evaluating the HTTP response header. 088 * 089 * @param session 090 * {@link Session} instance to be updated 091 */ 092 void updateSession(Session session); 093 094 /** 095 * Gets a location from the {@code Location} header. 096 * <p> 097 * Relative links are resolved against the last request's URL. 098 * 099 * @return Location {@link URL}, or {@code null} if no Location header was set 100 */ 101 URL getLocation(); 102 103 /** 104 * Gets a relation link from the header. 105 * <p> 106 * Relative links are resolved against the last request's URL. If there is more than 107 * one relation, the first one is returned. 108 * 109 * @param relation 110 * Link relation 111 * @return Link {@link URL}, or {@code null} if there was no such relation link 112 */ 113 URL getLink(String relation); 114 115 /** 116 * Gets a relation link from the header. 117 * <p> 118 * Relative links are resolved against the last request's URL. If there is more than 119 * one relation, the first one is returned. 120 * 121 * @param relation 122 * Link relation 123 * @return Link {@link URI}, or {@code null} if there was no such relation link 124 */ 125 URI getLinkAsURI(String relation); 126 127 /** 128 * Closes the {@link Connection}, releasing all resources. 129 */ 130 @Override 131 void close(); 132 133}