Package opencard.core.terminal

Class CardTerminal

  • Direct Known Subclasses:
    CTAPICardTerminal, JCOPSimCardTerminal, RemoteTerminal, SmartCardIOTerminal
    public abstract class CardTerminal
extends java.lang.Object
    The CardTerminal class represents a physical card terminal. It is assumed that a certain card terminal provides (at least one) slot for a smart card or a transceiver for a contactless smart card. Please NOTE that throughout OpenCard Framework inserting or removing a card may equally well mean that a connection between a contactless card and a transceiver was established or ended respectively.
    Depending on the features of the specific card terminal a concrete implementation might also implement additional, optional, interfaces (as found in opencard.opt.terminal.

    Similar to the PCSC smart card specification we assume that the card terminal will automatically power up the smart card and retrieve the ATR response (available through cardID() as a CardID object).

    CardTerminal objects are created by a CardTerminalFactory and registered in the CardTerminalRegistry. To get an enumeration of the available CardTerminals invoke CardTerminalRegistry.getCardTerminals ().

    Author:
    Dirk Husemann (hud@zurich.ibm.com), Peter Trommler (trp@zurich.ibm.com), Mike Wendler (mwendler@de.ibm.com), Stephan Breideneich (sbreiden@de.ibm.com)
    See Also:
    CardTerminalRegistry, CardTerminalFactory, CardID

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String address  
      protected java.lang.String name
      Useful information about this card terminal: the name, the type, and the address (usually meaning the COM port) as registered with the CardTerminalRegistry.
      protected java.util.Vector slots
      Deprecated. 
      protected java.lang.String type  

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected CardTerminal​(java.lang.String name, java.lang.String type, java.lang.String address)
      Instantiates a CardTerminal object.

    • Field Detail

      • slots

        @Deprecated
protected java.util.Vector slots
        Deprecated.
        the installed slots in the terminal

      • name

        protected final java.lang.String name
        Useful information about this card terminal:
        • the name,
        • the type, and
        • the address (usually meaning the COM port)
        as registered with the CardTerminalRegistry.

      • type

        protected final java.lang.String type

      • address

        protected final java.lang.String address

    • Constructor Detail

      • CardTerminal

        protected CardTerminal​(java.lang.String name,
                       java.lang.String type,
                       java.lang.String address)
        Instantiates a CardTerminal object.
        Parameters:
        name - The user friendly name.
        type - The terminal type.
        address - An identifier for the driver to locate the terminal.

    • Method Detail

      • enumerateSlots

        @Deprecated
public java.util.Enumeration enumerateSlots()
        Deprecated.

      • features

        public final java.util.Properties features()
        Query the card terminal about its features.

        Each feature is represented by a property. The standard features are

        • name: as configured and registered with the CardTerminalRegistry
        • type: as configured and registered with the CardTerminalRegistry
        • address: as configured and registered with the CardTerminalRegistry
        • slots: the number of slots belonging to this CardTerminal
        In addition, each CardTerminal implementation provides a set of card terminal specific features.

        Returns:
        A list of properties describing the features of this card terminal.

      • getAddress

        public java.lang.String getAddress()
        Return the address of this CardTerminal.

        Returns:
        The address of this CardTerminal as a String.

      • getCardID

        public abstract CardID getCardID​(int slotID)
                          throws CardTerminalException
        Return the answer-to-reset (ATR) response of the card inserted in slot slotID as a CardID. Before calling this method the caller should make sure that a card is present, otherwise null may be returned.

        This call should NOT block if no card is present.

        Parameters:
        slotID - slot id.
        Returns:
        The ATR response in form of a CardID object or null if no card is present.
        Throws:
        CardTerminalException - Thrown in case of problems in the card terminal.

      • getName

        public java.lang.String getName()
        Return the name associated with this CardTerminal.

        Returns:
        The name of this CardTerminal as a String.

      • getSlot

        @Deprecated
public Slot getSlot​(int slotID)
             throws java.lang.IndexOutOfBoundsException
        Deprecated.
        Throws:
        java.lang.IndexOutOfBoundsException

      • getType

        public java.lang.String getType()
        Return the type of this CardTerminal.

        Returns:
        The type of this CardTerminal as a String.

      • slots

        @Deprecated
public Slot[] slots()
        Deprecated.
        use getSlots() instead

      • getSlots

        public int getSlots()
        Return the number of slots belonging to this CardTerminal object.

      • isCardPresent

        public abstract boolean isCardPresent​(int slotID)
                               throws CardTerminalException
        Check whether there is a smart card present in a particular slot.
        Parameters:
        slotID - slot to check for a card.
        Returns:
        True if there is a smart card inserted in the slot.
        Throws:
        CardTerminalException - thrown in case of problems getting the status from CardTerminal (or other serious problems in the terminal).

      • isSlotChannelAvailable

        public boolean isSlotChannelAvailable​(int slotID)
        Check whether a SlotChannel is available for a particular slot.
        Parameters:
        slotID - The slot to check.
        Returns:
        True if there is a SlotChannel available.

      • isSlotChannelAvailable

        @Deprecated
public boolean isSlotChannelAvailable​(Slot slot)
        Deprecated.
        use isSlotChannelAvailable(int) instead

      • open

        public abstract void open()
                   throws CardTerminalException
        Initializes the CardTerminal. Implementations of this method must carry out all steps required to set the concrete terminal into a proper state. After invoking this method it should be possible to communicate with the terminal properly.
        Throws:
        CardTerminalException - thrown in case of initialization-errors (e.g. couldn't setup transfer protocol between CardTerminal and reader).

      • close

        public abstract void close()
                    throws CardTerminalException
        Closes the CardTerminal. Implementations of this method must carry out all steps required to close the concrete terminal and free resources held by it.
        Throws:
        CardTerminalException - thrown in case of initialization-errors (e.g. couldn't setup transfer protocol between CardTerminal and reader).

      • openSlotChannel

        public final SlotChannel openSlotChannel​(int slotID,
                                         java.lang.Object lockHandle)
                                  throws InvalidSlotChannelException,
                                         java.lang.IndexOutOfBoundsException,
                                         CardTerminalException
        Open a SlotChannel on Slot number slotID.
        Parameters:
        slotID - The number of the slot for which a SlotChannel is requested.
        lockHandle - trust ticket obtained from locking the terminal
        Throws:
        InvalidSlotChannelException - Thrown when slot channel is already allocated.
        java.lang.IndexOutOfBoundsException - Thrown when slotID is out of bounds.
        CardTerminalException - Thrown when internalOpenSlotChannel failed.

      • toString

        public java.lang.String toString()
        Returns a printable representation of this CardTerminal object.

        Overrides:
        toString in class java.lang.Object
        Returns:
        A String representing this CardTerminal object.

      • addSlots

        protected void addSlots​(int numberOfSlots)
                 throws CardTerminalException
        Add Slots to the CardTerminal. Used by the concrete CardTerminal implementations.
        Parameters:
        numberOfSlots - The number of slots to add.
        Throws:
        CardTerminalException - Thrown when instanciating of Slot failed.

      • cardRemoved

        protected void cardRemoved​(int slotID)
        Notify listeners that a card was removed from a slot of this terminal. (utility method).
        Parameters:
        slot - slot number of the slot where a card was removed

      • cardInserted

        protected void cardInserted​(int slotID)
        Notify listeners that a card was inserted into a slot of this terminal. (utility method).
        Parameters:
        slot - slot number of the slot where a card was inserted

      • internalFeatures

        protected java.util.Properties internalFeatures​(java.util.Properties features)
        The CardTerminal internal features() method to be provided by the concrete implementation. This default implementation just returns the parameter provided. Concrete implementations should override this method.
        Parameters:
        features - A Properties object that needs to be enhanced with the card terminal specific features.
        Returns:
        The enriched Properties object.

      • internalOpenSlotChannel

        protected void internalOpenSlotChannel​(int slotID)
                                throws CardTerminalException
        The internal openSlotChannel method. internalOpenSlotChannel is executed at the beginning of openSlotChannel.
        Parameters:
        slotID - The number of the slot for which a SlotChannel is requested.
        Throws:
        CardTerminalException - thrown in case of errors opening the card (e.g. error powering card).

      • internalOpenSlotChannel

        protected void internalOpenSlotChannel​(int slotID,
                                       java.lang.Object lockHandle)
                                throws CardTerminalException
        The internal openSlotChannel method for locked terminals (default implementation). Lockable terminals MUST overwrite this method. internalOpenSlotChannel is executed at the beginning of openSlotChannel.
        Parameters:
        slotID - The number of the slot for which a SlotChannel is requested.
        lockHandle - the trust ticket that the lock owner obtained when locking the terminal or slot
        Throws:
        CardTerminalException - thrown in case of errors opening the card (e.g. error powering card).

      • internalCloseSlotChannel

        protected void internalCloseSlotChannel​(SlotChannel sc)
                                 throws CardTerminalException
        The internal closeSlotChannel method. internalCloseSlotChannel is executed at the end of closeSlotChannel.
        Parameters:
        SlotChannel - The SlotChannel to close.
        Throws:
        CardTerminalException - thrown in case of errors closing the card (e.g. error disconnecting the card).

      • internalReset

        protected abstract CardID internalReset​(int slot,
                                        int ms)
                                 throws CardTerminalException
        The internal reset method to be provided by the concrete implementation.
        Parameters:
        slot - The slot number of the slot to be resetted.
        ms - To be ignored. If the card does not respond within the time specified for the protocol an exception should be thrown.
        Returns:
        The CardID of the card.
        Throws:
        CardTerminalException - thrown in case of errors during reset

      • internalReset

        protected CardID internalReset​(int slot,
                               boolean warm)
                        throws CardTerminalException
        The internal reset method may be overwritten by the actual implementation to support warm resets.
        Parameters:
        slot - The slot number of the slot to be resetted.
        ms - To be ignored. If the card does not respond within the time specified for the protocol an exception should be thrown.
        Returns:
        The CardID of the card.
        Throws:
        CardTerminalException - thrown in case of errors during reset

      • internalSendAPDU

        protected abstract ResponseAPDU internalSendAPDU​(int slot,
                                                 CommandAPDU capdu,
                                                 int ms)
                                          throws CardTerminalException
        The internalSendAPDU method to be provided by the concrete implementation.
        Parameters:
        slot - The slot number of the slot to be resetted.
        capdu - The CommandAPDU to send.
        ms - To be ignored. If the card does not respond within the time specified for the protocol an exception should be thrown.
        Returns:
        A ResponseAPDU.
        Throws:
        CardTerminalException - thrown in case of errors in the CardTerminal (e.g. errors during data exchange)