feat: add SAM event counters and ceilings management (#49)

Author: jeanpierrefortune

CHANGELOG.md

@@ -5,6 +5,10 @@ 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
+- `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])
 
 ## [1.3.0] - 2022-10-04
 ### Added
@@ -110,6 +114,9 @@ This is the initial release.
 [#38]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/38
 [#29]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/29
 [#28]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/28
+[#27]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/27
+[#26]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/26
+[#25]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/25
 [#24]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/24
 [#23]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/23
 [#22]: https://github.com/calypsonet/calypsonet-terminal-calypso-java-api/issues/22

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.3.1
+version = 1.4.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.3";
+  public static final String VERSION = "1.4";
 
   /** Private constructor */
   private CalypsoApiProperties() {}

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

@@ -56,7 +56,7 @@ public interface FileData {
   /**
    * Gets a reference to all known records content.
    *
-   * @return a not null map eventually empty if there's no content.
+   * @return a not null map possibly empty if there's no content.
    * @since 1.0.0
    */
   SortedMap<Integer, byte[]> getAllRecordsContent();

src/main/java/org/calypsonet/terminal/calypso/sam/CalypsoSam.java

@@ -11,6 +11,7 @@
  ************************************************************************************** */
 package org.calypsonet.terminal.calypso.sam;
 
+import java.util.SortedMap;
 import org.calypsonet.terminal.reader.selection.spi.SmartCard;
 
 /**
@@ -141,4 +142,40 @@ enum ProductType {
      */
     UNKNOWN
   }
+
+  /**
+   * Returns the value of an event counter.
+   *
+   * @param eventCounterNumber The number of the event counter (in range [0..26]).
+   * @return null if the event counter value is not set.
+   * @since 1.4.0
+   */
+  Integer getEventCounter(int eventCounterNumber);
+
+  /**
+   * Returns the value of known event counters in a sorted map where {@code key} is the counter
+   * number and {@code value} is the counter value.
+   *
+   * @return a not null map.
+   * @since 1.4.0
+   */
+  SortedMap<Integer, Integer> getEventCounters();
+
+  /**
+   * Returns the value of an event ceiling.
+   *
+   * @param eventCeilingNumber The number of the event ceiling (in range [0..26]).
+   * @return null if the event ceiling value is not set.
+   * @since 1.4.0
+   */
+  Integer getEventCeiling(int eventCeilingNumber);
+
+  /**
+   * Returns the value of known event ceilings in a sorted map where {@code key} is the ceiling
+   * number and {@code value} is the ceiling value.
+   *
+   * @return a not null map.
+   * @since 1.4.0
+   */
+  SortedMap<Integer, Integer> getEventCeilings();
 }

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

@@ -11,6 +11,7 @@
  ************************************************************************************** */
 package org.calypsonet.terminal.calypso.transaction;
 
+import java.util.List;
 import org.calypsonet.terminal.calypso.sam.CalypsoSam;
 import org.calypsonet.terminal.reader.CardReader;
 
@@ -55,4 +56,89 @@ public interface SamTransactionManager
    * @since 1.2.0
    */
   CalypsoSam getCalypsoSam();
+
+  /**
+   * Schedules the execution of a <b>Read Event Counter</b> command to read a single event counter.
+   *
+   * <p>Once this command is processed, the result is available in {@link CalypsoSam}.
+   *
+   * @param eventCounterNumber The number of the event counter to read (in range [0..26]).
+   * @return The current instance.
+   * @throws IllegalArgumentException If the provided argument is out of range.
+   * @since 1.4.0
+   */
+  SamTransactionManager prepareReadEventCounter(int eventCounterNumber);
+
+  /**
+   * Schedules the execution of a <b>Read Event Counter</b> command to read one or more consecutive
+   * event counters.
+   *
+   * <p>Once this command is processed, the result is available in {@link CalypsoSam}.
+   *
+   * @param fromEventCounterNumber The number of the first event counter to read (in range [0..26]).
+   * @param toEventCounterNumber The number of the last event counter to read (in range [0..26]).
+   * @return The current instance.
+   * @throws IllegalArgumentException If one of the provided argument is out of range.
+   * @since 1.4.0
+   */
+  SamTransactionManager prepareReadEventCounters(
+      int fromEventCounterNumber, int toEventCounterNumber);
+
+  /**
+   * Schedules the execution of a <b>Read Ceilings</b> command to read a single event ceiling.
+   *
+   * <p>Once this command is processed, the result is available in {@link CalypsoSam}.
+   *
+   * @param eventCeilingNumber The number of the event ceiling to read (in range [0..26]).
+   * @return The current instance.
+   * @throws IllegalArgumentException If the provided argument is out of range.
+   * @since 1.4.0
+   */
+  SamTransactionManager prepareReadEventCeiling(int eventCeilingNumber);
+
+  /**
+   * Schedules the execution of a <b>Read Ceilings</b> command to read one or more consecutive event
+   * ceilings.
+   *
+   * <p>Once this command is processed, the result is available in {@link CalypsoSam}.
+   *
+   * @param fromEventCeilingNumber The number of the first event ceiling to read (in range [0..26]).
+   * @param toEventCeilingNumber The number of the last event ceiling to read (in range [0..26]).
+   * @return The current instance.
+   * @throws IllegalArgumentException If one of the provided argument is out of range.
+   * @since 1.4.0
+   */
+  SamTransactionManager prepareReadEventCeilings(
+      int fromEventCeilingNumber, int toEventCeilingNumber);
+
+  /**
+   * Schedules the execution of a <b>Write Ceilings</b> command to write a single event ceiling.
+   *
+   * <p>Once this command is processed, the ceiling value available in {@link CalypsoSam} is
+   * updated.
+   *
+   * @param eventCeilingNumber The number of the event ceiling to write.
+   * @param newValue The desired value for the event ceiling (defined as a positive int {@code <=}
+   *     16777215 [FFFFFFh]).
+   * @return The current instance.
+   * @throws IllegalArgumentException If the provided argument is out of range.
+   * @since 1.4.0
+   */
+  SamTransactionManager prepareWriteEventCeiling(int eventCeilingNumber, int newValue);
+
+  /**
+   * Schedules the execution of a <b>Write Ceilings</b> command to write multiple event ceilings.
+   *
+   * <p>Once this command is processed, the ceiling values available in {@link CalypsoSam} are
+   * updated.
+   *
+   * @param fromEventCeilingNumber The number of the first event ceiling to write.
+   * @param newValues A list of event ceilings values to be written from the indicated position
+   *     (each event ceiling value is defined as a positive int {@code <=} 16777215 [FFFFFFh]).
+   * @return The current instance.
+   * @throws IllegalArgumentException If one of the provided argument is out of range.
+   * @since 1.4.0
+   */
+  SamTransactionManager prepareWriteEventCeilings(
+      int fromEventCeilingNumber, List<Integer> newValues);
 }

src/main/uml/api_class_diagram.puml

@@ -1,6 +1,6 @@
 @startuml
 title
-    Calypsonet - calypsonet-terminal-calypso-java-api - 1.3.+ (2022-10-04)
+    Calypsonet - calypsonet-terminal-calypso-java-api - 1.4.+ (2022-10-10)
 end title
 
 ' == THEME ==
@@ -261,6 +261,11 @@ package "org.calypsonet.terminal.calypso" as api {
             +byte getSoftwareIssuer ()
             +byte getSoftwareVersion ()
             +byte getSoftwareRevision ()
+
+            +Integer getEventCounter (int eventCounterNumber)
+            +SortedMap<Integer, Integer> getEventCounters ()
+            +Integer getEventCeiling (int eventCeilingNumber)
+            +SortedMap<Integer, Integer> getEventCeilings ()
         }
         +enum "ProductType" as SamProductType {
             SAM_C1
@@ -416,6 +421,13 @@ package "org.calypsonet.terminal.calypso" as api {
         +interface SamTransactionManager extends CommonTransactionManager {
             +<back:yellow>CardReader</back> getSamReader ()
             +CalypsoSam getCalypsoSam ()
+
+            +SamTransactionManager prepareReadEventCounter (int eventCounterNumber)
+            +SamTransactionManager prepareReadEventCounters (int fromEventCounterNumber, int toEventCounterNumber)
+            +SamTransactionManager prepareReadEventCeiling (int eventCeilingNumber)
+            +SamTransactionManager prepareReadEventCeilings (int fromEventCeilingNumber, int toEventCeilingNumber)
+            +SamTransactionManager prepareWriteEventCeiling (int eventCeilingNumber, int newValue)
+            +SamTransactionManager prepareWriteEventCeilings (int fromEventCeilingNumber, List<Integer> newValues)
         }
         +interface SamSecuritySetting extends CommonSecuritySetting {
         }