feat: init SAM context for next transaction (#54)

Author: andrei-cristea

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]
+### Added
+- `CardTransactionManager.initSamContextForNextTransaction` method.
 
 ## [1.7.0] - 2023-03-08
 ### Added

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.7.1
+version = 1.8.0
 
 javaSourceLevel = 1.6
 javaTargetLevel = 1.6

src/main/java/org/calypsonet/terminal/calypso/CalypsoApiProperties.java

@@ -23,7 +23,7 @@ public class CalypsoApiProperties {
    *
    * @since 1.0.0
    */
-  public static final String VERSION = "1.7";
+  public static final String VERSION = "1.8";
 
   /** Private constructor */
   private CalypsoApiProperties() {}

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

@@ -1417,4 +1417,29 @@ CardTransactionManager prepareChangeKey(
    * @since 1.6.0
    */
   CardTransactionManager prepareCancelSecureSession();
+
+  /**
+   * Prepares the SAM for the next transaction by anticipating all security context configuration
+   * operations.
+   *
+   * <p>This feature is only useful if the currently allocated SAM will be used for the next
+   * transaction. It is particularly relevant to optimize the transaction time in a ticketing
+   * context of user card validation.
+   *
+   * <p>For this optimization to be effective, it is necessary to call this method at the very end
+   * of the current transaction, i.e. <u>after</u> having notified the user of the access right
+   * (e.g. after opening the gate).
+   *
+   * @throws IllegalStateException In the following cases:
+   *     <ul>
+   *       <li>No {@link CardSecuritySetting} is available
+   *       <li>Unprocessed card commands are pending
+   *     </ul>
+   *
+   * @throws ReaderIOException If a communication error with the SAM reader occurs.
+   * @throws SamIOException If a communication error with the SAM occurs.
+   * @throws UnexpectedCommandStatusException If a command returns an unexpected status.
+   * @since 1.8.0
+   */
+  void initSamContextForNextTransaction();
 }