Update javadoc to reflect what happens when a cert is queried but not found

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
      * <pre>trust-root</pre>.
-     * If no such certificate is found, <pre>null</pre> 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 <pre>null</pre>.
      *
      * @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, <pre>null</pre> 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;

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;