javax.smartcardio

## Class CardTerminal

- java.lang.Object
- - javax.smartcardio.CardTerminal

- Direct Known Subclasses:
    AbCircleCardTerminalUSB

      public abstract class CardTerminal
      extends java.lang.Object

  A Smart Card terminal, sometimes referred to as a Smart Card Reader. A CardTerminal object can be obtained by calling CardTerminals.list() or CardTerminals.getTerminal().

  Note that physical card readers with slots for multiple cards are represented by one `CardTerminal` object per such slot.

  Since:
    1.6
  See Also:
    `CardTerminals`, `TerminalFactory`

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `CardTerminal()` Constructs a new CardTerminal object.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Card` | `connect(java.lang.String protocol)` Establishes a connection to the card.
    `abstract java.lang.String` | `getName()` Returns the unique name of this terminal.
    `abstract boolean` | `isCardPresent()` Returns whether a card is present in this terminal.
    `abstract boolean` | `waitForCardAbsent(long timeout)` Waits until a card is absent in this terminal or the timeout expires.
    `abstract boolean` | `waitForCardPresent(long timeout)` Waits until a card is present in this terminal or the timeout expires.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CardTerminal

          protected CardTerminal()

      Constructs a new CardTerminal object.

      This constructor is called by subclasses only. Application should call list() or getTerminal() to obtain a CardTerminal object.

  - ### Method Detail

    - #### getName

          public abstract java.lang.String getName()

      Returns the unique name of this terminal.
      Returns:
        the unique name of this terminal.

    - #### connect

          public abstract Card connect(java.lang.String protocol)
                                throws CardException

      Establishes a connection to the card. If a connection has previously established using the specified protocol, this method returns the same Card object as the previous call.
      Parameters:
        `protocol` - the protocol to use ("T=0", "T=1", or "T=CL"), or "*" to connect using any available protocol.
      Throws:
        `java.lang.NullPointerException` - if protocol is null
        `java.lang.IllegalArgumentException` - if protocol is an invalid protocol specification
        `CardNotPresentException` - if no card is present in this terminal
        `CardException` - if a connection could not be established using the specified protocol or if a connection has previously been established using a different protocol
        `java.lang.SecurityException` - if a SecurityManager exists and the caller does not have the required permission

    - #### isCardPresent

          public abstract boolean isCardPresent()
                                         throws CardException

      Returns whether a card is present in this terminal.
      Returns:
        whether a card is present in this terminal.
      Throws:
        `CardException` - if the status could not be determined

    - #### waitForCardPresent

          public abstract boolean waitForCardPresent(long timeout)
                                              throws CardException

      Waits until a card is present in this terminal or the timeout expires. If the method returns due to an expired timeout, it returns false. Otherwise it return true.

      If a card is present in this terminal when this method is called, it returns immediately.

      Parameters:
        `timeout` - if positive, block for up to `timeout` milliseconds; if zero, block indefinitely; must not be negative
      Returns:
        false if the method returns due to an expired timeout, true otherwise.
      Throws:
        `java.lang.IllegalArgumentException` - if timeout is negative
        `CardException` - if the operation failed

    - #### waitForCardAbsent

          public abstract boolean waitForCardAbsent(long timeout)
                                             throws CardException

      Waits until a card is absent in this terminal or the timeout expires. If the method returns due to an expired timeout, it returns false. Otherwise it return true.

      If no card is present in this terminal when this method is called, it returns immediately.

      Parameters:
        `timeout` - if positive, block for up to `timeout` milliseconds; if zero, block indefinitely; must not be negative
      Returns:
        false if the method returns due to an expired timeout, true otherwise.
      Throws:
        `java.lang.IllegalArgumentException` - if timeout is negative
        `CardException` - if the operation failed