opencard.opt.terminal
Class AbstractLockableTerminal

java.lang.Object
  extended by opencard.core.terminal.CardTerminal
      extended by opencard.opt.terminal.AbstractLockableTerminal
All Implemented Interfaces:
Lockable
Direct Known Subclasses:
Pcsc10LockableTerminal

public abstract class AbstractLockableTerminal
extends CardTerminal
implements Lockable

AbstractLockableTerminal is a base class for implementing lockable CardTerminals.

Version:
$Id: AbstractLockableTerminal.java,v 1.1 1999/10/22 14:43:29 damke Exp $
Author:
Peter Bendel(peter_bendel@de.ibm.com)
See Also:
CardTerminal, Lockable

Field Summary
 
Fields inherited from class opencard.core.terminal.CardTerminal
address, name, slots, type
 
Constructor Summary
protected AbstractLockableTerminal(java.lang.String name, java.lang.String type, java.lang.String address)
          Instantiates a CardTerminal object.
 
Method Summary
protected  java.lang.Thread getSlotLockHandle(int slot)
           
protected  java.lang.Object getTerminalLockHandle()
          accessors for subclasses
protected abstract  void internalLock()
           
protected abstract  void internalLockSlot(int slotNr)
           
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  void internalUnlock()
           
protected abstract  void internalUnlockSlot(int slotNr)
           
 java.lang.Object lock()
          Lock the whole terminal including all slots, pinpad, display and other resources.
protected abstract  void lockableOpenSlotChannel(int slot)
           
 java.lang.Object lockSlot(int slotNr)
           
 void unlock(java.lang.Object handle)
          Unlock the whole terminal including all slots, pinpad, other resources.
 void unlockSlot(int slotNr, java.lang.Object handle)
           
 
Methods inherited from class opencard.core.terminal.CardTerminal
addSlots, cardInserted, cardRemoved, close, closeSlotChannel, enumerateSlots, features, getAddress, getCardID, getCardID, getName, getSlot, getSlots, getType, internalCloseSlotChannel, internalFeatures, internalReset, internalReset, internalSendAPDU, isCardPresent, isCardPresent, isSlotChannelAvailable, isSlotChannelAvailable, open, openSlotChannel, openSlotChannel, openSlotChannel, reset, reset, reset, sendAPDU, sendAPDU, sendVerifiedCommandAPDU, slots, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AbstractLockableTerminal

protected AbstractLockableTerminal(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

getTerminalLockHandle

protected java.lang.Object getTerminalLockHandle()
accessors for subclasses


getSlotLockHandle

protected java.lang.Thread getSlotLockHandle(int slot)

lock

public final java.lang.Object lock()
                            throws CardTerminalException
Lock the whole terminal including all slots, pinpad, display and other resources.

A thread can call CardTerminal.lock() to lock a card terminal and all of its slots and CardTerminal.unlock() to return ownership of the lock. The lock() method can only be called successfully when the card terminal has no slot channels open and no other thread has locked a slot. The lock() call also prevents other threads from using the pin pad and display of the card terminal and from sending terminal commands.

Checking these conditions and maintaining the lock owner and list of locked slots is done in this abstract class. The actual locking is delegated to specific subclasses.

Important: whether the caller may send a terminal command MUST be checked in the subclass, since this abstract class cannot know whether the subclass implements the TerminalCommand interface.

Specified by:
lock in interface Lockable
Returns:
a handle (trust ticket) for the lock owner
Throws:
TerminalLockedException - locking failed
CardTerminalException

unlock

public void unlock(java.lang.Object handle)
            throws CardTerminalException
Unlock the whole terminal including all slots, pinpad, other resources. This call can only be called by a thread that has previously locked the terminal using lock(). It should not be used to unlock after having used lockSlot().

Specified by:
unlock in interface Lockable
Throws:
TerminalLockedException - unlocking failed
CardTerminalException

lockSlot

public java.lang.Object lockSlot(int slotNr)
                          throws CardTerminalException
Specified by:
lockSlot in interface Lockable
Throws:
CardTerminalException

unlockSlot

public void unlockSlot(int slotNr,
                       java.lang.Object handle)
                throws CardTerminalException
Specified by:
unlockSlot in interface Lockable
Throws:
CardTerminalException

internalLock

protected abstract void internalLock()
                              throws CardTerminalException
Throws:
CardTerminalException

internalUnlock

protected abstract void internalUnlock()
                                throws CardTerminalException
Throws:
CardTerminalException

internalLockSlot

protected abstract void internalLockSlot(int slotNr)
                                  throws CardTerminalException
Throws:
CardTerminalException

internalUnlockSlot

protected abstract void internalUnlockSlot(int slotNr)
                                    throws CardTerminalException
Throws:
CardTerminalException

internalOpenSlotChannel

protected final void internalOpenSlotChannel(int slotID)
                                      throws CardTerminalException
Description copied from class: CardTerminal
The internal openSlotChannel method. internalOpenSlotChannel is executed at the beginning of openSlotChannel.

Overrides:
internalOpenSlotChannel in class CardTerminal
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 final void internalOpenSlotChannel(int slotID,
                                             java.lang.Object lockHandle)
                                      throws CardTerminalException
Description copied from class: CardTerminal
The internal openSlotChannel method for locked terminals (default implementation). Lockable terminals MUST overwrite this method. internalOpenSlotChannel is executed at the beginning of openSlotChannel.

Overrides:
internalOpenSlotChannel in class CardTerminal
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).

lockableOpenSlotChannel

protected abstract void lockableOpenSlotChannel(int slot)
                                         throws CardTerminalException
Throws:
CardTerminalException