From 0e8bf060f2cbb3f8c7308b73c690d0297899e354 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Sat, 27 Aug 2022 13:33:52 +0200 Subject: [PATCH] Update javadoc to reflect what happens when a cert is queried but not found --- .../cert_d/ReadOnlyPGPCertificateDirectory.java | 16 ++++++++++------ .../certificate_store/PGPCertificateStore.java | 4 +++- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/pgp-cert-d-java/src/main/java/pgp/cert_d/ReadOnlyPGPCertificateDirectory.java b/pgp-cert-d-java/src/main/java/pgp/cert_d/ReadOnlyPGPCertificateDirectory.java index 0b1416c..72b048b 100644 --- a/pgp-cert-d-java/src/main/java/pgp/cert_d/ReadOnlyPGPCertificateDirectory.java +++ b/pgp-cert-d-java/src/main/java/pgp/cert_d/ReadOnlyPGPCertificateDirectory.java @@ -10,6 +10,7 @@ import pgp.certificate_store.exception.BadNameException; import java.io.IOException; import java.util.Iterator; +import java.util.NoSuchElementException; /** * Interface for a read-only OpenPGP certificate directory. @@ -19,12 +20,12 @@ public interface ReadOnlyPGPCertificateDirectory { /** * Get the trust-root certificate. This is a certificate which is stored under the special name * 
trust-root
. - * If no such certificate is found, 
null
is returned. * * @return trust-root certificate * * @throws IOException in case of an IO error * @throws BadDataException if the certificate contains bad data + * @throws NoSuchElementException if no such certificate is found */ Certificate getTrustRootCertificate() throws IOException, BadDataException; @@ -36,24 +37,25 @@ public interface ReadOnlyPGPCertificateDirectory { * Otherwise. the changed certificate is returned. * * @param tag tag - * @return changed certificate, or null if the certificate is unchanged or not found. + * @return changed certificate, or null if the certificate is unchanged. * * @throws IOException in case of an IO error * @throws BadDataException if the certificate contains bad data + * @throws NoSuchElementException if no such certificate is found */ Certificate getTrustRootCertificateIfChanged(long tag) throws IOException, BadDataException; /** * Get the certificate identified by the given fingerprint. - * If no such certificate is found, return 
null
. * * @param fingerprint lower-case fingerprint of the certificate - * @return certificate or null if no such certificate has been found + * @return certificate * * @throws IOException in case of an IO error * @throws BadNameException if the fingerprint is malformed * @throws BadDataException if the certificate contains bad data + * @throws NoSuchElementException if no such certificate is found */ Certificate getByFingerprint(String fingerprint) throws IOException, BadNameException, BadDataException; @@ -66,18 +68,18 @@ public interface ReadOnlyPGPCertificateDirectory { * * @param fingerprint lower-case fingerprint of the certificate * @param tag tag - * @return certificate or null if the certificate has not been changed or has not been found + * @return certificate or null if the certificate has not been changed * * @throws IOException in case of an IO error * @throws BadNameException if the fingerprint is malformed * @throws BadDataException if the certificate contains bad data + * @throws NoSuchElementException if no such certificate is found */ Certificate getByFingerprintIfChanged(String fingerprint, long tag) throws IOException, BadNameException, BadDataException; /** * Get the certificate identified by the given special name. - * If no such certificate is found, 
null
is returned. * * @param specialName special name * @return certificate or null @@ -85,6 +87,7 @@ public interface ReadOnlyPGPCertificateDirectory { * @throws IOException in case of an IO error * @throws BadNameException if the special name is not known * @throws BadDataException if the certificate contains bad data + * @throws NoSuchElementException if no such certificate is found */ Certificate getBySpecialName(String specialName) throws IOException, BadNameException, BadDataException; @@ -102,6 +105,7 @@ public interface ReadOnlyPGPCertificateDirectory { * @throws IOException in case of an IO error * @throws BadNameException if the special name is not known * @throws BadDataException if the certificate contains bad data + * @throws NoSuchElementException if no such certificate is found */ Certificate getBySpecialNameIfChanged(String specialName, long tag) throws IOException, BadNameException, BadDataException; diff --git a/pgp-certificate-store/src/main/java/pgp/certificate_store/PGPCertificateStore.java b/pgp-certificate-store/src/main/java/pgp/certificate_store/PGPCertificateStore.java index d0915b0..251229f 100644 --- a/pgp-certificate-store/src/main/java/pgp/certificate_store/PGPCertificateStore.java +++ b/pgp-certificate-store/src/main/java/pgp/certificate_store/PGPCertificateStore.java @@ -12,6 +12,7 @@ import pgp.certificate_store.exception.BadNameException; import java.io.IOException; import java.io.InputStream; import java.util.Iterator; +import java.util.NoSuchElementException; /** * Interface for an OpenPGP certificate (public key) store. @@ -20,7 +21,6 @@ public interface PGPCertificateStore { /** * Return the certificate that matches the given identifier. - * If no matching certificate can be found, return null. * * @param identifier identifier for a certificate. * @return certificate or null @@ -28,6 +28,7 @@ public interface PGPCertificateStore { * @throws IOException in case of an IO-error * @throws BadNameException if the identifier is invalid * @throws BadDataException if the certificate file contains invalid data + * @throws NoSuchElementException if no such certificate is found */ Certificate getCertificate(String identifier) throws IOException, BadNameException, BadDataException; @@ -45,6 +46,7 @@ public interface PGPCertificateStore { * @throws IOException in case of an IO-error * @throws BadNameException if the identifier is invalid * @throws BadDataException if the certificate file contains invalid data + * @throws NoSuchElementException if no such certificate is found */ Certificate getCertificateIfChanged(String identifier, Long tag) throws IOException, BadNameException, BadDataException;