opencard.opt.terminal
Class AbstractLockableTerminal

java.lang.Object
  |
  +--opencard.core.terminal.CardTerminal
        |
        +--opencard.opt.terminal.AbstractLockableTerminal

public abstract class AbstractLockableTerminal
extends opencard.core.terminal.CardTerminal
implements Lockable

AbstractLockableTerminal is a base class for implementing lockable CardTerminals.

See Also:
CardTerminal, Lockable

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)
           
protected  void internalOpenSlotChannel(int slotID, java.lang.Object lockHandle)
           
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, internalSendAPDU, isCardPresent, isCardPresent, isSlotChannelAvailable, isSlotChannelAvailable, open, openSlotChannel, openSlotChannel, openSlotChannel, 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 opencard.core.terminal.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

unlock

public void unlock(java.lang.Object handle)
            throws opencard.core.terminal.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

lockSlot

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

unlockSlot

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

internalLock

protected abstract void internalLock()
                              throws opencard.core.terminal.CardTerminalException

internalUnlock

protected abstract void internalUnlock()
                                throws opencard.core.terminal.CardTerminalException

internalLockSlot

protected abstract void internalLockSlot(int slotNr)
                                  throws opencard.core.terminal.CardTerminalException

internalUnlockSlot

protected abstract void internalUnlockSlot(int slotNr)
                                    throws opencard.core.terminal.CardTerminalException

internalOpenSlotChannel

protected final void internalOpenSlotChannel(int slotID)
                                      throws opencard.core.terminal.CardTerminalException
Overrides:
internalOpenSlotChannel in class opencard.core.terminal.CardTerminal

internalOpenSlotChannel

protected final void internalOpenSlotChannel(int slotID,
                                             java.lang.Object lockHandle)
                                      throws opencard.core.terminal.CardTerminalException
Overrides:
internalOpenSlotChannel in class opencard.core.terminal.CardTerminal

lockableOpenSlotChannel

protected abstract void lockableOpenSlotChannel(int slot)
                                         throws opencard.core.terminal.CardTerminalException