Client setup: remove old code and promote best practises (#1525)

* Add javadoc and tests

* Minor edit in README

* Convert field to local var

* Javadoc and tidy up

* Improve test to follow best practises

* Update README to follow best practises

* Update README

* Update README

* Improve code and indentation

* Minor edit

Author: gcatanese

README.md

@@ -82,8 +82,10 @@ Alternatively, you can download the [release on GitHub](https://github.com/Adyen
 
 ### General use with API key
 
-Every API the library supports is represented by a service object. The name of the service matching the corresponding
-API is listed in the [Supported API versions](#supported-api-versions) section of this document.
+For every API, one or more corresponding service classes can be found in the folder with the same name.
+Check the [Supported API versions](#supported-api-versions).
+
+**Note**: For requests on `live` environment, you must define the [Live URL Prefix](https://docs.adyen.com/development-resources/live-endpoints#live-url-prefix) in the Client object:
 
 ~~~~ java
 // Import the required classes
@@ -92,8 +94,13 @@ import com.adyen.enums.Environment;
 import com.adyen.service.checkout.PaymentsApi;
 import com.adyen.model.checkout.*;
 
-// Setup Client and Service
-Client client = new Client("Your X-API-KEY", Environment.TEST);
+// Setup Client using Config object
+Config config = new Config()
+    .environment(Environment.LIVE)
+    .liveEndpointUrlPrefix("myCompany")
+    .apiKey(apiKey);
+Client client = new Client(config);
+
 PaymentsApi paymentsApi = new PaymentsApi(client);
 
 // Create PaymentRequest 
@@ -120,29 +127,18 @@ PaymentResponse paymentResponse = paymentsApi.payments(paymentRequest);
 
 ~~~~
 
-### General use with API key for live environment
-For requests on live environment, you need to pass the [Live URL Prefix](https://docs.adyen.com/development-resources/live-endpoints#live-url-prefix) to the Client object:
-~~~~ java
-// Import the required classes
-import com.adyen.Client;
-import com.adyen.enums.Environment;
-import com.adyen.service.checkout.ModificationsApi
-
-// Setup Client and Service
-Client client = new Client("Your X-API-KEY", Environment.LIVE, "Your live URL prefix");
-ModificationsApi modificationsApi = new ModificationsApi(client);
-
-...
-~~~~
 ### General use with basic auth
 ~~~~ java
 // Import the required classes
 import com.adyen.Client;
 import com.adyen.enums.Environment;
 import com.adyen.service.checkout.PaymentLinksApi
 
-// Setup Client and Service
-Client client = new Client("Your username", "Your password", Environment.LIVE, "Your live URL prefix", "Your application name");
+// Setup Client and Service passing prefix  
+Client client = new Client("Your username", "Your password", Environment.LIVE, "mycompany123");
+// Or setup Client and Service passing prefix and application name 
+//Client client = new Client("Your username", "Your password", Environment.LIVE, "mycompany123", "Your application name");
+
 PaymentLinksApi paymentLinksApi = new PaymentLinksApi(client);
 
 ...
@@ -156,6 +152,23 @@ import com.adyen.model.checkout.PaymentRequest;
 // Deserialize using built-in function
 PaymentRequest paymentRequest = PaymentRequest.fromJson("YOUR_JSON_STRING");
 ~~~~
+### Error handling
+
+Use a try-catch block to handle API errors. Catch the `ApiException` to inspect the response and handle specific cases:
+~~~~
+try {
+    service.getPaymentLink("1234");
+} catch (ApiException e) {
+    // Obtain response 
+    int statusCode = e.getStatusCode();
+    String responseBody = e.getResponseBody();
+    // Check ApiError object
+    ApiError apiError = e.getError();
+    String errorCode = apiError.getErrorCode();
+    List<String> invalidFields = apiError.getInvalidFields();
+    ....
+}
+~~~~
 ### Using notification webhooks parser
 ~~~~ java
 // Import the required classes
@@ -295,27 +308,9 @@ Client client = new Client(sslContext, apiKey);
 // Use the client
 ~~~~
 
-### Classic Platforms Error Handling
 
-When requests fail, the library throws exceptions. For Classic AFP endpoints like [Create Account Holder](https://docs.adyen.com/api-explorer/Account/6/post/createAccountHolder), you can decode further details from the exception:  
-
-```java
-Client client = new Client("Your YOUR_API_KEY", Environment.TEST);
-ClassicPlatformAccountApi api = new ClassicPlatformAccountApi(client);
-CreateAccountHolderRequest request = new CreateAccountHolderRequest();
-
-try {
-    api.createAccountHolder(request);
-} catch (ApiException e) {
-    CreateAccountHolderResponse error = CreateAccountHolderResponse.fromJson(e.getResponseBody());
-    // inspect the error
-    System.out.println(e.getStatusCode());
-    System.out.println(error.getInvalidFields());
-}
-```
-
-## Using the Cloud Terminal API Integration
-In order to submit In-Person requests with [Terminal API over Cloud](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/) you need to initialize the client in a similar way as the steps listed above for Ecommerce transactions, but make sure to include `TerminalCloudAPI`:
+## Using the Cloud Terminal API
+For In-Person Payments integrations with the [Cloud Terminal API](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/), you must initialise the Client **setting the closest** [Region](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/#cloud):
 ``` java
 // Step 1: Import the required classes
 import com.adyen.Client;
@@ -325,13 +320,11 @@ import com.adyen.model.nexo.*;
 import com.adyen.model.terminal.*;
 
 // Step 2: Initialize the client object
-Client client = new Client("Your YOUR_API_KEY", Environment.TEST);
-
-// for LIVE environment use
-// Config config = new Config();
-// config.setEnvironment(Environment.LIVE);
-// config.setTerminalApiRegion(Region.EU);
-// Client client = new Client(config);
+Config config = new Config()
+    .environment(Environment.LIVE)
+    .terminalApiRegion(Region.EU)
+    .apiKey(apiKey);
+Client client = new Client(config);
 
 // Step 3: Initialize the API object
 TerminalCloudAPI terminalCloudApi = new TerminalCloudAPI(client);
@@ -567,9 +560,7 @@ TerminalAPIRequest terminalAPIPaymentRequest = new TerminalAPIRequest();
 TerminalAPIResponse terminalAPIResponse = terminalLocalAPI.request(terminalAPIRequest);
 ```
 
-
 ### Example integrations
- 
 For a closer look at how our Java library works, you can clone one of our example integrations:
 * [Java Spring Boot example integration](https://github.com/adyen-examples/adyen-java-spring-online-payments).
 * [Kotlin Spring Boot example integration](https://github.com/adyen-examples/adyen-kotlin-spring-online-payments).
@@ -580,20 +571,15 @@ These include commented code, highlighting key features and concepts, and exampl
 We value your input! Help us enhance our API Libraries and improve the integration experience by providing your feedback. Please take a moment to fill out [our feedback form](https://forms.gle/A4EERrR6CWgKWe5r9) to share your thoughts, suggestions or ideas. 
 
 ## Contributing
- 
- 
-We encourage you to contribute to this repository, so everyone can benefit from new features, bug fixes, and any other improvements.
- 
+We encourage you to contribute to this repository, so everyone can benefit from new features, bug fixes, and any other improvements. 
 
 Have a look at our [contributing guidelines](CONTRIBUTING.md) to find out how to raise a pull request.
- 
- 
+
 ## Support
 If you have a feature request, or spotted a bug or a technical problem, [create an issue here](https://github.com/Adyen/adyen-java-api-library/issues/new/choose).
 
-For other questions, [contact our Support Team](https://www.adyen.help/hc/en-us/requests/new?ticket_form_id=39.1.1705420).
- 
- 
+For other questions, [contact our Support Team](https://www.adyen.help/hc/en-us/requests/new?ticket_form_id=39.0.0705420).
+
 ## Licence
 This repository is available under the [MIT license](https://github.com/Adyen/adyen-java-api-library/blob/main/LICENSE).
 

src/main/java/com/adyen/Client.java

@@ -18,19 +18,21 @@ public class Client {
   public static final String TERMINAL_API_ENDPOINT_APSE =
       "https://terminal-api-live-apse.adyen.com";
 
+  /** Create Client instance (empty config) */
   public Client() {
     this.config = new Config();
   }
 
+  /**
+   * Create Client instance with the given configuration
+   *
+   * @param config Configuration
+   */
   public Client(Config config) {
     this.config = config;
     this.setEnvironment(config.environment, config.liveEndpointUrlPrefix);
   }
 
-  public Client(String username, String password, Environment environment, String applicationName) {
-    this(username, password, environment, null, applicationName);
-  }
-
   /**
    * Use this constructor to create client for client certificate authentication along with API key.
    * Note: Client certificate authentication is only applicable for PAL and Checkout services in
@@ -44,6 +46,28 @@ public Client(SSLContext sslContext, String apiKey) {
     this.config.setSSLContext(sslContext);
   }
 
+  /**
+   * Create Client instance
+   *
+   * @param username HTTP basic username
+   * @param password HTTP basic password
+   * @param environment Environment (Test or Live)
+   * @param liveEndpointUrlPrefix Prefix required for Live integrations
+   */
+  public Client(
+      String username, String password, Environment environment, String liveEndpointUrlPrefix) {
+    this(username, password, environment, liveEndpointUrlPrefix, null);
+  }
+
+  /**
+   * Create Client instance
+   *
+   * @param username HTTP basic username
+   * @param password HTTP basic password
+   * @param environment Environment (Test or Live)
+   * @param liveEndpointUrlPrefix Prefix required for Live integrations
+   * @param applicationName Application name (additional name/tag passed in HTTP requests)
+   */
   public Client(
       String username,
       String password,
@@ -58,99 +82,33 @@ public Client(
   }
 
   /**
-   * @param username your merchant account Username
-   * @param password your merchant accont Password
-   * @param environment This defines the payment environment live or test
-   * @param connectionTimeoutMillis Provide the time to time out
-   * @deprecated As of library version 1.6.1, timeouts should be set by {@link #setTimeouts(int
-   *     connectionTimeoutMillis, int readTimeoutMillis)} or directly by {@link
-   *     com.adyen.Config#setConnectionTimeoutMillis(int connectionTimeoutMillis)}.
-   */
-  @Deprecated
-  public Client(
-      String username, String password, Environment environment, int connectionTimeoutMillis) {
-    this(username, password, environment, null);
-    this.config.setConnectionTimeoutMillis(connectionTimeoutMillis);
-  }
-
-  /**
-   * @param username your merchant account Username
-   * @param password your merchant accont Password
-   * @param environment This defines the payment environment live or test
-   * @param connectionTimeoutMillis Provide the time to time out
-   * @param liveEndpointUrlPrefix provide the merchant specific url
-   * @deprecated As of library version 1.6.1, timeouts should be set by {@link #setTimeouts(int
-   *     connectionTimeoutMillis, int readTimeoutMillis)} or directly by {@link
-   *     com.adyen.Config#setConnectionTimeoutMillis(int connectionTimeoutMillis)}.
+   * Create Client instance
+   *
+   * @param apiKey API Key
+   * @param environment Environment (Test or Live)
    */
-  @Deprecated
-  public Client(
-      String username,
-      String password,
-      Environment environment,
-      int connectionTimeoutMillis,
-      String liveEndpointUrlPrefix) {
-    this(username, password, environment, liveEndpointUrlPrefix, null);
-    this.config.setConnectionTimeoutMillis(connectionTimeoutMillis);
-  }
-
   public Client(String apiKey, Environment environment) {
     this(apiKey, environment, null);
   }
 
+  /**
+   * Create Client instance
+   *
+   * @param apiKey API Key
+   * @param environment Environment (Test or Live)
+   * @param liveEndpointUrlPrefix Prefix required for the live integrations
+   */
   public Client(String apiKey, Environment environment, String liveEndpointUrlPrefix) {
     this.config = new Config();
     this.config.setApiKey(apiKey);
     this.setEnvironment(environment, liveEndpointUrlPrefix);
   }
 
   /**
-   * @param apiKey Defines the api key that can be retrieved by back office
-   * @param environment This defines the payment environment live or test
-   * @param connectionTimeoutMillis Provide the time to time out
-   * @deprecated As of library version 1.6.1, timeouts should be set by {@link #setTimeouts(int
-   *     connectionTimeoutMillis, int readTimeoutMillis)} or directly by {@link
-   *     com.adyen.Config#setConnectionTimeoutMillis(int connectionTimeoutMillis)}.
-   */
-  @Deprecated
-  public Client(String apiKey, Environment environment, int connectionTimeoutMillis) {
-    this(apiKey, environment);
-    this.config.setConnectionTimeoutMillis(connectionTimeoutMillis);
-  }
-
-  /**
-   * @param apiKey Defines the api key that can be retrieved by back office
-   * @param environment This defines the payment environment live or test
-   * @param connectionTimeoutMillis Provide the time to time out
-   * @param liveEndpointUrlPrefix provide the merchant specific url
-   * @deprecated As of library version 1.6.1, timeouts should be set by {@link #setTimeouts(int
-   *     connectionTimeoutMillis, int readTimeoutMillis)} or directly by {@link
-   *     com.adyen.Config#setConnectionTimeoutMillis(int connectionTimeoutMillis)}.
-   */
-  @Deprecated
-  public Client(
-      String apiKey,
-      Environment environment,
-      int connectionTimeoutMillis,
-      String liveEndpointUrlPrefix) {
-    this(apiKey, environment, liveEndpointUrlPrefix);
-    this.config.setConnectionTimeoutMillis(connectionTimeoutMillis);
-  }
-
-  /**
-   * @param environment This defines the payment environment live or test
-   * @deprecated As of library version 1.5.4, replaced by {@link #setEnvironment(Environment
-   *     environment, String liveEndpointUrlPrefix)}.
-   */
-  @Deprecated
-  public void setEnvironment(Environment environment) {
-    this.setEnvironment(environment, null);
-  }
-
-  /**
-   * @param environment This defines the payment environment live or test
-   * @param liveEndpointUrlPrefix Provide the unique live url prefix from the "API URLs and
-   *     Response" menu in the Adyen Customer Area
+   * Set Environment, together with the live endpoint url prefix.
+   *
+   * @param environment Environment (Test or Live)
+   * @param liveEndpointUrlPrefix The unique live url prefix (required for live integrations)
    */
   public void setEnvironment(Environment environment, String liveEndpointUrlPrefix) {
     config.setEnvironment(environment);
@@ -161,8 +119,11 @@ public void setEnvironment(Environment environment, String liveEndpointUrlPrefix
   }
 
   /**
+   * Retrieve the Terminal Cloud endpoint based on Region and Environment
+   *
    * @param region The region for which the endpoint is requested. If null or the region is not
    *     found, defaults to default EU endpoint.
+   * @param environment Environment (Test or Live)
    */
   public String retrieveCloudEndpoint(Region region, Environment environment) {
     // Check the environment for TEST and get the endpoint

src/main/java/com/adyen/Config.java

@@ -6,21 +6,25 @@
 import javax.net.ssl.SSLContext;
 
 public class Config {
+  // API key authentication
+  protected String apiKey;
+  // Basic authentication
   protected String username;
   protected String password;
+  // Environment: Test or Live
   protected Environment environment;
 
-  /** Application name: used as HTTP client User-Agent */
+  // Application name: used as HTTP client User-Agent
   protected String applicationName;
 
-  protected String apiKey;
+  // HTTP Client options
   protected int connectionTimeoutMillis = 60 * 1000; // default 60 sec
   protected int readTimeoutMillis = 60 * 1000; // default 60 sec
   protected int connectionRequestTimeoutMillis = 60 * 1000; // default 60 sec
   protected int defaultKeepAliveMillis = 60 * 1000; // default 60 sec
   protected Boolean protocolUpgradeEnabled;
 
-  // Terminal API Specific
+  // Terminal API configuration
   protected String terminalApiCloudEndpoint;
   protected String terminalApiLocalEndpoint;
   protected String liveEndpointUrlPrefix;