opencard.core.service
Class CardServiceScheduler

java.lang.Object
  |
  +--opencard.core.service.CardServiceScheduler

public final class CardServiceScheduler
extends java.lang.Object
implements CTListener

Manager for logical channels to an inserted smartcard. For each smart card known to the system and in use by some application there is one CardServiceScheduler that manages the access to the physical smart card. This is acchieved by allocating the available communication channels to the CardServices that want to access the card. The CardServiceScheduler takes care of state management and issues such as suspending active and resuming suspended CardServices.

Note that the current version supports only one logical channel per smart card. To support multiple channels, the internal structure of this class as well as the public interface has to be changed. One way to change the public interface would be to add a method named setCustomChannels, which works similiar to setCustomChannel but expects an array of channels that have to be managed. A second method to set only the number of channels to manage should then be added, too. In any case, it is a card service factory's responsibility to switch the scheduler to multi-channel support.

See Also:
CardService, CardChannel, SmartCard, CardServiceFactory

Constructor Summary
CardServiceScheduler(SlotChannel slotchannel)
          Instantiates a new scheduler that is tied to the given slot channel.
 
Method Summary
 CardChannel allocateCardChannel(java.lang.Object applicant, boolean block)
          Allocates a card channel.
 void cardInserted(CardTerminalEvent ctEvent)
          Dummy method.
 void cardRemoved(CardTerminalEvent ctEvent)
          Signals that a smartcard has been removed.
protected  SmartCard createSmartCard(CardID cid)
          Creates a new SmartCard object.
 SlotChannel getSlotChannel()
          Returns the slot channel for this scheduler.
protected  boolean isAlive()
          Checks whether this scheduler is alive.
 boolean isCustomized()
          Deprecated.  
 void releaseCardChannel(CardChannel channel)
          Releases a card channel.
protected  void releaseSmartCard(SmartCard card)
          Releases a SmartCard object.
 CardID reset(CardChannel ch, boolean block)
          Reset the card associated with this CardServiceScheduler
 void setCustomChannel(CardChannel channel)
          Deprecated. use CardChannel.setState() instead
 java.lang.String toString()
          Returns a human-readable string representation of this scheduler.
 void useDefaultChannel()
          Deprecated.  
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CardServiceScheduler

public CardServiceScheduler(SlotChannel slotchannel)
Instantiates a new scheduler that is tied to the given slot channel.
Parameters:
slotChannel - the physical channel to use for communicating with the card
Method Detail

setCustomChannel

public void setCustomChannel(CardChannel channel)
                      throws InvalidCardChannelException
Deprecated. use CardChannel.setState() instead

useDefaultChannel

public void useDefaultChannel()
                       throws InvalidCardChannelException
Deprecated.  

isCustomized

public final boolean isCustomized()
Deprecated.  

getSlotChannel

public final SlotChannel getSlotChannel()
Returns the slot channel for this scheduler.
Returns:
the slot channel for this scheduler

allocateCardChannel

public CardChannel allocateCardChannel(java.lang.Object applicant,
                                       boolean block)
                                throws CardTerminalException
Allocates a card channel. The allocated channel has to be freed using releaseCardChannel.
Parameters:
applicant - The object requesting the card channel. This parameter will be useful when support for multi-channel cards is implemented. It allows to implement channel affinity.
block - If true the calling thread will be suspended until a CardChannel becomes available; if false allocateCardChannel() will return null at once.
Returns:
The allocated card channel, or null if none has been allocated.
Throws:
CardTerminalException - if the terminal encountered an error. This can only happen if the smartcard was removed, in which case the scheduler will close down. When closing down, the underlying slot channel is closed down, too. This may result in this exception.
See Also:
releaseCardChannel(opencard.core.service.CardChannel)

releaseCardChannel

public void releaseCardChannel(CardChannel channel)
                        throws InvalidCardChannelException
Releases a card channel. The channel to release must have been allocated using allocateCardChannel.
Parameters:
channel - the card channel to release
Throws:
InvalidCardChannelException - The CardChannel has not been allocated here.
See Also:
allocateCardChannel(java.lang.Object, boolean)

reset

public final CardID reset(CardChannel ch,
                          boolean block)
                   throws CardTerminalException
Reset the card associated with this CardServiceScheduler
Parameters:
channel - If the caller already has a channel he can provide it. Otherwise the scheduler will allocate the channel itsself.
block - If true the calling thread will be suspended until a CardChannel becomes available; if false allocateCardChannel() will return null at once.
Returns:
CardID ATR of the card reset. null iff a channel is in use and the request was non-blocking
Throws:
CardTerminalException - Reset failed

cardInserted

public void cardInserted(CardTerminalEvent ctEvent)
Dummy method. Since the scheduler is interested only in the removal of the associated smartcard, card insertion events are ignored. This method has to be implemented anyway, since it is required by CTListener.
Specified by:
cardInserted in interface CTListener
See Also:
CTListener

cardRemoved

public void cardRemoved(CardTerminalEvent ctEvent)
                 throws CardTerminalException
Signals that a smartcard has been removed. If the removed card is the one associated with this scheduler, the scheduler will shut down. Any channels to the smartcard will be closed. This method is required by the interface CTListener.
Specified by:
cardRemoved in interface CTListener
Parameters:
ctEvent - an event indicating that a smartcard has been removed
See Also:
CTListener

toString

public java.lang.String toString()
Returns a human-readable string representation of this scheduler.
Returns:
a string representing this scheduler
Overrides:
toString in class java.lang.Object

isAlive

protected final boolean isAlive()
                         throws CardTerminalException
Checks whether this scheduler is alive.
Returns:
true if it is, false otherwise

createSmartCard

protected SmartCard createSmartCard(CardID cid)
                             throws CardTerminalException
Creates a new SmartCard object. A reference counter gets incremented.
Parameters:
cid - The CardID representing the smart card.
Returns:
A SmartCard attached to this CardServiceScheduler.
Throws:
CardTerminalException - The terminal encountered an error.

releaseSmartCard

protected void releaseSmartCard(SmartCard card)
                         throws CardTerminalException
Releases a SmartCard object. If the reference counter reaches 0, the SlotChannel is closed and the CardServiceRegistry gets told that our job is done.
Parameters:
card - The SmartCard object to release.