docs: improve javadoc for CalypsoCard, selection and transaction managers

Author: andrei-cristea

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

@@ -14,6 +14,12 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import org.calypsonet.terminal.calypso.GetDataTag;
+import org.calypsonet.terminal.calypso.SelectFileControl;
+import org.calypsonet.terminal.calypso.WriteAccessLevel;
+import org.calypsonet.terminal.calypso.transaction.CardTransactionManager;
+import org.calypsonet.terminal.calypso.transaction.SvAction;
+import org.calypsonet.terminal.calypso.transaction.SvOperation;
 import org.calypsonet.terminal.reader.selection.spi.SmartCard;
 
 /**
@@ -174,6 +180,8 @@ public interface CalypsoCard extends SmartCard {
    * <p>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 {
    * <p>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.
    *
+   * <p>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 {
    * <p>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.
    *
+   * <p>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 {
    * <p>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.
    *
+   * <p>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<SvDebitLogRecord> getSvDebitLogAllRecords();

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

@@ -211,7 +211,7 @@ 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).
+   * requested file and record exist in the file structure of the card (best-effort mode).
    *
    * <p>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.
    *
-   * <p>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.
+   * <p>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.
+   *
+   * <p>This mechanism is based on the anticipation of the APDU responses of the card.
+   *
+   * <p>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.
+   *
+   * <p>Then, the remote ticketing processing must prepare all the commands of the session (from
+   * opening to closing) before executing it.
+   *
+   * <p>Example:
+   *
+   * <pre>{@code
+   * transaction
+   *   .prepareOpenSecureSession(...)
+   *   .prepare...
+   *   [...]
+   *   .prepare...
+   *   .prepareCloseSecureSession()
+   *   .processCommands(...);
+   * }</pre>
+   *
+   * <b>Caution</b>: this feature will be ineffective in the following cases:
+   *
+   * <ul>
+   *   <li>the card or the SAM does not support the extended mode
+   *   <li>the session contains commands that necessarily require exchanges with the card during the
+   *       session (e.g. PIN, Stored Value, encryption, early mutual authentication, data not
+   *       previously read outside the session)
+   *   <li>the session is opened with an access level different from the pre-opening one
+   *   <li>an intermediate "processCommand(...)" call has been made
+   *   <li>the session uses asymmetric cryptography
+   * </ul>
    *
    * @param writeAccessLevel The write access level.
    * @return The object instance.

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

@@ -706,9 +706,12 @@ CardTransactionManager prepareDecreaseCounters(
    * Schedules the execution of a <b>SV Reload</b> command to increase the current SV balance and
    * using the provided additional data.
    *
-   * <p>Note #1: a communication with the SAM is done here.
+   * <p>Once this command is processed, the SV data is updated in {@link CalypsoCard}.
    *
-   * <p>Note #2: the key used is the reload key.
+   * <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
+   * CalypsoCard#getSvLoadLogRecord()}.
+   *
+   * <p>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 <b>SV Reload</b> command to increase the current SV balance.
    *
-   * <p>Note #1: the optional SV additional data are set to zero.
+   * <p>Once this command is processed, the SV data is updated in {@link CalypsoCard}.
    *
-   * <p>Note #2: a communication with the SAM is done here.
+   * <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
+   * CalypsoCard#getSvLoadLogRecord()}.
+   *
+   * <p>Note #1: the optional SV additional data are set to zero.
    *
-   * <p>Note #3: the key used is the reload key.
+   * <p>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.
    *
-   * <p>Note #1: a communication with the SAM is done here.
+   * <p>Once this command is processed, the SV data is updated in {@link CalypsoCard}.
    *
-   * <p>Note #2: the key used is the reload key.
+   * <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
+   * CalypsoCard#getSvDebitLogLastRecord()}, {@link CalypsoCard#getSvDebitLogAllRecords()}.
+   *
+   * <p>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(
    * <p>It consists in decreasing the current balance of the SV by a certain amount or canceling a
    * previous debit.
    *
-   * <p>Note #1: the optional SV additional data are set to zero.
+   * <p>Once this command is processed, the SV data is updated in {@link CalypsoCard}.
    *
-   * <p>Note #2: a communication with the SAM is done here.
-   *
-   * <p>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.
+   * <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
+   * CalypsoCard#getSvDebitLogLastRecord()}, {@link CalypsoCard#getSvDebitLogAllRecords()}.
    *
-   * <p>Note #4: operations that would result in a negative balance are forbidden (SV Exception
-   * raised).
+   * <p>Note #1: the optional SV additional data are set to zero.
    *
-   * <p>Note #5: the key used is the debit key
+   * <p>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(
    *
    * <p>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.
    *
    * <p>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(
    *       <li>A secure session is already opened
    *     </ul>
    *
+   * @see
+   *     org.calypsonet.terminal.calypso.card.CalypsoCardSelection#preparePreOpenSecureSession(WriteAccessLevel)
    * @since 1.6.0
    */
   CardTransactionManager prepareOpenSecureSession(WriteAccessLevel writeAccessLevel);