OpenCard  
 
OCF, the OpenCard Framework is a standard Java framework for working with Smart Cards.  
 

opencard.core.terminal
Class CardTerminal

java.lang.Object
  |
  +--opencard.core.terminal.CardTerminal
Direct Known Subclasses:
AbstractLockableTerminal, com.gemplus.opencard.terminal.GemplusSerialCardTerminal, Pcsc10CardTerminal, PcscMigCardTerminal
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 ().

Version:
$Id: CardTerminal.java,v 1.3 1999/11/03 12:37:16 damke Exp $
See Also:
CardTerminalRegistry, CardTerminalFactory, CardID

Field Summary
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
protected CardTerminal(java.lang.String name, java.lang.String type, java.lang.String address)
          Instantiates a CardTerminal object.
 
Method Summary
protected  void addSlots(int numberOfSlots)
          Add Slots to the CardTerminal.
protected  void cardInserted(int slotID)
          Notify listeners that a card was inserted into a slot of this terminal. (utility method).
protected  void cardRemoved(int slotID)
          Notify listeners that a card was removed from a slot of this terminal. (utility method).
abstract  void close()
          Closes the CardTerminal.
 void closeSlotChannel(SlotChannel sc)
          Closes a SlotChannel.
 java.util.Enumeration enumerateSlots()
          Deprecated.  
 java.util.Properties features()
          Query the card terminal about its features. Each feature is represented by a property.
 java.lang.String getAddress()
          Return the address of this CardTerminal.
abstract  CardID getCardID(int slotID)
          Return the answer-to-reset (ATR) response of the card inserted in slot slotID as a CardID.
 CardID getCardID(int slotID, int ms)
          Deprecated.  
 java.lang.String getName()
          Return the name associated with this CardTerminal.
 Slot getSlot(int slotID)
          Deprecated.  
 int getSlots()
          Return the number of slots belonging to this CardTerminal object.
 java.lang.String getType()
          Return the type of this CardTerminal.
protected  void internalCloseSlotChannel(SlotChannel sc)
          The internal closeSlotChannel method.
protected  java.util.Properties internalFeatures(java.util.Properties features)
          The CardTerminal internal features() method to be provided by the concrete implementation.
protected  void internalOpenSlotChannel(int slotID)
          The internal openSlotChannel method.
protected  void internalOpenSlotChannel(int slotID, java.lang.Object lockHandle)
          The internal openSlotChannel method for locked terminals (default implementation).
protected abstract  CardID internalReset(int slot, int ms)
          The internal reset method to be provided by the concrete implementation.
protected abstract  ResponseAPDU internalSendAPDU(int slot, CommandAPDU capdu, int ms)
          The internalSendAPDU method to be provided by the concrete implementation.
abstract  boolean isCardPresent(int slotID)
          Check whether there is a smart card present in a particular slot.
 boolean isCardPresent(Slot slot)
          Deprecated. use isCardPresent(int) instead
 boolean isSlotChannelAvailable(int slotID)
          Check whether a SlotChannel is available for a particular slot.
 boolean isSlotChannelAvailable(Slot slot)
          Deprecated. use isSlotChannelAvailable(int) instead
abstract  void open()
          Initializes the CardTerminal.
 SlotChannel openSlotChannel(int slotID)
          Open a SlotChannel on Slot number slotID.
 SlotChannel openSlotChannel(int slotID, java.lang.Object lockHandle)
          Open a SlotChannel on Slot number slotID.
 SlotChannel openSlotChannel(Slot slot)
          Deprecated. use openSlotChannel(int) instead
 CardID reset(SlotChannel sc)
          Reset a smart card inserted in a slot.
 CardID reset(SlotChannel sc, int ms)
          Deprecated. use reset(SlotChannel)
 ResponseAPDU sendAPDU(SlotChannel sc, CommandAPDU capdu)
          Send a CommandAPDU on a slot.
 ResponseAPDU sendAPDU(SlotChannel sc, CommandAPDU capdu, int ms)
          Deprecated.  
 ResponseAPDU sendVerifiedCommandAPDU(SlotChannel chann, CommandAPDU capdu, CHVControl vc, int ms)
          default implementation for deprecated method in interface VerifiedAPDUInterface.
 Slot[] slots()
           
 java.lang.String toString()
          Returns a printable representation of this CardTerminal object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

slots

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

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.

getCardID

public CardID getCardID(int slotID,
                        int ms)
                 throws CardTerminalException
Deprecated.  

getName

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

Returns:
The name of this CardTerminal as a String.

getSlot

public Slot getSlot(int slotID)
             throws java.lang.IndexOutOfBoundsException
Deprecated.  

getType

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

Returns:
The type of this CardTerminal as a String.

slots

public Slot[] slots()

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).

isCardPresent

public boolean isCardPresent(Slot slot)
                      throws CardTerminalException
Deprecated. use isCardPresent(int) instead

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

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)
                                  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.
Throws:
InvalidSlotChannelException - Thrown when slot channel is already allocated.
java.lang.IndexOutOfBoundsException - Thrown when slotID is out of bounds.
CardTerminalException - Thrown when internalOpenSlotChannel failed.

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.
handle - 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.

openSlotChannel

public final SlotChannel openSlotChannel(Slot slot)
                                  throws InvalidSlotChannelException,
                                         java.lang.IndexOutOfBoundsException,
                                         CardTerminalException
Deprecated. use openSlotChannel(int) instead

closeSlotChannel

public final void closeSlotChannel(SlotChannel sc)
                            throws InvalidSlotChannelException,
                                   CardTerminalException
Closes a SlotChannel.
Parameters:
sc - The SlotChannel to close.
Throws:
InvalidSlotChannelException - when slot channel of the slot in the passed SlotChannel is not the same as the one passed
CardTerminalException - thrown in case of problem in internalCloseSlotChannel

reset

public final CardID reset(SlotChannel sc,
                          int ms)
                   throws InvalidSlotChannelException,
                          CardTerminalException
Deprecated. use reset(SlotChannel)

reset

public final CardID reset(SlotChannel sc)
                   throws InvalidSlotChannelException,
                          CardTerminalException
Reset a smart card inserted in a slot.
Parameters:
sc - The open SlotChannel attached to the slot.
Throws:
InvalidSlotChannelException - Thrown when the supplied SlotChannel is not valid.
CardTerminalException - Thrown when error occurred in internalReset
See Also:
internalReset(int, int)

sendAPDU

public final ResponseAPDU sendAPDU(SlotChannel sc,
                                   CommandAPDU capdu)
                            throws InvalidSlotChannelException,
                                   CardTerminalException
Send a CommandAPDU on a slot.
Parameters:
sc - The open SlotChannel attached to the slot.
capdu - The CommandAPDU to send.
Returns:
The ResponseAPDU as received from the card.
Throws:
InvalidSlotChannelException - Thrown when the supplied SlotChannel is not valid.
CardTerminalException - thrown in case of problems in the CardTerminal.

sendAPDU

public final ResponseAPDU sendAPDU(SlotChannel sc,
                                   CommandAPDU capdu,
                                   int ms)
                            throws InvalidSlotChannelException,
                                   CardTerminalException
Deprecated.  
Send a CommandAPDU on a slot.

toString

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

Returns:
A String representing this CardTerminal object.
Overrides:
toString in class java.lang.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

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)

sendVerifiedCommandAPDU

public ResponseAPDU sendVerifiedCommandAPDU(SlotChannel chann,
                                            CommandAPDU capdu,
                                            CHVControl vc,
                                            int ms)
                                     throws CardTerminalException
default implementation for deprecated method in interface VerifiedAPDUInterface. Note: throws an exception if this terminal does not implement VerifiedAPDUInterface