Class SHADebit


  • public class SHADebit
    extends SHATransaction

    This class implements an account debit application for SHA Transactions. Account data is stored on user iButtons after being digitally signed by a coprocessor iButton. Account data consists of the following:

    • 1 byte: Length of the account file
    • 1 byte: Data type code (dynamic or static)
    • 20 bytes: Account Data Signature
    • 2 bytes: Money Conversion Factor
    • 3 bytes: Account Balance
    • 2 bytes: Transaction ID
    • 1 byte: File continuation pointer
    • 2 bytes: CRC16 of entire 30 bytes seeded with the page number
    • 32 bytes Total

    A typical use case for this class might be as follows:

     OneWireContainer18 coprOWC18 = new OneWireContainer18(adapter, address);
    
     // COPR.0 is the filename for coprocessor service data
     SHAiButtonCopr copr = new SHAiButtonCopr(coprOWC18, "COPR.0");
    
     // Initial amount for new users is $100, and debit amount is 50 cents
     SHATransaction trans = new SHADebit(copr, 10000, 50);
    
     OneWireContainer18 owc18 = new OneWireContainer18(adapter, userAddress);
    
     // The following constructor erases all transaction data from the user and
     // installs the system authentication secret on the user iButton.
     SHAiButtonUser user = new SHAiButtonUser18(copr, owc18, true, authSecret);
    
     // creates account data on iButton
     if (trans.setupTransactionData(user))
            System.out.println("Account data installed successfully");
     else
            System.out.println("Account data installation failed");
    
     // ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
    
     // "challenges" user iButton
     if (trans.verifyUser(user)) {
            System.out.println("User Verified Successfully");
    
            // checks data signature and account balance>0
            if (trans.verifyTransactionData(user)) {
                    System.out.println("Account Data Verified Successfully");
    
                    // debits and writes new data to user iButton
                    if (trans.executeTransaction(user)) {
                            System.out.println("Account debited.");
                            System.out.println("New Balance: " + trans.getParameter(SHADebit.USER_BALANCE));
                    }
            }
     }
    
     // ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
    
     if (trans.getLastError() != 0) {
            System.err.println("Error code: " + trans.getLastError());
     }
     

    This class makes use of several performance enhancements for TINI. For instance, most methods are synchronized to access instance variable byte arrays rather than creating new byte arrays every time a transaction is performed. This could hurt performance in multi-threaded applications, but the usefulness of having several threads contending to talk to a single iButton is questionable since the methods in com.dalsemi.onewire.adapter.DSPortAdapter beginExclusive(boolean) and endExclusive() should be used.

    See Also:
    SHATransaction, SHAiButtonCopr, SHAiButtonUser
    • Constructor Detail

      • SHADebit

        protected SHADebit()
        User apps should never call this
      • SHADebit

        public SHADebit​(SHAiButtonCopr copr)
        SHADebit constructor. copr is the SHAiButtonCopr that is used to perform this transaction. After saving a reference to the SHA coprocessor, this constructor resets all parameters for this type of transaction to their default values.
        Parameters:
        copr - The coprocessor used for authentication and data signing in this transaction.
      • SHADebit

        public SHADebit​(SHAiButtonCopr copr,
                        int initialAmount,
                        int debitAmount)
        SHADebit constructor. copr is the SHAiButtonCopr that is used to perform this transaction. After saving a reference to the SHA coprocessor, this constructor resets all parameters for this type of transaction to their default values.
        Parameters:
        copr - The coprocessor used for authentication and data signing in this transaction.
    • Method Detail

      • setupTransactionData

        public boolean setupTransactionData​(SHAiButtonUser user)
                                     throws OneWireException,
                                            OneWireIOException

        Setup account data on a fresh user iButton. Prior to calling setup transaction data, the authentication secret for the iButton should already be setup and a directory entry (as well as at least an empty placeholder file) should exist for the account data. If you constructed the SHAiButtonUser using SHAiButtonUser(SHAiButtonCopr,OneWireContainer18,boolean,byte[]) the secret has been setup for you and you should know call this function. If you try to install the authentication secret after creating the account data, you will destroy all account data on the iButton.

        You can set the value of the initial account balance by calling transaction.setParameter(SHADebit.INITIAL_AMOUNT,10000) where the value of the units is in cents (i.e. 10000 = $100).

        Flow of action:

        • Generate generic account page
        • Insert the initial balance into account data
        • Create a signature using coprocessor
        • Insert the digital signature
        • Write account data page to iButton

        Specified by:
        setupTransactionData in class SHATransaction
        Parameters:
        user - SHAiButtonUser upon which the transaction occurs.
        Returns:
        trueif and only if the signature is successfully created by the coprocessor AND the data is successfully written to the user iButton.
        Throws:
        OneWireException
        OneWireIOException
        See Also:
        SHAiButtonCopr.createDataSignature(byte[],byte[],byte[],int), SHAiButtonUser.writeAccountData(byte[],int), SHATransaction.getLastError()
      • getParameter

        public int getParameter​(int type)

        Retrieves the value of a particular parameter for this debit transaction.

        Valid Parameters

        • SHADebit.DEBIT_AMOUNT
        • SHADebit.INITIAL_AMOUNT
        • SHADebit.USER_BALANCE

        Note that the value of SHADebit.USER_BALANCE will be set after calling verifyTransactionData(SHAiButtonUser) and after calling executeTransaction(SHAiButtonUser).

        Specified by:
        getParameter in class SHATransaction
        Returns:
        The value of the requested parameter.
        Throws:
        java.lang.IllegalArgumentException - if an invalid parameter type is requested.
      • setParameter

        public boolean setParameter​(int type,
                                    int param)

        Sets the value of a particular parameter for this debit transaction.

        Valid Parameters

        • SHADebit.DEBIT_AMOUNT
        • SHADebit.INITIAL_AMOUNT

        Specified by:
        setParameter in class SHATransaction
        Parameters:
        type - Specifies the parameter type (SHADebit.DEBIT_AMOUNT or SHADebit.INITIAL_AMOUNT)
        Returns:
        true if a valid parameter type was specified and the value of the parameter is positive.
        Throws:
        java.lang.IllegalArgumentException - if an invalid parameter type is requested.
      • resetParameters

        public void resetParameters()

        Resets all transaction parameters to default values

        Specified by:
        resetParameters in class SHATransaction