docs: update CardTransactionManager API

Author: jeanpierrefortune

CHANGELOG.md

@@ -6,6 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Changed
+- Added precision in the documentation of the methods of the `CardTransactionManager` API.
 - UML diagrams moved to a dedicated repository (see `README.md` file).
 
 ## [1.4.0] - 2022-10-26

src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java

@@ -563,6 +563,10 @@ CardTransactionManager prepareReadRecordsPartially(
    * #processClosing()}, the counter must have been read previously otherwise an {@link
    * IllegalStateException} will be raised during the execution of {@link #processClosing()}.
    *
+   * <p>Note 3: if several counters of the same file have to be incremented at the same time of the
+   * transaction, it is recommended to use the method {@link #prepareIncreaseCounters(byte, Map)}
+   * for optimization reasons.
+   *
    * @param sfi SFI of the EF to select.
    * @param counterNumber The number of the counter (must be zero in case of a simulated counter).
    * @param incValue Value to add to the counter (defined as a positive int {@code <=} 16777215
@@ -574,8 +578,10 @@ CardTransactionManager prepareReadRecordsPartially(
   CardTransactionManager prepareIncreaseCounter(byte sfi, int counterNumber, int incValue);
 
   /**
-   * Schedules the execution of a <b>Increase Multiple</b> command to increase multiple target
-   * counters at the same time.
+   * Schedules the execution of a <b>Increase Multiple</b> command or multiple <b>Increase</b>
+   * commands to increase multiple target counters at the same time.
+   *
+   * <p>The decision to execute one or the other command is made according to the type of card.
    *
    * <p>Note 1: {@link CalypsoCard} is updated with the provided input data.
    *
@@ -587,8 +593,6 @@ CardTransactionManager prepareReadRecordsPartially(
    * @param counterNumberToIncValueMap The map containing the counter numbers to be incremented and
    *     their associated increment values.
    * @return The current instance.
-   * @throws UnsupportedOperationException If the increase multiple command is not available for
-   *     this card.
    * @throws IllegalArgumentException If one of the provided argument is out of range or if the map
    *     is null or empty.
    * @since 1.1.0
@@ -605,6 +609,10 @@ CardTransactionManager prepareIncreaseCounters(
    * #processClosing()}, the counter must have been read previously otherwise an {@link
    * IllegalStateException} will be raised during the execution of {@link #processClosing()}.
    *
+   * <p>Note 3: if several counters of the same file have to be decremented at the same time of the
+   * transaction, it is recommended to use the method {@link #prepareDecreaseCounters(byte, Map)}
+   * for optimization reasons.
+   *
    * @param sfi SFI of the EF to select.
    * @param counterNumber The number of the counter (must be zero in case of a simulated counter).
    * @param decValue Value to subtract to the counter (defined as a positive int {@code <=} 16777215
@@ -616,8 +624,10 @@ CardTransactionManager prepareIncreaseCounters(
   CardTransactionManager prepareDecreaseCounter(byte sfi, int counterNumber, int decValue);
 
   /**
-   * Schedules the execution of a <b>Decrease Multiple</b> command to decrease multiple target
-   * counters at the same time.
+   * Schedules the execution of a <b>Decrease Multiple</b> command or multiple <b>Decrease</b>
+   * commands to decrease multiple target counters at the same time.
+   *
+   * <p>The decision to execute one or the other command is made according to the type of card.
    *
    * <p>Note 1: {@link CalypsoCard} is updated with the provided input data.
    *
@@ -629,8 +639,6 @@ CardTransactionManager prepareIncreaseCounters(
    * @param counterNumberToDecValueMap The map containing the counter numbers to be decremented and
    *     their associated decrement values.
    * @return The current instance.
-   * @throws UnsupportedOperationException If the decrease multiple command is not available for
-   *     this card.
    * @throws IllegalArgumentException If one of the provided argument is out of range or if the map
    *     is null or empty.
    * @since 1.1.0
@@ -833,7 +841,7 @@ CardTransactionManager prepareDecreaseCounters(
    * CalypsoCard#getSvDebitLogAllRecords()}.
    *
    * @return The current instance.
-   * @throws UnsupportedOperationException If the application is not of type Stored Value.
+   * @throws UnsupportedOperationException If the SV feature is not available for this card.
    * @since 1.0.0
    */
   CardTransactionManager prepareSvReadAllLogs();
@@ -941,7 +949,7 @@ CardTransactionManager prepareDecreaseCounters(
    *
    * @param pin The PIN code value (4-byte long byte array).
    * @return The current instance.
-   * @throws UnsupportedOperationException If the PIN feature is not available for this card
+   * @throws UnsupportedOperationException If the PIN feature is not available for this card.
    * @throws IllegalArgumentException If the provided argument is out of range.
    * @throws IllegalStateException If commands have been prepared before invoking this process
    *     method.