Add missing javadoc

This commit is contained in:
Paul Schaub 2022-04-11 13:23:32 +02:00
parent a36e01d7d2
commit 0dc7ba1ecb
Signed by: vanitasvitae
GPG key ID: 62BEE9264BF17311
11 changed files with 176 additions and 4 deletions

View file

@ -9,20 +9,54 @@ import java.util.Arrays;
import java.util.List;
import java.util.Map;
/**
* Request email verification for email addresses of user-ids on a certificate.
*/
public interface RequestVerify {
/**
* Request email verification for the given email address.
*
* @param emailAddress email address
* @return builder
*/
default ForEmailAddresses forEmailAddress(String emailAddress) {
return forEmailAddresses(emailAddress);
}
/**
* Request email verification for one or more email addresses.
*
* @param emailAddresses email addresses
* @return builder
*/
ForEmailAddresses forEmailAddresses(String... emailAddresses);
interface ForEmailAddresses {
/**
* Execute the verification request using the given <pre>token</pre>, retrieved earlier by uploading the
* certificate to the server.
*
* @param token access token to authorize the request
* @return servers successful response
*
* @throws IOException in case of an error
*/
default Response execute(String token) throws IOException {
return execute(token, Arrays.asList("en_US", "en_GB"));
}
/**
* Execute the verification request using the given <pre>token</pre>, retrieved earlier by uploading the
* certificate to the server.
*
* @param token access token to authorize the request
* @param locale list of preferred locales for the verification emails
* @return servers successful response
*
* @throws IOException in case of an error
*/
Response execute(String token, List<String> locale) throws IOException;
}
@ -41,14 +75,29 @@ public interface RequestVerify {
this.token = token;
}
/**
* Return the uppercase OpenPGP fingerprint of the certificate.
*
* @return fingerprint
*/
public String getKeyFingerprint() {
return keyFingerprint;
}
/**
* Return a map of {@link Status States} of email addresses of user-ids on the certificate after requesting
* verification.
* @return status map
*/
public Map<String, Status> getStatus() {
return status;
}
/**
* Return an access token to be used to make further requests to the API.
*
* @return token
*/
public String getToken() {
return token;
}

View file

@ -4,6 +4,9 @@
package pgp.vks.client;
/**
* Enum representing different states an email address of a user-id on a certificate can be in.
*/
public enum Status {
/**

View file

@ -27,6 +27,11 @@ public class VKSImpl implements VKS {
this.api = new URLMapper(vksService);
}
/**
* Return a {@link VKSImpl} instance targeting the <pre>https://keys.openpgp.org</pre> VKS.
*
* @return VKS instance
*/
@SneakyThrows
public static VKS keysDotOpenPgpDotOrg() {
return new VKSImpl("https://keys.openpgp.org");

View file

@ -6,6 +6,9 @@ package pgp.vks.client.exception;
import java.net.ConnectException;
/**
* Exception gets thrown when a public key certificate cannot be published for some reason.
*/
public class CertCannotBePublishedException extends ConnectException {
public CertCannotBePublishedException(String errorMessage) {

View file

@ -6,12 +6,11 @@ package pgp.vks.client.exception;
import java.net.ConnectException;
/**
* Exception gets thrown when the queried OpenPGP certificate cannot be found on the server.
*/
public class CertNotFoundException extends ConnectException {
public CertNotFoundException() {
super();
}
public CertNotFoundException(String message) {
super(message);
}

View file

@ -4,6 +4,10 @@
package pgp.vks.client.exception;
/**
* Exception gets thrown when an unsupported API {@link pgp.vks.client.VKS.Version} is used.
* E.g. user wants to use some command using v2 API, but implementation only supports v1.
*/
public class UnsupportedApiException extends RuntimeException {
public UnsupportedApiException(String message) {

View file

@ -6,6 +6,11 @@ package pgp.vks.client.v1.dto;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Error response that gets returned by the server if a POST request fails.
*
* @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
*/
public class ErrorResponseDto {
private final String error;
@ -14,6 +19,11 @@ public class ErrorResponseDto {
this.error = error;
}
/**
* Return the error message.
*
* @return error message
*/
@JsonProperty("error")
public String getError() {
return error;

View file

@ -14,6 +14,11 @@ import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.Charset;
/**
* Request for uploading a certificate to the VKS.
*
* @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
*/
public class UploadRequestDto {
private static final byte[] ARMOR_HEADER = "-----BEGIN PGP PUBLIC KEY BLOCK-----".getBytes(Charset.forName("UTF8"));
@ -24,6 +29,15 @@ public class UploadRequestDto {
this.keytext = keytext;
}
/**
* Create an {@link UploadRequestDto} from an ASCII armored or binary OpenPGP certificate which is read from the
* given <pre>certInStream</pre>.
*
* @param certInStream {@link InputStream} containing the ASCII armored or binary OpenPGP certificate
* @return request DTO
*
* @throws IOException in case of an IO error
*/
public static UploadRequestDto fromInputStream(InputStream certInStream) throws IOException {
ByteArrayOutputStream certBuf = new ByteArrayOutputStream();
Streams.pipeAll(certInStream, certBuf);
@ -31,11 +45,26 @@ public class UploadRequestDto {
return fromBytes(certBuf.toByteArray());
}
/**
* Create an {@link UploadRequestDto} from an ASCII armored or binary OpenPGP certificate which is read from the
* given <pre>keytext</pre> byte array.
*
* @param keytext byte array containing the ASCII armored or binary OpenPGP certificate
* @return request DTO
*/
public static UploadRequestDto fromBytes(byte[] keytext) {
String armoredOrBase64 = new String(base64IfNecessary(keytext));
return new UploadRequestDto(armoredOrBase64);
}
/**
* Prepare a serialized OpenPGP certificate for upload.
* If the given <pre>certBytes</pre> contain an ASCII armored OpenPGP certificate, do nothing.
* Otherwise, consider the bytes to be the binary representation of an OpenPGP certificate and wrap it in Base64 encoding.
*
* @param certBytes certificate bytes
* @return Unmodified ASCII armored, or base64 encoded binary OpenPGP certificate
*/
private static byte[] base64IfNecessary(byte[] certBytes) {
if (!Arrays.areEqual(certBytes, 0, ARMOR_HEADER.length, ARMOR_HEADER, 0, ARMOR_HEADER.length)) {
certBytes = Base64.encode(certBytes);

View file

@ -11,6 +11,11 @@ import pgp.vks.client.Upload;
import java.util.HashMap;
import java.util.Map;
/**
* The VKS servers response to a successful upload.
*
* @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
*/
public class UploadResponseDto {
private final String key_fpr;
@ -25,21 +30,41 @@ public class UploadResponseDto {
this.token = token;
}
/**
* Uppercase fingerprint of the uploaded OpenPGP certificate.
*
* @return fingerprint
*/
@JsonProperty("key_fpr")
public String getKeyFingerprint() {
return key_fpr;
}
/**
* Access token which can be used for a limited time to request verification emails for user-ids on the certificate.
*
* @return access token
*/
@JsonProperty("token")
public String getToken() {
return token;
}
/**
* Map of {@link Status States} of email addresses of user-ids on the certificate.
*
* @return email status map
*/
@JsonProperty("status")
public Map<String, Status> getStatus() {
return new HashMap<>(status);
}
/**
* Convert the DTO into an entity.
*
* @return entity
*/
public Upload.Response toEntity() {
return new Upload.Response(getKeyFingerprint(), getStatus(), getToken());
}

View file

@ -8,6 +8,11 @@ import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* Request for email verification of one or more unpublished/pending user-ids.
*
* @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
*/
public class VerificationRequestDto {
private final String token;
@ -22,16 +27,31 @@ public class VerificationRequestDto {
this.locale = locale;
}
/**
* Return the token which was previously required by uploading a certificate using an {@link UploadRequestDto}.
*
* @return access token used to authenticate the request
*/
@JsonProperty("token")
public String getToken() {
return token;
}
/**
* {@link List} of email addresses for which to request email verification.
*
* @return email addresses
*/
@JsonProperty("addresses")
public List<String> getAddresses() {
return addresses;
}
/**
* {@link List} of preferred locales for the verification mails.
*
* @return locale list
*/
@JsonProperty("locale")
public List<String> getLocale() {
return locale;

View file

@ -10,6 +10,11 @@ import pgp.vks.client.Status;
import java.util.Map;
/**
* VKS servers response to a successful verification request.
*
* @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
*/
public class VerificationResponseDto {
private final String key_fpr;
@ -24,21 +29,41 @@ public class VerificationResponseDto {
this.token = token;
}
/**
* Uppercase OpenPGP fingerprint of the certificate.
*
* @return fingerprint
*/
@JsonProperty("key_fpr")
public String getKeyFingerprint() {
return key_fpr;
}
/**
* Access token which can be used to authenticate further verification requests.
*
* @return token
*/
@JsonProperty("token")
public String getToken() {
return token;
}
/**
* Map of {@link Status States} of email addresses of user-ids on the certificate.
*
* @return email address status map
*/
@JsonProperty("status")
public Map<String, Status> getStatus() {
return status;
}
/**
* Convert this DTO to an entity.
*
* @return entity
*/
public RequestVerify.Response toEntity() {
return new RequestVerify.Response(getKeyFingerprint(), getStatus(), getToken());
}