feat: add "SelectFileException" to manage the status of the "Select File" card command

Author: andrei-cristea

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `prepareWriteEventCeiling`, `prepareWriteEventCeilings` methods to `SamTransactionManager` API (issue [#25])
 - `prepareReadEventCeiling`, `prepareReadEventCeilings` methods to `SamTransactionManager` and `getEventCeiling`, `getEventCeilings` methods to `CalypsoSam` API (issue [#26])
 - `prepareReadEventCounter`, `prepareReadEventCounters` methods to `SamTransactionManager` and `getEventCounter`, `getEventCounters` methods to `CalypsoSam` API (issue [#27])
+- `SelectFileException` to manage the status of the "Select File" card command.
 ### Upgraded
 - "Calypsonet Terminal Reader API" to version `1.1.0`
 

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

@@ -915,6 +915,8 @@ CardTransactionManager prepareDecreaseCounters(
    * @throws InvalidCardSignatureException If a secure session is open and multiple session mode is
    *     enabled and an intermediate session is correctly closed but the card signature is
    *     incorrect.
+   * @throws SelectFileException If a "Select File" prepared card command indicated that the file
+   *     was not found.
    * @since 1.0.0
    * @deprecated Use {@link #processCommands()} instead.
    */
@@ -1107,6 +1109,8 @@ CardTransactionManager processChangeKey(
    *     card signature.
    * @throws InvalidCardSignatureException If multiple session mode is enabled and an intermediate
    *     session is correctly closed but the card signature is incorrect.
+   * @throws SelectFileException If a "Select File" prepared card command indicated that the file
+   *     was not found.
    * @since 1.0.0
    */
   CardTransactionManager processOpening(WriteAccessLevel writeAccessLevel);

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

@@ -109,6 +109,8 @@ public interface CommonTransactionManager<
    * @throws InvalidCardSignatureException If a secure session is open and multiple session mode is
    *     enabled and an intermediate session is correctly closed but the card signature is
    *     incorrect.
+   * @throws SelectFileException If a "Select File" prepared card command indicated that the file
+   *     was not found.
    * @since 1.2.0
    */
   T processCommands();

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

@@ -0,0 +1,36 @@
+/* **************************************************************************************
+ * Copyright (c) 2022 Calypso Networks Association https://calypsonet.org/
+ *
+ * See the NOTICE file(s) distributed with this work for additional information
+ * regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ ************************************************************************************** */
+package org.calypsonet.terminal.calypso.transaction;
+
+/**
+ * Indicates that the file selection failed because it was not found. This can happen in the
+ * following cases:
+ *
+ * <ul>
+ *   <li>The "Select File" card command status is 6A82h;
+ * </ul>
+ *
+ * @since 1.4.0
+ */
+public class SelectFileException extends RuntimeException {
+
+  /**
+   * Encapsulates a lower level exception.
+   *
+   * @param message Message to identify the exception context.
+   * @param cause The cause.
+   * @since 1.4.0
+   */
+  public SelectFileException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

src/main/uml/api_class_diagram.puml

@@ -1,6 +1,6 @@
 @startuml
 title
-    Calypsonet - calypsonet-terminal-calypso-java-api - 1.4.+ (2022-10-10)
+    Calypsonet - calypsonet-terminal-calypso-java-api - 1.4.+ (2022-10-19)
 end title
 
 ' == THEME ==
@@ -441,6 +441,7 @@ package "org.calypsonet.terminal.calypso" as api {
             +**InvalidSignatureException**: R-APDU of PSO Verify Signature = 6988.
             +**InvalidCardSignatureException**: R-APDU of DigestAuthenticate = 6988 **or** R-APDU of SvCheck = 6988.
             +**CardSignatureNotVerifiableException**: R-APDU of CloseSecureSession = 9000 but SAM is no more available.
+            +**SelectFileException**: R-APDU of SelectFile = 6A82.
             +**UnexpectedCommandStatusException**
             +**ReaderIOException**: Card reader and/or SAM reader communication is broken.
             +**CardIOException**