From e561d4e50a7a9f41a6d71806343ab9c7c3cce53f Mon Sep 17 00:00:00 2001 From: Jean-Pierre Fortune Date: Tue, 7 Apr 2026 22:38:46 +0200 Subject: [PATCH 1/3] docs: clarify write operations in Javadoc --- CHANGELOG.md | 2 ++ gradle.properties | 2 +- .../StorageCardTransactionManager.java | 34 +++++++++++-------- 3 files changed, 23 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 50db5fb..d9bef3e 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 +- **Javadoc**: clarified write contract for `prepareWriteBlocks` and `prepareSt25WriteSystemBlock`. ## [1.2.0] - 2026-03-18 ### Added diff --git a/gradle.properties b/gradle.properties index 5d66a10..f82e7ea 100644 --- a/gradle.properties +++ b/gradle.properties @@ -2,7 +2,7 @@ group = org.eclipse.keypop title = Keypop Storage Card Java API description = API defining the needed interfaces to manage storage cards -version = 1.2.0-SNAPSHOT +version = 1.2.1-SNAPSHOT # Java Configuration javaSourceLevel = 1.8 diff --git a/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java b/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java index 48deeb2..7ea10a1 100644 --- a/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java +++ b/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java @@ -122,14 +122,17 @@ public interface StorageCardTransactionManager * *

The data length must match the block size defined by the card's {@link ProductType}. * - *

Important: After execution of this write command, the {@link StorageCard} - * memory image is not automatically updated. ST25/SRT512 cards do not provide - * reliable status codes to confirm successful write operations. To ensure data consistency, an - * explicit read operation must be performed after the write to refresh the memory image and - * verify the actual content stored on the card. + *

Important: It is the user's responsibility to ensure that the write + * operations are coherent with the target card's technology (e.g., OTP bits). The data provided + * must represent the expected final state of the system block after the write operation. * * - * @param data The data to be written to the system block. The length must match the card's block - * size. + *

ST25/SRT512 cards do not provide reliable status codes to confirm successful write + * operations. Consequently, the library performs an automatic verification read. This check will + * fail if the physical state of the system block after the write does not exactly match the + * provided data. + * + * @param data The data to be written to the system block (expected final state). The length must + * match the card's block size. * @return The current instance. * @throws IllegalArgumentException If data is null or its length does not match the block size. * @throws UnsupportedOperationException If the current card type is not ST25/SRT512. @@ -180,15 +183,18 @@ public interface StorageCardTransactionManager * array divided by the block size of the storage card. The block size is provided by {@link * ProductType#getBlockSize()}. * - *

Important: Some storage card technologies do not provide reliable status - * codes to confirm successful write operations. For such cards (e.g., SRT512/ST25), the library - * automatically performs a verification read after each write to ensure that the data has been - * correctly stored. For cards that provide a reliable write acknowledgment, no additional read is - * performed. In all cases, the library guarantees the integrity of the written data, and the - * application does not need to explicitly perform verification reads. + *

Important: It is the user's responsibility to ensure that the write + * operations are coherent with the target card's technology (e.g., OTP bits, counters). The data + * provided must represent the expected final state of the blocks after the write + * operation. * + * + *

For cards that do not provide reliable status codes (e.g., SRT512/ST25), the library + * performs an automatic verification read. This check will fail if the physical state of the card + * after the write does not exactly match the provided data. For cards providing reliable + * acknowledgment, no additional read is performed. * * @param fromBlockAddress The offset from which the blocks will be written. - * @param data The data to be written to the storage card. + * @param data The data to be written to the storage card (expected final state). * @return The current instance of the {@link StorageCardTransactionManager}. * @throws IllegalArgumentException If data is null or its length is not a multiple of the block * size. From bfb013a0a7f769ae0f217998d8ffc035212eaf3b Mon Sep 17 00:00:00 2001 From: Jean-Pierre Fortune Date: Wed, 8 Apr 2026 09:52:52 +0200 Subject: [PATCH 2/3] docs: update Javadoc to clarify memory image updates for write commands --- .../transaction/StorageCardTransactionManager.java | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java b/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java index 7ea10a1..b8b46c5 100644 --- a/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java +++ b/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java @@ -39,10 +39,10 @@ *

For read commands: The {@link StorageCard} memory image is updated with the * data retrieved from the card. * - *

For write commands: The {@link StorageCard} memory image is not - * updated even when the command appears successful, as some storage card technologies do - * not provide reliable confirmation of write completion. Applications should perform explicit read - * operations after writes to verify the actual card content and update the memory image. + *

For write commands: The {@link StorageCard} memory image is updated with the + * written data once the write is confirmed successful. For card technologies that do not provide + * reliable status codes (e.g. ST25/SRT512), confirmation is obtained via an automatic verification + * read; the memory image is updated only if this verification passes. * *

The process is interrupted at the first failed command. * @@ -124,7 +124,7 @@ public interface StorageCardTransactionManager * *

Important: It is the user's responsibility to ensure that the write * operations are coherent with the target card's technology (e.g., OTP bits). The data provided - * must represent the expected final state of the system block after the write operation. * + * must represent the expected final state of the system block after the write operation. * *

ST25/SRT512 cards do not provide reliable status codes to confirm successful write * operations. Consequently, the library performs an automatic verification read. This check will @@ -186,7 +186,7 @@ public interface StorageCardTransactionManager *

Important: It is the user's responsibility to ensure that the write * operations are coherent with the target card's technology (e.g., OTP bits, counters). The data * provided must represent the expected final state of the blocks after the write - * operation. * + * operation. * *

For cards that do not provide reliable status codes (e.g., SRT512/ST25), the library * performs an automatic verification read. This check will fail if the physical state of the card From d6ddcfa760bd7ca268fb2c0ea1ef5bab1a0f8a17 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Fortune Date: Wed, 8 Apr 2026 10:00:30 +0200 Subject: [PATCH 3/3] docs: remove redundant Javadoc notes on memory image updates for write operations --- .../transaction/StorageCardTransactionManager.java | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java b/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java index b8b46c5..77dcbec 100644 --- a/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java +++ b/src/main/java/org/eclipse/keypop/storagecard/transaction/StorageCardTransactionManager.java @@ -78,12 +78,6 @@ public interface StorageCardTransactionManager * *

The data length must match the block size defined by the card's {@link ProductType}. * - *

Important: After execution of this write command, the {@link StorageCard} - * memory image is not automatically updated. Some storage card technologies do - * not provide reliable status codes to confirm successful write operations. To ensure data - * consistency, an explicit read operation must be performed after the write to refresh the memory - * image and verify the actual content stored on the card. - * * @param data The data to be written to the system block. The length must match the card's block * size. * @return The current instance.