Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## opencard.core.terminal
Class CardTerminal

    java.lang.Object
      opencard.core.terminal.CardTerminal

Direct Known Subclasses:
  AbstractLockableTerminal, CTAPICardTerminal, JCOPSimCardTerminal, JCWDPSimCardTerminal, Pcsc10CardTerminal, 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 `CardTerminal`s invoke `CardTerminalRegistry.getCardTerminals ()`.

Version:
  $Id: CardTerminal.java,v 1.2 2005/09/19 10:21:22 asc Exp $
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
`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.
`protected void` | `cardRemoved(int slotID)` Notify listeners that a card was removed from a slot of this terminal.
`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.
`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 CardID` | `internalReset(int slot, boolean warm)` The internal reset method may be overwritten by the actual implementation to support warm resets.
`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, boolean warm)` 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()` Deprecated. use getSlots() instead
`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.

  Throws:
    `CardTerminalException`

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

  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

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

### isCardPresent

    public boolean isCardPresent(Slot slot)
                          throws CardTerminalException

  Deprecated. use isCardPresent(int) instead

  Throws:
    `CardTerminalException`

### 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.
    `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.

### openSlotChannel

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

  Deprecated. use openSlotChannel(int) instead

  Throws:
    `InvalidSlotChannelException`
    `java.lang.IndexOutOfBoundsException`
    `CardTerminalException`

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

  Throws:
    `InvalidSlotChannelException`
    `CardTerminalException`

### 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`

### reset

    public final CardID reset(SlotChannel sc,
                              boolean warm)
                       throws InvalidSlotChannelException,
                              CardTerminalException

  Reset a smart card inserted in a slot.

  Parameters:
    `sc` - The open `SlotChannel` attached to the slot.
    `warm` - Perform a warm reset rather than a cold reset
  Throws:
    `InvalidSlotChannelException` - Thrown when the supplied `SlotChannel` is not valid.
    `CardTerminalException` - Thrown when error occurred in `internalReset`

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

  Throws:
    `InvalidSlotChannelException`
    `CardTerminalException`

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

### 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

  Throws:
    `CardTerminalException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD