Package opencard.core.service

Class CardService

  • Direct Known Subclasses:
    BasicAppletCardService, EACCardService, IsoCardService, PassThruCardService, RemoteClientCardService, SecurityDomainCardService
    public abstract class CardService
extends java.lang.Object
    Provides specific smart card functionality to applications. This functionality may be, for example, an ISO 7816-4 file system or a ISO 7816-7 data base system. A concrete card service is almost always smart card operating system specific.

    Communication with a smart card takes place through a CardChannel that the card service either allocates from a CardServiceScheduler or gets from a third party, for example another card service or the corresponding SmartCard object if beginMutex is invoked there.
    The methods to allocate and release card channels provided here are aware of channels that have been pre-set by a third party. A public method providing card functionality in a class derived from CardService will typically have the following structure: 

     public RetType doSomeThingWithCard(...)
     throws CardServiceException, CardTerminalException
 {
   ... // check parameters
   RetType retvalue = null;
   try {
     allocateCardChannel(); // ensure there is a channel
     CommandAPDU  command  = ...;
     ResponseAPDU response =
              getCardChannel().sendCommandAPDU(command);
     ... // evaluate response, maybe send further commands
     retvalue = ...;
   } finally {             // despite any exceptions
     releaseCardChannel(); // free the card channel
   }
   return retvalue;
 }
    Author:
    Dirk Husemann (hud@zurich.ibm.com), Reto Hermann (rhe@zurich.ibm.com), Thomas Schaeck (schaeck@de.ibm.com), Roland Weber (rolweber@de.ibm.com)
    See Also:
    CardChannel, CardServiceScheduler, SmartCard.beginMutex()

    • Method Detail

      • setCardChannel

        public void setCardChannel​(CardChannel channel)
        Sets the channel to use for communicating with the smartcard. Setting the channel with this method avoids allocating a channel before each operation, and releasing it afterwards. This can be used to issue a series of commands to the smartcard that has to or should be processed without intervening commands, for example to avoid additional SELECT operations or multiple password queries that would have to be performed by the service otherwise.
        This method is typically invoked from SmartCard.beginMutex. All services used by an application will be provided with the same channel, and no other application will have access to the smartcard (unless it supports multiple logical channels). A second use for this method are services that are built on top of other services and provide their own channel, the so-called meta services.
        Pre-setting a channel does not mean that allocateCardChannel and realeaseCardChannel cannot be invoked. Their implementation in this class just avoids the invocations of the scheduler if a channel is already available. They still check whether the scheduler is alive, or whether it has died since the smartcard has been removed. Derived services may add more functionality there, making the invocation of those methods necessary even if a channel has been pre-set.
        This method has intentionally not been declared final. A service that uses customized channels may want to prepare the channel for future use here.
        Parameters:
        channel - the channel to use, or null to reset

      • getCardChannel

        public final CardChannel getCardChannel()
        Gets the card channel to use for communicating with the smartcard. The channel returned has either been allocated using allocateCardChannel, or was provided by a third party via setCardChannel. If neither is true, this method will return null.
        If a service uses customized channels that provide additional methods, it is suggested to implement a method getMyChannel with a more special return type than here. That method could call this one and down-cast the channel returned.
        Returns:
        the channel for communication with the smartcard

      • setCHVDialog

        public void setCHVDialog​(CHVDialog dialog)
        Sets the CHV dialog to be used for getting passwords from the user. This method is intentionally not declared final, since a card service that uses helper objects may want to pass the dialog to one of them.
        Parameters:
        dialog - the CHV dialog to be used

      • getCard

        public final SmartCard getCard()
        Gets the smartcard object associated with this service. Services are requested at a particular instance of SmartCard which can be used to identify the smartcard and also represents the application that requested the service. This method returns the smartcard object that was used to request this service.
        Returns:
        the smartcard object for this service

      • initialize

        protected void initialize​(CardServiceScheduler scheduler,
                          SmartCard smartcard,
                          boolean blocking)
                   throws CardServiceException
        Initializes this service. This method is an extension to the constructor. It is invoked by the CardServiceFactory after creating a service using the default constructor. The service cannot be used until this method has been invoked and returned without throwing an exception.
        Derived services may override this method to perform extended initialization. However, the implementation in this class has to be invoked anyway. The preferred way to do this is by invoking super.initialize at the beginning of the redefined method. This mimics the construction mechanism, where the invocation of the base class constructors has to be the first statement in the constructors of derived classes.
        This method has visibility protected since it is meant to be invoked only from class CardServiceFactory. If services should be instantiatable from somewhere else, they may redefine it with public visibility, or whatever is appropriate.
        Parameters:
        scheduler - where this service is going to allocate channels
        smartcard - which smartcard has to be supported by this service
        blocking - whether channel allocation is going to be blocking
        Throws:
        CardServiceException - if the service could not be initialized. The object created via the default constructor may not be used if this happens.
        See Also:
        CardServiceFactory