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

opencard.core.service
Class SmartCard

java.lang.Object
  |
  +--opencard.core.service.SmartCard
public final class SmartCard
extends java.lang.Object

The SmartCard object is the point of access to the OpenCard framework for the application. CardServices are accessible through the services of the SmartCard object.

A SmartCard object is always tied to the controlling CardServiceScheduler.

Version:
$Id: SmartCard.java,v 1.3 1999/11/03 12:37:16 damke Exp $
See Also:
CardService

Constructor Summary
SmartCard(CardServiceScheduler scheduler, CardID cid)
          Instantiates a SmartCard object that is tied to scheduler.
 
Method Summary
 void beginMutex()
          Gain exclusive access to the card.
 void close()
          Closes this SmartCard object and signals to OCF that the allocated resources are not any longer required.
 void endMutex()
          Releases exclusive access to the card.
protected  void finalize()
          Finalizer: close this SmartCard in case it is still open.
 CardID getCardID()
          Gets the CardID object representing this smart card.
 CardService getCardService(java.lang.Class clazz, boolean block)
          Tries to instantiate a CardService for the smart card that implements class clazz.
static SmartCard getSmartCard(CardTerminalEvent ctEvent)
          Deprecated. use getSmartCard(CardTerminalEvent, CardRequest)
static SmartCard getSmartCard(CardTerminalEvent ctEvent, CardRequest req)
          Gets a SmartCard object for a received CardTerminalEvent provided that the CardRequest can be satisfied.
static SmartCard getSmartCard(CardTerminalEvent ctEvent, CardRequest req, java.lang.Object lockHandle)
          Gets a SmartCard object for a received CardTerminalEvent provided that the CardRequest can be satisfied.
static java.lang.String getVersion()
          return version information about OCF It returns a string of the form OCF1.2;IBM Reference Implementation, Build Hudson, 21-May-1999 The first part indicates the API.
static boolean isStarted()
          Determines whether the startup process has already been carried out during this session.
static void shutdown()
          Shuts down the entire OpenCard Framework.
static void start()
          Initializes the entire OpenCard Framework and is meant to be the first method to be invoked in any application in order to setup OpenCard properly.
static SmartCard waitForCard(CardRequest req)
          Waits for a card to be inserted into any of the card terminals attached to the system.
static SmartCard waitForCard(CardRequest req, java.lang.Object lockHandle)
          Waits for a card to be inserted into any of the locked card terminals attached to the system.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SmartCard

public SmartCard(CardServiceScheduler scheduler,
                 CardID cid)
Instantiates a SmartCard object that is tied to scheduler.
Parameters:
scheduler - The controlling CardServiceScheduler.
cid - The CardID object representing the physical smart card.
Method Detail

getVersion

public static java.lang.String getVersion()
return version information about OCF It returns a string of the form

OCF1.2;IBM Reference Implementation, Build Hudson, 21-May-1999

The first part indicates the API. It always starts with "OCF", followed by an API version number, and terminate by a semicolon. Currently, this the API version number is simply the OCF release number. When a formal OCF specification becomes available, it would refer to the version of that specification it implements. After the semicolon, vendor specific information is included. The format of the vendor specific information is not specified.

beginMutex

public void beginMutex()
                throws java.lang.InterruptedException,
                       CardTerminalException
Gain exclusive access to the card. Be sure to call endMutex() eventually!.
Throws:
java.lang.InterruptedException - Thrown when no exclusive access to the card could be gained.
CardTerminalException - Thrown when the terminal encountered an error.
See Also:
CardService.setCardChannel(opencard.core.service.CardChannel), CardServiceScheduler.allocateCardChannel(java.lang.Object, boolean)

close

public void close()
           throws CardTerminalException
Closes this SmartCard object and signals to OCF that the allocated resources are not any longer required.
Throws:
CardTerminalException - Thrown when an error is encountered during cleanup.

endMutex

public void endMutex()
Releases exclusive access to the card.

finalize

protected void finalize()
Finalizer: close this SmartCard in case it is still open.
Overrides:
finalize in class java.lang.Object

getCardID

public CardID getCardID()
Gets the CardID object representing this smart card.
Returns:
The CardID object.

getCardService

public CardService getCardService(java.lang.Class clazz,
                                  boolean block)
                           throws java.lang.ClassNotFoundException,
                                  CardServiceException
Tries to instantiate a CardService for the smart card that implements class clazz.
Parameters:
clazz - The class that the CardService shall implement.
block - If true, indicates that the CardService should run in blocking mode.
Throws:
java.lang.ClassNotFoundException - Thrown when no CardService implementing clazz exists for this card.
CardServiceException - Thrown when a service was found but failed to initialize.

getSmartCard

public static SmartCard getSmartCard(CardTerminalEvent ctEvent)
                              throws CardTerminalException
Deprecated. use getSmartCard(CardTerminalEvent, CardRequest)

getSmartCard

public static SmartCard getSmartCard(CardTerminalEvent ctEvent,
                                     CardRequest req)
                              throws CardTerminalException
Gets a SmartCard object for a received CardTerminalEvent provided that the CardRequest can be satisfied.
Parameters:
ctEvent - The received CardTerminalEvent.
req - A CardRequest object describing the kind of smart card that we are interested in.
Returns:
A SmartCard object.

getSmartCard

public static SmartCard getSmartCard(CardTerminalEvent ctEvent,
                                     CardRequest req,
                                     java.lang.Object lockHandle)
                              throws CardTerminalException
Gets a SmartCard object for a received CardTerminalEvent provided that the CardRequest can be satisfied.
Parameters:
ctEvent - The received CardTerminalEvent.
req - A CardRequest object describing the kind of smart card that we are interested in.
lockHandle - the handle obtained by the lock owner when locking a slot or terminal.
Returns:
A SmartCard object.

isStarted

public static boolean isStarted()
Determines whether the startup process has already been carried out during this session. NOTE however that this says nothing at all about success or failure of this process!
Returns:
true if the setup process has been carried out during this session, false otherwise.

shutdown

public static void shutdown()
                     throws CardTerminalException
Shuts down the entire OpenCard Framework. This is meant to be the last method to be invoked in any application in order to close OpenCard properly. This process will cause CardTerminalRegistry and CardServiceRegistry to cleanup themselves and leave OpenCard in a clean state.

start

public static void start()
                  throws OpenCardPropertyLoadingException,
                         java.lang.ClassNotFoundException,
                         CardServiceException,
                         CardTerminalException
Initializes the entire OpenCard Framework and is meant to be the first method to be invoked in any application in order to setup OpenCard properly. This process tries to get the OpenCard properties and fill the CardTerminalRegistry and CardServiceRegistryby means of the according property entries.
Throws:
java.lang.ClassNotFoundException - thrown when one of the required classes is not found
OpenCardPropertyLoadingException - thrown if something goes wrong during the the property loading process

waitForCard

public static SmartCard waitForCard(CardRequest req)
                             throws CardTerminalException
Waits for a card to be inserted into any of the card terminals attached to the system. Returns a SmartCard object if the provided CardRequest matches the inserted SmartCard. Returns null if a SmartCard is inserted that doesn't match the CardRequest. This method must not be called from the event handling methods cardInserted or cardRemoved of a CTListener, since this may result in a deadlock. If a card request for a card inserted event has to be satisfied, getSmartCard has to be used instead.
Parameters:
req - A CardRequest object describing the kind of smart card that we are interested in.
Returns:
A SmartCard object if the request could be satisfied; null if it could not, because a timeout occurred.
See Also:
CardRequest, CTListener, CTListener.cardInserted(opencard.core.event.CardTerminalEvent), CTListener.cardRemoved(opencard.core.event.CardTerminalEvent), getSmartCard(opencard.core.event.CardTerminalEvent, opencard.core.service.CardRequest)

waitForCard

public static SmartCard waitForCard(CardRequest req,
                                    java.lang.Object lockHandle)
                             throws CardTerminalException
Waits for a card to be inserted into any of the locked card terminals attached to the system. Returns a SmartCard object if the provided CardRequest matches the inserted SmartCard.
Parameters:
req - A CardRequest object describing the kind of smart card that we are interested in.
lockHandle - handle obtained by lock owner when locking a terminal. This parameter is only necessary for locked terminals / slots.
Returns:
A SmartCard object if the request could be satisfied; null if it could not, because a timeout occurred.
See Also:
CardRequest, CTListener, CTListener.cardInserted(opencard.core.event.CardTerminalEvent), CTListener.cardRemoved(opencard.core.event.CardTerminalEvent), getSmartCard(opencard.core.event.CardTerminalEvent, opencard.core.service.CardRequest)