docs: update prepareReadRecord methods documentation, remove NoSuchElementException (#14)

Closes #13

Author: jeanpierrefortune

CHANGELOG.md

@@ -5,6 +5,9 @@ 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 `prepareReadRecord` methods (issue [#13]).
+- Signature of methods throwing `NoSuchElementException` (issue [#13]).
 
 ## [1.0.2] - 2021-11-22
 ### Deprecated
@@ -25,6 +28,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
 
+[#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
 [#7]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/7

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.2
+version = 1.0.3
 
 javaSourceLevel = 1.6
 javaTargetLevel = 1.6

src/main/java/org/calypsonet/terminal/calypso/card/CalypsoCard.java

@@ -13,7 +13,6 @@
 
 import java.util.List;
 import java.util.Map;
-import java.util.NoSuchElementException;
 import org.calypsonet.terminal.reader.selection.spi.SmartCard;
 
 /**
@@ -166,8 +165,7 @@ public interface CalypsoCard extends SmartCard {
    * modifications, which can be canceled if the secure session fails.
    *
    * @param sfi The SFI to search.
-   * @return a not null reference.
-   * @throws NoSuchElementException if requested EF is not found.
+   * @return Null if the requested EF is not found.
    * @since 1.0.0
    */
   ElementaryFile getFileBySfi(byte sfi);
@@ -179,8 +177,7 @@ public interface CalypsoCard extends SmartCard {
    * modifications, which can be canceled if the secure session fails.
    *
    * @param lid The LID to search.
-   * @return a not null reference.
-   * @throws NoSuchElementException if requested EF is not found.
+   * @return Null if the requested EF is not found.
    * @since 1.0.0
    */
   ElementaryFile getFileByLid(short lid);

src/main/java/org/calypsonet/terminal/calypso/card/CalypsoCardSelection.java

@@ -165,6 +165,9 @@ public interface CalypsoCardSelection extends CardSelection {
   /**
    * Adds a command APDU to read a single record from the indicated EF.
    *
+   * <p>Once this command is processed, the result is available in {@link CalypsoCard} if the
+   * requested file and record exist in the file structure of the card (best effort behavior).
+   *
    * @param sfi The SFI of the EF to read
    * @param recordNumber The record number to read.
    * @return The object instance.

src/main/java/org/calypsonet/terminal/calypso/card/FileData.java

@@ -11,7 +11,6 @@
  ************************************************************************************** */
 package org.calypsonet.terminal.calypso.card;
 
-import java.util.NoSuchElementException;
 import java.util.SortedMap;
 
 /**
@@ -25,8 +24,7 @@ public interface FileData {
    * Gets a reference to the known content of record #1.<br>
    * For a Binary file, it means all the bytes of the file.
    *
-   * @return a not empty reference to the record content.
-   * @throws NoSuchElementException if record #1 is not set.
+   * @return an empty array if the record #1 is not set.
    * @since 1.0.0
    */
   byte[] getContent();
@@ -35,8 +33,7 @@ public interface FileData {
    * Gets a reference to the known content of a specific record.
    *
    * @param numRecord The record number.
-   * @return a not empty reference to the record content.
-   * @throws NoSuchElementException if record #numRecord is not set.
+   * @return an empty array if the requested record is not set.
    * @since 1.0.0
    */
   byte[] getContent(int numRecord);
@@ -47,9 +44,9 @@ public interface FileData {
    * @param numRecord The record number.
    * @param dataOffset The offset index (should be {@code >=} 0).
    * @param dataLength The data length (should be {@code >=} 1).
-   * @return a copy not empty of the record subset content.
+   * @return a not empty copy of the record subset content when the record is set, an empty array
+   *     when the record is not set.
    * @throws IllegalArgumentException if dataOffset {@code <} 0 or dataLength {@code <} 1.
-   * @throws NoSuchElementException if record #numRecord is not set.
    * @throws IndexOutOfBoundsException if dataOffset {@code >=} content length or (dataOffset +
    *     dataLength) {@code >} content length.
    * @since 1.0.0
@@ -71,23 +68,21 @@ public interface FileData {
    * e.g. if numCounter == 2, then value is extracted from bytes indexes [3,4,5].
    *
    * @param numCounter The counter number (should be {@code >=} 1).
-   * @return The counter value or 0 if record #1 or numCounter is not set.
+   * @return The counter value or null if record #1 or numCounter is not set.
    * @throws IllegalArgumentException if numCounter is {@code <} 1.
-   * @throws NoSuchElementException if record #1 or numCounter is not set.
    * @throws IndexOutOfBoundsException if numCounter has a truncated value (when size of record #1
    *     modulo 3 != 0).
    * @since 1.0.0
    */
-  int getContentAsCounterValue(int numCounter);
+  Integer getContentAsCounterValue(int numCounter);
 
   /**
    * Gets all known counters value.<br>
    * The counters values are extracted from record #1.<br>
    * If last counter has a truncated value (when size of record #1 modulo 3 != 0), then last counter
    * value is not returned.
    *
-   * @return a not empty object.
-   * @throws NoSuchElementException if record #1 is not set.
+   * @return an empty map if record #1 is not set.
    * @since 1.0.0
    */
   SortedMap<Integer, Integer> getAllCountersValue();

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

@@ -16,7 +16,6 @@
 import org.calypsonet.terminal.calypso.WriteAccessLevel;
 import org.calypsonet.terminal.calypso.card.CalypsoCard;
 import org.calypsonet.terminal.calypso.card.ElementaryFile;
-import org.calypsonet.terminal.calypso.card.FileData;
 import org.calypsonet.terminal.reader.CardReader;
 
 /**
@@ -125,14 +124,29 @@ public interface CardTransactionManager {
    *
    * <p>Once this command is processed, the result is available in {@link CalypsoCard}.
    *
-   * <p>See the method {@link CalypsoCard#getFileBySfi(byte)}, the objects {@link ElementaryFile},
-   * {@link FileData} and their specialized methods according to the type of expected data: e.g.
-   * {@link FileData#getContent(int)}.
+   * <p>Depending on whether or not we are inside a secure session, there are two types of behavior
+   * following this command:
+   *
+   * <ul>
+   *   <li>Outside a secure session (best effort mode): the following "process" command will not
+   *       fail whatever the existence of the targeted file or record (the {@link CalypsoCard}
+   *       object may not be filled).
+   *   <li>Inside a secure session in contactless mode (strict mode): the following "process"
+   *       command will fail if the targeted file or record does not exist (the {@link CalypsoCard}
+   *       object is always filled or an exception is raised when the reading failed).
+   * </ul>
+   *
+   * <p><b>This method should not be used inside a secure session in contact mode</b> because
+   * additional exchanges with the card will be operated and will corrupt the security of the
+   * session. Instead, use the method {@link #prepareReadRecordFile(byte, int, int, int)} for this
+   * case and provide valid parameters.
    *
    * @param sfi The SFI of the EF to read.
    * @param recordNumber The record number to read.
    * @return The current instance.
    * @throws IllegalArgumentException If one of the provided arguments is out of range.
+   * @throws IllegalStateException If this method is invoked inside a secure session in contact
+   *     mode.
    * @since 1.0.0
    */
   CardTransactionManager prepareReadRecordFile(byte sfi, int recordNumber);
@@ -143,12 +157,22 @@ public interface CardTransactionManager {
    *
    * <p>Once this command is processed, the result is available in {@link CalypsoCard}.
    *
-   * <p>See the method {@link CalypsoCard#getFileBySfi(byte)}, the objects {@link ElementaryFile},
-   * {@link FileData} and their specialized methods according to the type of expected data: e.g.
-   * {@link FileData#getContent()}.
+   * <p>Depending on whether or not we are inside a secure session, there are two types of behavior
+   * following this command:
+   *
+   * <ul>
+   *   <li>Outside a secure session (best effort mode): the following "process" command will not
+   *       fail whatever the existence of the targeted file or record (the {@link CalypsoCard}
+   *       object may not be filled).
+   *   <li>Inside a secure session (strict mode): the following "process" command will fail if the
+   *       targeted file or record does not exist (the {@link CalypsoCard} object is always filled
+   *       or an exception is raised when the reading failed).<br>
+   *       Invalid parameters could lead to additional exchanges with the card and thus corrupt the
+   *       security of the session.
+   * </ul>
    *
    * @param sfi The SFI of the EF.
-   * @param firstRecordNumber The record number to read (or first record to read in case of several.
+   * @param firstRecordNumber The record number to read (or first record to read in case of several
    *     records)
    * @param numberOfRecords The number of records expected.
    * @param recordSize The record length.
@@ -164,13 +188,23 @@ CardTransactionManager prepareReadRecordFile(
    * which should be a counter file.
    *
    * <p>The record will be read up to the counter location indicated in parameter.<br>
-   * Thus all previous counters will also be read.
+   * Thus, all previous counters will also be read.
    *
    * <p>Once this command is processed, the result is available in {@link CalypsoCard}.
    *
-   * <p>See the method {@link CalypsoCard#getFileBySfi(byte)}, the objects {@link ElementaryFile},
-   * {@link FileData} and their specialized methods according to the type of expected data: e.g.
-   * {@link FileData#getAllCountersValue()} (int)}.
+   * <p>Depending on whether or not we are inside a secure session, there are two types of behavior
+   * following this command:
+   *
+   * <ul>
+   *   <li>Outside a secure session (best effort mode): the following "process" command will not
+   *       fail whatever the existence of the targeted file or counter (the {@link CalypsoCard}
+   *       object may not be filled).
+   *   <li>Inside a secure session (strict mode): the following "process" command will fail if the
+   *       targeted file or counter does not exist (the {@link CalypsoCard} object is always filled
+   *       or an exception is raised when the reading failed).<br>
+   *       Invalid parameters could lead to additional exchanges with the card and thus corrupt the
+   *       security of the session.
+   * </ul>
    *
    * @param sfi The SFI of the EF.
    * @param countersNumber The number of the last counter to be read.

src/main/uml/api_class_diagram.puml

@@ -1,6 +1,6 @@
 @startuml
 title
-    Calypsonet - calypsonet-terminal-calypso-java-api - 1.0.+ (26/07/2021)
+    Calypsonet - calypsonet-terminal-calypso-java-api - 1.0.+ (13/12/2021)
 end title
 
 ' == THEME ==
@@ -80,7 +80,7 @@ package "org.calypsonet.terminal.calypso" as api {
             +CalypsoCardSelection filterByDfName (String aid)
             +CalypsoCardSelection setFileOccurrence (FileOccurrence fileOccurrence)
             +CalypsoCardSelection setFileControlInformation (FileControlInformation fileControlInformation)
-            +CalypsoCardSelection addSuccessfulStatusWord (int statusWord)
+            +<s>CalypsoCardSelection addSuccessfulStatusWord (int statusWord)</s>
 
             +CalypsoCardSelection acceptInvalidatedCard ()
 
@@ -182,7 +182,7 @@ package "org.calypsonet.terminal.calypso" as api {
             +byte[] getContent (int numRecord, int dataOffset, int dataLength)
             +SortedMap<Integer, byte[]> getAllRecordsContent ()
 
-            +int getContentAsCounterValue (int numCounter)
+            +Integer getContentAsCounterValue (int numCounter)
             +SortedMap<Integer, Integer> getAllCountersValue ()
         }
         +enum "ProductType" as CardProductType {