Improve javadoc (#1493)

Author: gcatanese

src/main/java/com/adyen/ApiKeyAuthenticatedService.java

@@ -21,9 +21,12 @@
 package com.adyen;
 
 /**
- * The ApiKeyAuthenticatedService is an interface to enable a child service to support API key authentication feature.
- */
-public class ApiKeyAuthenticatedService extends Service {
+ * A service base class that enforces API key authentication.
+ * <p>
+ * This class extends Service and ensures that any extending service
+ * requires an API key for authentication.
+ * </p>
+ */public class ApiKeyAuthenticatedService extends Service {
 
     protected ApiKeyAuthenticatedService(Client client) {
         super(client);

src/main/java/com/adyen/Service.java

@@ -22,6 +22,9 @@
 
 import com.adyen.enums.Environment;
 
+/**
+ * Parent class for all Service implementations
+ */
 public class Service {
     private boolean isApiKeyRequired = false;
     private Client client;

src/main/java/com/adyen/builders/terminal/TerminalAPIRequestBuilder.java

@@ -58,6 +58,31 @@
 
 import static com.adyen.constants.ApiConstants.TerminalAPI.PROTOCOL_VERSION;
 
+/**
+ * Builder for constructing a TerminalAPIRequest using the fluent interface pattern.
+ * <p>
+ * This builder allows you to configure and create various types of Terminal API requests by setting
+ * the appropriate request object and associated metadata such as MessageClassType and
+ * MessageCategoryType.
+ * </p>
+ *
+ * <p>
+ * Each type of Terminal API request (e.g. PaymentRequest, BalanceInquiryRequest, etc.)
+ * has a dedicated `withXRequest` method that sets the necessary fields and message types internally.
+ * Once all necessary fields are set, call build() to generate the TerminalAPIRequest.
+ * </p>
+ *
+ * <p>
+ * Example usage:
+ * </p>
+ * <pre>{@code
+ * TerminalAPIRequest request = new TerminalAPIRequestBuilder("Sale001", "Service001", "POI001")
+ *     .withPaymentRequest(paymentRequest)
+ *     .withSecurityTrailer(contentInformation)
+ *     .build();
+ * }</pre>
+ *
+ */
 public final class TerminalAPIRequestBuilder {
 
     // MessageHeader

src/main/java/com/adyen/httpclient/AdyenHttpClient.java

@@ -63,6 +63,10 @@
 import static com.adyen.constants.ApiConstants.RequestProperty.REQUESTED_VERIFICATION_CODE_HEADER;
 import static com.adyen.constants.ApiConstants.RequestProperty.USER_AGENT;
 
+/**
+ * HTTP client implementation to invoke the Adyen APIs.
+ * Built on top of org.apache.hc.client5
+ */
 public class AdyenHttpClient implements ClientInterface {
 
     private static final String CHARSET = "UTF-8";

src/main/java/com/adyen/httpclient/TerminalLocalAPIHostnameVerifier.java

@@ -8,19 +8,48 @@
 import javax.net.ssl.SSLSession;
 import java.security.cert.X509Certificate;
 
+/**
+ * A custom HostnameVerifier implementation for verifying SSL connections to
+ * Adyen Terminal Local APIs. This verifier ensures the peer certificate's common name (CN)
+ * matches expected patterns based on the current Environment.
+ * <p>
+ * This is typically used to verify secure connections to payment terminals on local networks.
+ *
+ * <p>It validates the hostname by inspecting the leaf certificate (first in the chain)
+ * and checking it against allowed CNs using TerminalCommonNameValidator.
+ *
+ * @see TerminalCommonNameValidator
+ * @see Environment
+ */
 public final class TerminalLocalAPIHostnameVerifier implements HostnameVerifier {
+
+    /**
+     * The Adyen environment (e.g., TEST, LIVE) that determines which hostnames are valid.
+     */
     private final Environment environment;
 
+    /**
+     * Constructs a new {@code TerminalLocalAPIHostnameVerifier} with the specified environment.
+     *
+     * @param environment The Adyen environment used for validating terminal hostnames.
+     */
     public TerminalLocalAPIHostnameVerifier(Environment environment) {
         this.environment = environment;
     }
 
+    /**
+     * Verifies the hostname of an SSL session by inspecting the peer's certificate
+     * and validating its common name against expected values for the given environment.
+     *
+     * @param hostname the hostname to verify.
+     * @param session the SSL session associated with the connection.
+     * @return {@code true} if the hostname is valid for the given environment; {@code false} otherwise.
+     */
     @Override
     public boolean verify(String hostname, SSLSession session) {
         try {
             if (session.getPeerCertificates() != null && session.getPeerCertificates().length > 0) {
-                // Assume the first certificate is the leaf, since chain will be ordered, according to Java documentation:
-                // https://docs.oracle.com/javase/7/docs/api/javax/net/ssl/SSLSession.html#getPeerCertificates()
+                // Assume the first certificate is the leaf, since chain will be ordered.
                 X509Certificate certificate = (X509Certificate) session.getPeerCertificates()[0];
                 return TerminalCommonNameValidator.validateCertificate(certificate, environment);
             }

src/main/java/com/adyen/util/CertificateUtil.java

@@ -32,26 +32,29 @@
 import java.security.cert.CertificateException;
 import java.security.cert.CertificateFactory;
 
+/**
+ * Utility class for loading X.509 certificates and Java KeyStores.
+ */
 public final class CertificateUtil {
 
     private CertificateUtil() {
     }
 
     /**
-     * Load Certificate from system file path
-     * @param filePath Path of certificate file
-     * @return Certificate
+     * Loads an X.509 certificate from the given file path.
+     * @param filePath Filepath of the certificate
+     * @return instance of the certificate
      * @throws FileNotFoundException if file is not found
-     * @throws CertificateException if any error occurred while reading certificate
+     * @throws CertificateException if any error occurred while reading the certificate
      */
     public static Certificate loadCertificate(String filePath) throws FileNotFoundException, CertificateException {
         return loadCertificate(new FileInputStream(filePath));
     }
 
     /**
-     * Load Certificate from a input stream
-     * @param inputStream InputStream containing certificate data
-     * @return Certificate
+     * Loads an X.509 certificate from an input stream.
+     * @param inputStream InputStream containing the certificate.
+     * @return instance of the certificate
      * @throws CertificateException if any error occurred while reading certificate from stream
      */
     public static Certificate loadCertificate(InputStream inputStream) throws CertificateException {
@@ -60,15 +63,15 @@ public static Certificate loadCertificate(InputStream inputStream) throws Certif
     }
 
     /**
-     * Load KeyStore from given path and type
+     * Loads a KeyStore from the specified file path using the given type and password.
      * @param keyStorePath file path
      * @param keyStoreType keystore type (JKS/PKCS12 etc)
      * @param keyStorePassword keystore password
-     * @return
-     * @throws KeyStoreException
-     * @throws CertificateException
-     * @throws NoSuchAlgorithmException
-     * @throws IOException
+     * @return the loaded KeyStore instance.
+     * @throws KeyStoreException if the keystore type is invalid.
+     * @throws CertificateException if a certificate in the keystore could not be loaded.
+     * @throws NoSuchAlgorithmException if the algorithm for checking the keystore integrity cannot be found.
+     * @throws IOException if there is an I/O or format problem with the keystore data.
      */
     public static KeyStore loadKeyStore(String keyStorePath, String keyStoreType, String keyStorePassword) throws KeyStoreException, CertificateException, NoSuchAlgorithmException, IOException {
 
@@ -90,9 +93,10 @@ public static KeyStore loadKeyStore(String keyStorePath, String keyStoreType, St
             throw new FileNotFoundException("Keystore file not found at path " + keyStorePath);
         }
 
-        FileInputStream inputStream = new FileInputStream(file);
-        keyStore.load(inputStream, password);
-        inputStream.close();
+        try (FileInputStream inputStream = new FileInputStream(file)) {
+            keyStore.load(inputStream, password);
+        }
+
         return keyStore;
     }
 }

src/main/java/com/adyen/util/DateUtil.java

@@ -26,10 +26,23 @@
 import java.util.Locale;
 import java.util.TimeZone;
 
+/**
+ * Utility class for parsing date strings into java.util.Date objects using specified formats.
+ */
 public final class DateUtil {
+
+    // Private constructor to prevent instantiation
     private DateUtil() {
     }
 
+    /**
+     * Parses a date string using the given date format.
+     * Returns {@code null} if the input is {@code null} or parsing fails.
+     *
+     * @param dateString the date string to parse
+     * @param format     the format pattern to use for parsing (e.g., {@code "yyyy-MM-dd"})
+     * @return the parsed Date, or {@code null} if parsing fails
+     */
     public static Date parseDateToFormat(String dateString, String format) {
         if (dateString == null) {
             return null;
@@ -46,10 +59,24 @@ public static Date parseDateToFormat(String dateString, String format) {
         return null;
     }
 
+    /**
+     * Parses a date string in {@code yyyy-MM-dd} format.
+     * Returns {@code null} if the input is {@code null} or parsing fails.
+     *
+     * @param dateString the date string to parse
+     * @return the parsed {@link Date}, or {@code null} if parsing fails
+     */
     public static Date parseYmdDate(String dateString) {
         return parseDateToFormat(dateString, "yyyy-MM-dd");
     }
 
+    /**
+     * Parses a date string in {@code M/yyyy} format.
+     * Returns {@code null} if the input is {@code null} or parsing fails.
+     *
+     * @param dateString the date string to parse
+     * @return the parsed {@link Date}, or {@code null} if parsing fails
+     */
     public static Date parseMYDate(String dateString) {
         return parseDateToFormat(dateString, "M/yyyy");
     }