BeIDCards (Commons eID Client 1.2.0 API)

java.lang.Object
- be.fedict.commons.eid.client.BeIDCards

```
public class BeIDCards
extends Object
```
BeIDCards is a synchronous approach to Belgian Identity Cards and their presence in the user's system, as opposed to the asynchronous, event-driven approach of BeIDCardManager (but BeIDCards uses an underlying BeIDCardManager to achieve it's goals). It's main purpose is to have a very simple way to get a user's BeIDCard instance, abstracting away and delegating issues such as terminal connection, card insertion, and handling multiple eligible cards.
BeIDCards handle user interaction (if any) through an instance of BeIDCardsUI, which can be supplied at construction, or left to the supplied default, which will instantiate a be.fedict.commons.eid.dialogs.DefaultBeIDCardsUI (which needs to be available on the class path)

Author:

Frank Marien

Constructor Summary

Constructors
Constructor and Description
`BeIDCards()` a BeIDCards without logging, using the default BeIDCardsUI
`BeIDCards(BeIDCardsUI ui)` a BeIDCards without logging, using the supplied BeIDCardsUI
`BeIDCards(Logger logger)` a BeIDCards logging to supplied logger, using the default BeIDCardsUI
`BeIDCards(Logger logger, BeIDCardsUI ui)` a BeIDCards logging to logger, using the supplied BeIDCardsUI and locale

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`BeIDCards`	`close()` call close() if you no longer need this BeIDCards instance.
`Set<BeIDCard>`	`getAllBeIDCards()` return Set of all BeID Cards present.
`Locale`	`getLocale()`
`BeIDCard`	`getOneBeIDCard()` return exactly one BeID Card.
`BeIDCard`	`getOneBeIDCard(javax.smartcardio.CardTerminal terminal)` return a BeID Card inserted into a given CardTerminal
`boolean`	`hasBeIDCards()` Return whether any BeID Cards are currently present.
`boolean`	`hasBeIDCards(javax.smartcardio.CardTerminal terminal)` Return whether any BeID Cards are currently present.
`boolean`	`hasCardTerminals()`
`BeIDCards`	`setLocale(Locale newLocale)` Set the Locale to use for subsequent UI operations.
`BeIDCards`	`waitUntilCardRemoved(BeIDCard card)` wait for a particular BeID card to be removed.

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

- Constructor Detail
  - BeIDCards
```
public BeIDCards()
```
    a BeIDCards without logging, using the default BeIDCardsUI
  - BeIDCards
```
public BeIDCards(BeIDCardsUI ui)
```
    a BeIDCards without logging, using the supplied BeIDCardsUI
    
    Parameters:
    
    ui - an instance of be.fedict.commons.eid.client.spi.BeIDCardsUI that will be called upon for any user interaction required to handle other calls. The UI's Locale will be used globally for subsequent UI actions, as if setLocale() was called, except where the Locale is explicity set for individual BeIDCard instances.
  - BeIDCards
```
public BeIDCards(Logger logger)
```
    a BeIDCards logging to supplied logger, using the default BeIDCardsUI
    
    Parameters:
    
    logger - an instance of be.fedict.commons.eid.spi.Logger that will be send all the logs
  - BeIDCards
```
public BeIDCards(Logger logger,
                 BeIDCardsUI ui)
```
    a BeIDCards logging to logger, using the supplied BeIDCardsUI and locale
    
    Parameters:
    
    logger - an instance of be.fedict.commons.eid.spi.Logger that will be send all the logs
    
    ui - an instance of be.fedict.commons.eid.client.spi.BeIDCardsUI that will be called upon for any user interaction required to handle other calls. The UI's Locale will be used globally for subsequent UI actions, as if setLocale() was called, except where the Locale is explicity set for individual BeIDCard instances.
- Method Detail
  - hasBeIDCards
```
public boolean hasBeIDCards()
```
    Return whether any BeID Cards are currently present.
    
    Returns:
    
    true if one or more BeID Cards are inserted in one or more connected CardTerminals, false if zero BeID Cards are present
  - hasBeIDCards
```
public boolean hasBeIDCards(javax.smartcardio.CardTerminal terminal)
```
    Return whether any BeID Cards are currently present.
    
    Parameters:
    
    terminal - if not null, only this terminal will be considered in determining whether beID Cards are present.
    
    Returns:
    
    true if one or more BeID Cards are inserted in one or more connected CardTerminals, false if zero BeID Cards are present
  - getAllBeIDCards
```
public Set<BeIDCard> getAllBeIDCards()
```
    return Set of all BeID Cards present. Will return empty Set if no BeID cards are present at time of call
    
    Returns:
    
    a (possibly empty) set of all BeID Cards inserted at time of call
  - getOneBeIDCard
```
public BeIDCard getOneBeIDCard()
                        throws CancelledException
```
    return exactly one BeID Card. This may block when called when no BeID Cards are present, until at least one BeID card is inserted, at which point this will be returned. If, at time of call, more than one BeID card is present, will request the UI to select between those, and return the selected card. If the UI is called upon to request the user to select between different cards, or to insert one card, and the user declines, CancelledException is thrown.
    
    Returns:
    
    a BeIDCard instance. The only one present, or one chosen out of several by the user
    
    Throws:
    
    CancelledException
  - getOneBeIDCard
```
public BeIDCard getOneBeIDCard(javax.smartcardio.CardTerminal terminal)
                        throws CancelledException
```
    return a BeID Card inserted into a given CardTerminal
    
    Parameters:
    
    terminal - if not null, only BeID Cards in this particular CardTerminal will be considered. May block when called when no BeID Cards are present, until at least one BeID card is inserted, at which point this will be returned. If, at time of call, more than one BeID card is present, will request the UI to select between those, and return the selected card. If the UI is called upon to request the user to select between different cards, or to insert one card, and the user declines, CancelledException is thrown.
    
    Returns:
    
    a BeIDCard instance. The only one present, or one chosen out of several by the user
    
    Throws:
    
    CancelledException
  - waitUntilCardRemoved
```
public BeIDCards waitUntilCardRemoved(BeIDCard card)
```
    wait for a particular BeID card to be removed. Note that this only works with BeID objects that were acquired using either the getOneBeIDCard() or getAllBeIDCards() methods from the same BeIDCards instance. If, at time of call, that particular card is present, the UI is called upon to prompt the user to remove that card.
    
    Parameters:
    
    card -
    
    Returns:
    
    this BeIDCards instance to allow for method chaining
  - hasCardTerminals
```
public boolean hasCardTerminals()
```
  - close
```
public BeIDCards close()
                throws InterruptedException
```
    call close() if you no longer need this BeIDCards instance.
    
    Returns:
    
    this
    
    Throws:
    
    InterruptedException
  - setLocale
```
public BeIDCards setLocale(Locale newLocale)
```
    Set the Locale to use for subsequent UI operations. BeIDCards and BeIDCardManager share the same global Locale, so this will impact all instances of either. BeIDCard instances may have individual, per-instance Locale settings, however.
    
    Parameters:
    
    newLocale - will be used globally for subsequent UI actions, as if setLocale() was called, except where the Locale is explicity set for individual BeIDCard instances.
    
    Returns:
    
    this BeIDCards, to allow method chaining
  - getLocale
```
public Locale getLocale()
```
    Returns:
    
    the currently set Locale

Class BeIDCards

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BeIDCards

BeIDCards

BeIDCards

BeIDCards

Method Detail

hasBeIDCards

hasBeIDCards

getAllBeIDCards

getOneBeIDCard

getOneBeIDCard

waitUntilCardRemoved

hasCardTerminals

close

setLocale

getLocale