Package org.eclipse.keypop.storagecard.transaction

Interface StorageCardTransactionManager

public interface StorageCardTransactionManager
Provides methods to manage APDU exchanges with a storage card.

This interface allows to:

  • Prepare read and write operations to the card
  • Process prepared commands in a single transaction
  • Manage the communication channel with the card
Since:
1.0.0

  • Method Details

    • prepareReadBlock

      StorageCardTransactionManager prepareReadBlock(int blockNumber)
      Prepares the reading of a specific block from the storage card.

      Block numbers start at 0 and the maximum value is provided by ProductType.getBlockCount().

      Once this command is processed, the result is available in StorageCard.

      Parameters:
      blockNumber - The number of the block to be read.
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If the block number is out of range.
      Since:
      1.0.0
      See Also:

    • prepareReadBlocks

      StorageCardTransactionManager prepareReadBlocks(int fromBlockNumber, int toBlockNumber)
      Prepares the reading of a range of blocks from the storage card.

      Block numbers start at 0 and the maximum value is provided by ProductType.getBlockCount().

      Once this command is processed, the result is available in StorageCard.

      Parameters:
      fromBlockNumber - The starting block number (inclusive).
      toBlockNumber - The ending block number (inclusive).
      Returns:
      The current instance.
      Throws:
      IllegalArgumentException - If one of the arguments is out of range.
      Since:
      1.0.0
      See Also:

    • prepareWriteBlocks

      StorageCardTransactionManager prepareWriteBlocks(int fromBlockNumber, byte[] data)
      Prepares the writing of blocks of data to the storage card starting from a specific block number offset.

      The provided data should be a byte array representing the content of the blocks to be written. The number of blocks that will be written is determined by the length of the data array divided by the block size of the storage card. The block size is provided by ProductType.getBlockCount().

      Once this command is processed, the data will be available in StorageCard using the dedicated block management methods.

      Parameters:
      fromBlockNumber - The offset from which the blocks will be written.
      data - The data to be written to the storage card.
      Returns:
      The current instance of the StorageCardTransactionManager.
      Throws:
      IllegalArgumentException - If data is null or its length is not a multiple of the block size.
      Since:
      1.0.0
      See Also:

    • processCommands

      StorageCardTransactionManager processCommands(ChannelControl channelControl) throws ReaderIOException, CardIOException, UnexpectedCommandStatusException
      Processes all previously prepared commands and closes the physical channel if requested.

      All APDUs corresponding to the prepared commands are sent to the card, their responses are retrieved and used to update the StorageCard associated with the transaction.

      For write commands, the StorageCard is updated only when the command is successful.

      The process is interrupted at the first failed command.

      Parameters:
      channelControl - Policy for managing the physical channel after executing commands to the card.
      Returns:
      The current instance.
      Throws:
      ReaderIOException - If a communication error with the card reader or the cryptographic module reader occurs.
      CardIOException - If a communication error with the card occurs.
      UnexpectedCommandStatusException - If one of the prepared command failed.
      Since:
      1.0.0