Module org.shredzone.acme4j

Package org.shredzone.acme4j.connector

Interface Connection

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

DefaultConnection

public interface Connection
extends AutoCloseable

Connects to the ACME server and offers different methods for invoking the API.

The actual way of communicating with the ACME server is intentionally left open. Implementations could use other means than HTTP, or could mock the communication for unit testing.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes the Connection, releasing all resources.
Optional<ZonedDateTime>	getExpiration()	Returns the expiration date of the resource, if present.
Optional<ZonedDateTime>	getLastModified()	Returns the content of the last-modified header, if present.
Collection<URL>	getLinks(String relation)	Gets one or more relation links from the header.
URL	getLocation()	Gets a location from the Location header.
Optional<String>	getNonce()	Gets the nonce from the nonce header.
Optional<Instant>	getRetryAfter()	Returns the Retry-After header if present.
default void	handleRetryAfter(String message)	Deprecated. Prefer to use getRetryAfter().
List<X509Certificate>	readCertificates()	Reads a certificate and its chain of issuers.
JSON	readJsonResponse()	Reads a server response as JSON object.
void	resetNonce(Session session)	Resets the session nonce, by fetching a new one.
int	sendCertificateRequest(URL url, Login login)	Sends a signed POST-as-GET request for a certificate resource.
int	sendRequest(URL url, Session session, ZonedDateTime ifModifiedSince)	Sends a simple GET request.
int	sendSignedPostAsGetRequest(URL url, Login login)	Sends a signed POST-as-GET request.
int	sendSignedRequest(URL url, JSONBuilder claims, Login login)	Sends a signed POST request.
int	sendSignedRequest(URL url, JSONBuilder claims, Session session, KeyPair keypair)	Sends a signed POST request.

Method Detail

resetNonce

void resetNonce(Session session)
         throws AcmeException

Resets the session nonce, by fetching a new one.

Parameters:

session - Session instance to fetch a nonce for

Throws:

AcmeException

sendRequest

int sendRequest(URL url,
                Session session,
                @Nullable
                ZonedDateTime ifModifiedSince)
         throws AcmeException

Sends a simple GET request.

If the response code was not HTTP status 200, an AcmeException matching the error is raised.

Parameters:

url - URL to send the request to.

session - Session instance to be used for tracking

ifModifiedSince - ZonedDateTime to be sent as "If-Modified-Since" header, or null if this header is not to be used

Returns:

HTTP status that was returned

Throws:

AcmeException

sendCertificateRequest

int sendCertificateRequest(URL url,
                           Login login)
                    throws AcmeException

Sends a signed POST-as-GET request for a certificate resource. Requires a Login for the session and KeyPair. The Login account location is sent in a "kid" protected header.

If the server does not return a 200 class status code, an AcmeException is raised matching the error.

Parameters:

url - URL to send the request to.

login - Login instance to be used for signing and tracking.

Returns:

HTTP 200 class status that was returned

Throws:

AcmeException

sendSignedPostAsGetRequest

int sendSignedPostAsGetRequest(URL url,
                               Login login)
                        throws AcmeException

Sends a signed POST-as-GET request. Requires a Login for the session and KeyPair. The Login account location is sent in a "kid" protected header.

If the server does not return a 200 class status code, an AcmeException is raised matching the error.

Parameters:

url - URL to send the request to.

login - Login instance to be used for signing and tracking.

Returns:

HTTP 200 class status that was returned

Throws:

AcmeException

sendSignedRequest

int sendSignedRequest(URL url,
                      JSONBuilder claims,
                      Login login)
               throws AcmeException

Sends a signed POST request. Requires a Login for the session and KeyPair. The Login account location is sent in a "kid" protected header.

If the server does not return a 200 class status code, an AcmeException is raised matching the error.

Parameters:

url - URL to send the request to.

claims - JSONBuilder containing claims.

login - Login instance to be used for signing and tracking.

Returns:

HTTP 200 class status that was returned

Throws:

AcmeException

sendSignedRequest

int sendSignedRequest(URL url,
                      JSONBuilder claims,
                      Session session,
                      KeyPair keypair)
               throws AcmeException

Sends a signed POST request. Only requires a Session. The KeyPair is sent in a "jwk" protected header field.

If the server does not return a 200 class status code, an AcmeException is raised matching the error.

Parameters:

url - URL to send the request to.

claims - JSONBuilder containing claims.

session - Session instance to be used for tracking.

keypair - KeyPair to be used for signing.

Returns:

HTTP 200 class status that was returned

Throws:

AcmeException

readJsonResponse

JSON readJsonResponse()
               throws AcmeException

Reads a server response as JSON object.

Returns:

The JSON response.

Throws:

AcmeException

readCertificates

List<X509Certificate> readCertificates()
                                throws AcmeException

Reads a certificate and its chain of issuers.

Returns:

List of X.509 certificate and chain that was read.

Throws:

AcmeException

getRetryAfter

Optional<Instant> getRetryAfter()

Returns the Retry-After header if present.

Since:

3.0.0

handleRetryAfter

@Deprecated
default void handleRetryAfter(String message)
                       throws AcmeException

Deprecated.

Prefer to use getRetryAfter().

Throws an AcmeRetryAfterException if the last status was HTTP Accepted and a Retry-After header was received.

Parameters:

message - Message to be sent along with the AcmeRetryAfterException

Throws:

AcmeException

getNonce

Optional<String> getNonce()

Gets the nonce from the nonce header.

Returns:

Base64 encoded nonce, or empty if no nonce header was set

getLocation

URL getLocation()

Gets a location from the Location header.

Relative links are resolved against the last request's URL.

Returns:

Location URL

Throws:

AcmeProtocolException - if the location header is missing

getLastModified

Optional<ZonedDateTime> getLastModified()

Returns the content of the last-modified header, if present.

Returns:

Date in the Last-Modified header, or empty if the server did not provide this information.

Since:

2.10

getExpiration

Optional<ZonedDateTime> getExpiration()

Returns the expiration date of the resource, if present.

Returns:

Expiration date, either from the Cache-Control or Expires header. If empty, the server did not provide an expiration date, or forbid caching.

Since:

2.10

getLinks

Collection<URL> getLinks(String relation)

Gets one or more relation links from the header. The result is expected to be a URL.

Relative links are resolved against the last request's URL.

Parameters:

relation - Link relation

Returns:

Collection of links. Empty if there was no such relation.

close

void close()

Closes the Connection, releasing all resources.

Specified by:

close in interface AutoCloseable