From 21f63c6cf6cd50f1aae624d625672c7660d8ccdd Mon Sep 17 00:00:00 2001
From: Andrei Cristea <andrei.cristea019@gmail.com>
Date: Fri, 17 Dec 2021 11:40:26 +0100
Subject: [PATCH] docs: Add a precision in "processOpening" and
 "processClosing" methods

Closes #15
---
 CHANGELOG.md                                  |  3 ++
 gradle.properties                             |  2 +-
 .../transaction/CardTransactionManager.java   | 35 +++++++++++--------
 3 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63bbc60..74c51ba 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Changed
+- Documentation of `processOpening` and `processClosing` methods (issue [#15]).
 
 ## [1.0.3] - 2021-12-15
 ### Changed
@@ -31,6 +33,7 @@ This is the initial release.
 [1.0.1]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/compare/1.0.0...1.0.1
 [1.0.0]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/releases/tag/1.0.0
 
+[#15]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/15
 [#13]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/13
 [#11]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/11
 [#9]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/9
diff --git a/gradle.properties b/gradle.properties
index 12365a1..5445044 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -1,7 +1,7 @@
 group = org.calypsonet.terminal
 title = Calypsonet Terminal Calypso API
 description = API defining the needed interfaces to manage Calypso cards
-version = 1.0.3
+version = 1.0.4
 
 javaSourceLevel = 1.6
 javaTargetLevel = 1.6
diff --git a/src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java b/src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java
index 1a7174d..519edca 100644
--- a/src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java
+++ b/src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java
@@ -124,7 +124,7 @@ public interface CardTransactionManager {
    *
    * <p>Once this command is processed, the result is available in {@link CalypsoCard}.
    *
-   * <p>Depending on whether or not we are inside a secure session, there are two types of behavior
+   * <p>Depending on whether we are inside a secure session, there are two types of behavior
    * following this command:
    *
    * <ul>
@@ -157,7 +157,7 @@ public interface CardTransactionManager {
    *
    * <p>Once this command is processed, the result is available in {@link CalypsoCard}.
    *
-   * <p>Depending on whether or not we are inside a secure session, there are two types of behavior
+   * <p>Depending on whether we are inside a secure session, there are two types of behavior
    * following this command:
    *
    * <ul>
@@ -192,7 +192,7 @@ CardTransactionManager prepareReadRecordFile(
    *
    * <p>Once this command is processed, the result is available in {@link CalypsoCard}.
    *
-   * <p>Depending on whether or not we are inside a secure session, there are two types of behavior
+   * <p>Depending on whether we are inside a secure session, there are two types of behavior
    * following this command:
    *
    * <ul>
@@ -218,7 +218,7 @@ CardTransactionManager prepareReadRecordFile(
    * Schedules the execution of a <b>Verify Pin</b> command without PIN presentation in order to get
    * the attempt counter.
    *
-   * <p>The PIN status will made available in CalypsoCard after the execution of process command.
+   * <p>The PIN status will be made available in CalypsoCard after the execution of process command.
    * <br>
    * Adds it to the list of commands to be sent with the next process command.
    *
@@ -351,8 +351,8 @@ CardTransactionManager prepareReadRecordFile(
    *
    * <p>Once this command is processed, the result is available in {@link CalypsoCard}.
    *
-   * <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link CalypsoCard#getSvLoadLogRecord()}
-   * ()}, {@link CalypsoCard#getSvDebitLogLastRecord()}, {@link
+   * <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
+   * CalypsoCard#getSvLoadLogRecord()}, {@link CalypsoCard#getSvDebitLogLastRecord()}, {@link
    * CalypsoCard#getSvDebitLogAllRecords()}.
    *
    * @param svOperation Informs about the nature of the intended operation: debit or reload.
@@ -476,8 +476,8 @@ CardTransactionManager prepareReadRecordFile(
    * objects (see {@link CalypsoCard#getSvLoadLogRecord()} and {@link
    * CalypsoCard#getSvDebitLogAllRecords()}).
    *
-   * <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link CalypsoCard#getSvLoadLogRecord()}
-   * ()}, {@link CalypsoCard#getSvDebitLogLastRecord()}, {@link
+   * <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
+   * CalypsoCard#getSvLoadLogRecord()}, {@link CalypsoCard#getSvDebitLogLastRecord()}, {@link
    * CalypsoCard#getSvDebitLogAllRecords()}.
    *
    * @return The current instance.
@@ -555,7 +555,7 @@ CardTransactionManager prepareReadRecordFile(
   CardTransactionManager processCardCommands();
 
   /**
-   * Performs a PIN verification, in order to authenticate the card holder and/or unlock access to
+   * Performs a PIN verification, in order to authenticate the cardholder and/or unlock access to
    * certain card files.
    *
    * <p>This command can be performed both in and out of a secure session. The PIN code can be
@@ -609,7 +609,7 @@ CardTransactionManager prepareReadRecordFile(
    * <p>It is the starting point of the sequence:
    *
    * <ul>
-   *   <li>{@link #processOpening(WriteAccessLevel)}
+   *   <li>{@code processOpening(WriteAccessLevel)}
    *   <li>[{@link #processCardCommands()}]
    *   <li>[...]
    *   <li>[{@link #processCardCommands()}]
@@ -626,7 +626,7 @@ CardTransactionManager prepareReadRecordFile(
    * object, otherwise a {@link IllegalStateException} is raised.
    *
    * <p>The secure session is opened with the {@link WriteAccessLevel} passed as an argument
-   * depending on whether it is a personalization, reload or debit transaction profile..
+   * depending on whether it is a personalization, reload or debit transaction profile.
    *
    * <p>The possible overflow of the internal session buffer of the card is managed in two ways
    * depending on the setting chosen in {@link CardSecuritySetting}.
@@ -663,6 +663,10 @@ CardTransactionManager prepareReadRecordFile(
    * card file then this one is replaced by a setting of the session opening command allowing the
    * retrieval of this data in response to this command.
    *
+   * <p>Please note that the CAAD mechanism may require a file to be read before being modified. For
+   * this mechanism to work properly, this reading must not be placed in the first position of the
+   * prepared commands in order to be correctly taken into account by the SAM.
+   *
    * <p><b>Other operations carried out</b>
    *
    * <ul>
@@ -698,7 +702,9 @@ CardTransactionManager prepareReadRecordFile(
    * <p><b>Nominal case</b>
    *
    * <p>The previously prepared commands are integrated into the calculation of the session digest
-   * by the SAM before execution by the card by anticipating their responses.
+   * by the SAM before execution by the card by anticipating their responses.<br>
+   * Therefore, the previous prepared commands <b>should contain only modify commands</b>
+   * (update/write/increase/decrease).
    *
    * <p>Thus, the session closing command containing the terminal signature is integrated into the
    * same APDU group sent to the card via a final card request.
@@ -740,9 +746,10 @@ CardTransactionManager prepareReadRecordFile(
    * </ul>
    *
    * @return The current instance.
-   * @throws IllegalStateException If no session is open.
+   * @throws IllegalStateException If no session is open or if previous prepared commands contain
+   *     non modify commands.
    * @throws CardTransactionException If a functional error occurs (including card and SAM IO
-   *     errors)
+   *     errors).
    * @since 1.0.0
    */
   CardTransactionManager processClosing();