The returned array contains the software issuer ID and the discretionary data. * * @return An empty array if the traceability information is not available. + * @see CalypsoCardSelection#prepareGetData(GetDataTag) + * @see CardTransactionManager#prepareGetData(GetDataTag) * @since 1.1.0 */ byte[] getTraceabilityInformation(); @@ -182,6 +190,10 @@ public interface CalypsoCard extends SmartCard { * Returns the metadata of the current DF. * * @return Null if is not set. + * @see CalypsoCardSelection#prepareSelectFile(short) + * @see CalypsoCardSelection#prepareSelectFile(SelectFileControl) + * @see CardTransactionManager#prepareSelectFile(short) + * @see CardTransactionManager#prepareSelectFile(SelectFileControl) * @since 1.0.0 */ DirectoryHeader getDirectoryHeader(); @@ -192,6 +204,9 @@ public interface CalypsoCard extends SmartCard { *
Note that if a secure session is actually running, then the object contains all session * modifications, which can be canceled if the secure session fails. * + *
The file structure of the card image is updated as a result of file read and write + * operations. + * * @param sfi The SFI to search. * @return Null if the requested EF is not found or if the SFI is equal to 0. * @since 1.0.0 @@ -204,6 +219,9 @@ public interface CalypsoCard extends SmartCard { *
Note that if a secure session is actually running, then the object contains all session * modifications, which can be canceled if the secure session fails. * + *
The file structure of the card image is updated as a result of file read and write + * operations. + * * @param lid The LID to search. * @return Null if the requested EF is not found. * @since 1.0.0 @@ -230,6 +248,9 @@ public interface CalypsoCard extends SmartCard { *
Note that if a secure session is actually running, then the set contains all session * modifications, which can be canceled if the secure session fails. * + *
The file structure of the card image is updated as a result of file read and write
+ * operations.
+ *
* @return A not null reference (it may be empty if no one EF is set).
* @since 1.1.0
*/
@@ -240,6 +261,8 @@ public interface CalypsoCard extends SmartCard {
*
* @return True if the card has been ratified.
* @throws IllegalStateException If no session has been opened.
+ * @see CalypsoCardSelection#preparePreOpenSecureSession(WriteAccessLevel)
+ * @see CardTransactionManager#prepareOpenSecureSession(WriteAccessLevel)
* @since 1.0.0
*/
boolean isDfRatified();
@@ -254,6 +277,8 @@ public interface CalypsoCard extends SmartCard {
*
* @return A positive value.
* @throws IllegalStateException If no session has been opened.
+ * @see CalypsoCardSelection#preparePreOpenSecureSession(WriteAccessLevel)
+ * @see CardTransactionManager#prepareOpenSecureSession(WriteAccessLevel)
* @since 1.2.0
*/
int getTransactionCounter();
@@ -307,6 +332,8 @@ public interface CalypsoCard extends SmartCard {
*
* @return True if the PIN status is blocked
* @throws IllegalStateException If the PIN has not been checked.
+ * @see CardTransactionManager#prepareCheckPinStatus()
+ * @see CardTransactionManager#prepareVerifyPin(byte[])
* @since 1.0.0
*/
boolean isPinBlocked();
@@ -316,6 +343,8 @@ public interface CalypsoCard extends SmartCard {
*
* @return The number of remaining attempts.
* @throws IllegalStateException If the PIN has not been checked.
+ * @see CardTransactionManager#prepareCheckPinStatus()
+ * @see CardTransactionManager#prepareVerifyPin(byte[])
* @since 1.0.0
*/
int getPinAttemptRemaining();
@@ -335,6 +364,11 @@ public interface CalypsoCard extends SmartCard {
*
* @return An int
* @throws IllegalStateException If no SV Get command has been executed.
+ * @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
+ * @see CardTransactionManager#prepareSvDebit(int)
+ * @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
+ * @see CardTransactionManager#prepareSvReload(int)
+ * @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
int getSvBalance();
@@ -344,6 +378,11 @@ public interface CalypsoCard extends SmartCard {
*
* @return An int
* @throws IllegalStateException If no SV Get command has been executed.
+ * @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
+ * @see CardTransactionManager#prepareSvDebit(int)
+ * @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
+ * @see CardTransactionManager#prepareSvReload(int)
+ * @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
int getSvLastTNum();
@@ -352,6 +391,11 @@ public interface CalypsoCard extends SmartCard {
* Gets a reference to the last {@link SvLoadLogRecord}
*
* @return A last SV load log record object or null if not available.
+ * @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
+ * @see CardTransactionManager#prepareSvDebit(int)
+ * @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
+ * @see CardTransactionManager#prepareSvReload(int)
+ * @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
SvLoadLogRecord getSvLoadLogRecord();
@@ -360,6 +404,11 @@ public interface CalypsoCard extends SmartCard {
* Gets a reference to the last {@link SvDebitLogRecord}
*
* @return A last SV debit log record object or null if not available.
+ * @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
+ * @see CardTransactionManager#prepareSvDebit(int)
+ * @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
+ * @see CardTransactionManager#prepareSvReload(int)
+ * @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
SvDebitLogRecord getSvDebitLogLastRecord();
@@ -368,6 +417,11 @@ public interface CalypsoCard extends SmartCard {
* Gets list of references to the {@link SvDebitLogRecord} read from the card.
*
* @return An empty list if no log records are available.
+ * @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
+ * @see CardTransactionManager#prepareSvDebit(int)
+ * @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
+ * @see CardTransactionManager#prepareSvReload(int)
+ * @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
List 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).
+ * requested file and record exist in the file structure of the card (best-effort mode).
*
* Caution: the resulting APDU command must be compliant with PRIME revision 3 cards.
* Therefore, the command may be rejected by some earlier revision cards.
@@ -289,8 +289,43 @@ public interface CalypsoCardSelection extends CardSelection {
* feature, this optimizes future exchanges with the card in the case of secure sessions intended
* to be executed in a single step.
*
- * Caution: the resulting APDU command is compliant with PRIME revision 3 cards supporting the
- * extended mode. Therefore, the command may be rejected by some earlier revision cards.
+ * The objective of the pre-opening is to allow the grouping of all the commands of a secure
+ * session. This functionality is only relevant in the case of a distributed system where the
+ * ticketing processing is done remotely in order to allow a complete secure session to be carried
+ * out in a single exchange between the server and the terminal.
+ *
+ * This mechanism is based on the anticipation of the APDU responses of the card.
+ *
+ * In order to achieve the objective of a single exchange, it is essential to read locally
+ * beforehand (out of session) all the data that will have to be read in session. If not,
+ * additional exchanges will be made.
+ *
+ * Then, the remote ticketing processing must prepare all the commands of the session (from
+ * opening to closing) before executing it.
+ *
+ * Example:
+ *
+ * Note #1: a communication with the SAM is done here.
+ * Once this command is processed, the SV data is updated in {@link CalypsoCard}.
*
- * Note #2: the key used is the reload key.
+ * See the methods {@link CalypsoCard#getSvBalance()}, {@link
+ * CalypsoCard#getSvLoadLogRecord()}.
+ *
+ * Note #1: the key used is the reload key.
*
* @param amount The value to be reloaded, positive or negative integer in the range.
* -8388608..8388607
@@ -732,11 +735,14 @@ CardTransactionManager prepareDecreaseCounters(
/**
* Schedules the execution of a SV Reload command to increase the current SV balance.
*
- * Note #1: the optional SV additional data are set to zero.
+ * Once this command is processed, the SV data is updated in {@link CalypsoCard}.
*
- * Note #2: a communication with the SAM is done here.
+ * See the methods {@link CalypsoCard#getSvBalance()}, {@link
+ * CalypsoCard#getSvLoadLogRecord()}.
+ *
+ * Note #1: the optional SV additional data are set to zero.
*
- * Note #3: the key used is the reload key.
+ * Note #2: the key used is the reload key.
*
* @param amount The value to be reloaded, positive integer in the range 0..8388607 for a DO.
* action, in the range 0..8388608 for an UNDO action.
@@ -763,9 +769,12 @@ CardTransactionManager prepareDecreaseCounters(
* previous debit according to the type operation chosen in when invoking the previous SV Get
* command.
*
- * Note #1: a communication with the SAM is done here.
+ * Once this command is processed, the SV data is updated in {@link CalypsoCard}.
*
- * Note #2: the key used is the reload key.
+ * See the methods {@link CalypsoCard#getSvBalance()}, {@link
+ * CalypsoCard#getSvDebitLogLastRecord()}, {@link CalypsoCard#getSvDebitLogAllRecords()}.
+ *
+ * Note #1: the key used is the debit key
*
* @param amount The amount to be subtracted or added, positive integer in the range 0..32767 when
* subtracted and 0..32768 when added.
@@ -793,18 +802,14 @@ CardTransactionManager prepareDecreaseCounters(
* It consists in decreasing the current balance of the SV by a certain amount or canceling a
* previous debit.
*
- * Note #1: the optional SV additional data are set to zero.
+ * Once this command is processed, the SV data is updated in {@link CalypsoCard}.
*
- * Note #2: a communication with the SAM is done here.
- *
- * Note #3: the key used is the reload key.The information fields such as date and time are set
- * to 0. The extraInfo field propagated in Logs are automatically generated with the type of
- * transaction and amount.
+ * See the methods {@link CalypsoCard#getSvBalance()}, {@link
+ * CalypsoCard#getSvDebitLogLastRecord()}, {@link CalypsoCard#getSvDebitLogAllRecords()}.
*
- * Note #4: operations that would result in a negative balance are forbidden (SV Exception
- * raised).
+ * Note #1: the optional SV additional data are set to zero.
*
- * Note #5: the key used is the debit key
+ * Note #2: the key used is the debit key
*
* @param amount The amount to be subtracted or added, positive integer in the range 0..32767 when
* subtracted and 0..32768 when added.
@@ -1275,7 +1280,7 @@ CardTransactionManager prepareChangeKey(
*
* Note that if the next prepared command is a "Read One Record" or "Read One Or More
* Counters", then it will by default be merged with the "Open Secure Session" command for
- * optimization purposes.
+ * optimization purposes except if the "pre-open" mode is active.
*
* This mechanism may in some cases be incompatible with the security constraints and can be
* disabled via the {@link CardSecuritySetting#disableReadOnSessionOpening()} method.
@@ -1290,6 +1295,8 @@ CardTransactionManager prepareChangeKey(
* {@code
+ * transaction
+ * .prepareOpenSecureSession(...)
+ * .prepare...
+ * [...]
+ * .prepare...
+ * .prepareCloseSecureSession()
+ * .processCommands(...);
+ * }
+ *
+ * Caution: this feature will be ineffective in the following cases:
+ *
+ *
+ *
*
* @param writeAccessLevel The write access level.
* @return The object instance.
diff --git a/src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java b/src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java
index e40b929..da569de 100644
--- a/src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java
+++ b/src/main/java/org/calypsonet/terminal/calypso/transaction/CardTransactionManager.java
@@ -706,9 +706,12 @@ CardTransactionManager prepareDecreaseCounters(
* Schedules the execution of a SV Reload command to increase the current SV balance and
* using the provided additional data.
*
- *