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}