Package 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.
- Author:
- Dirk Husemann (hud@zurich.ibm.com), Mike Wendler (mwendler@de.ibm.com), Stephan Breideneich (sbreiden@de.ibm.com), Thomas Schaeck (schaeck@de.ibm.com)
- See Also:
CardService
-
-
Constructor Summary
Constructors Constructor Description SmartCard(CardServiceScheduler scheduler, CardID cid)
Instantiates a SmartCard object that is tied to scheduler.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description 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.APDUTracer
getAPDUTracer()
Return the current APDUTracerCardID
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 formstatic boolean
isStarted()
Determines whether the startup process has already been carried out during this session.CardID
reset(boolean warm)
Reset inserted cardvoid
setAPDUTracer(APDUTracer tracer)
Sets the APDU tracer that monitors all APDU to and from the card-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 void
startup()
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.
-
-
-
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 formOCF1.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 classjava.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
@Deprecated public static SmartCard getSmartCard(CardTerminalEvent ctEvent) throws CardTerminalException
Deprecated.use getSmartCard(CardTerminalEvent, CardRequest)- Throws:
CardTerminalException
-
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.
- Throws:
CardTerminalException
-
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.
- Throws:
CardTerminalException
-
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.- Throws:
CardTerminalException
-
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 foundOpenCardPropertyLoadingException
- thrown if something goes wrong during the the property loading processCardServiceException
CardTerminalException
-
startup
public static void startup() 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 does not fill the CardTerminalRegistry and CardServiceRegistry, which is left to the application.- Throws:
java.lang.ClassNotFoundException
- thrown when one of the required classes is not foundOpenCardPropertyLoadingException
- thrown if something goes wrong during the the property loading processCardServiceException
CardTerminalException
-
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.
- Throws:
CardTerminalException
- 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.
- Throws:
CardTerminalException
- 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)
-
reset
public CardID reset(boolean warm) throws CardTerminalException
Reset inserted card- Returns:
- CardID of card in reader
- Throws:
CardTerminalException
-
setAPDUTracer
public void setAPDUTracer(APDUTracer tracer)
Sets the APDU tracer that monitors all APDU to and from the card-- Parameters:
tracer
- the APDUTracer
-
getAPDUTracer
public APDUTracer getAPDUTracer()
Return the current APDUTracer- Returns:
-
-