Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## opencard.core.service
Class CardService

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

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;
>      }

See Also:
  `CardChannel`, `CardServiceScheduler`, `SmartCard.beginMutex()`

Constructor Summary
`protected` | `CardService()` Creates a new card service, which is not yet initialized.

Method Summary
`protected void` | `allocateCardChannel()` Allocates a card channel iff one is required.
`SmartCard` | `getCard()` Gets the smartcard object associated with this service.
`CardChannel` | `getCardChannel()` Gets the card channel to use for communicating with the smartcard.
`CHVDialog` | `getCHVDialog()` Returns the dialog for CHV input.
`protected void` | `initialize(CardServiceScheduler scheduler, SmartCard smartcard, boolean blocking)` Initializes this service.
`protected void` | `releaseCardChannel()` Releases the allocated card channel.
`void` | `setCardChannel(CardChannel channel)` Sets the channel to use for communicating with the smartcard.
`void` | `setCHVDialog(CHVDialog dialog)` Sets the CHV dialog to be used for getting passwords from the user.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### CardService

    protected CardService()

  Creates a new card service, which is not yet initialized. Before this new service can be used, `initialize` has to be invoked. This two phase creation scheme has been developed to avoid using `java.lang.reflect` to instantiate card services.
  See Also:
    `initialize(opencard.core.service.CardServiceScheduler, opencard.core.service.SmartCard, boolean)`

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
  See Also:
    `allocateCardChannel()`, `releaseCardChannel()`

### 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:
    `the` - CHV dialog to be used

### getCHVDialog

    public final CHVDialog getCHVDialog()

  Returns the dialog for CHV input. The dialog has to be set using `setCHVDialog`.
  Returns:
    the dialog to use to query a password from the user
  See Also:
    `setCHVDialog(opencard.core.service.CHVDialog)`

### 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`

### allocateCardChannel

    protected void allocateCardChannel()
                                throws InvalidCardChannelException

  Allocates a card channel iff one is required. If a channel has been provided by `setCardChannel`, none has to be allocated. `releaseCardChannel` will take care of this and release the channel only if it actually has been allocated here. After calling this method, a card channel will be available and can be obtained via `getCardChannel`.
  Throws:
    InvalidCardChannelException - The controlling `CardServiceScheduler` has quit. The service is non-blocking and the channel is in use.
  See Also:
    `setCardChannel(opencard.core.service.CardChannel)`, `getCardChannel()`, `releaseCardChannel()`, `CardChannel`, `CardServiceScheduler`

### releaseCardChannel

    protected void releaseCardChannel()
                               throws InvalidCardChannelException

  Releases the allocated card channel. If the channel has not been allocated by `allocateCardChannel` but was provided via `setCardChannel`, it will not be released.
  Throws:
    InvalidCardChannelException - The controlling `CardServiceScheduler` has quit.
  See Also:
    `allocateCardChannel()`, `setCardChannel(opencard.core.service.CardChannel)`, `CardChannel`, `CardServiceScheduler`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD