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

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 `CardServiceRegistry`by 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)`

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