/*
* Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.smartcardio;
import java.util.*;
/**
* The set of terminals supported by a TerminalFactory.
* This class allows applications to enumerate the available CardTerminals,
* obtain a specific CardTerminal, or wait for the insertion or removal of
* cards.
*
* <p>This class is multi-threading safe and can be used by multiple
* threads concurrently. However, this object keeps track of the card
* presence state of each of its terminals. Multiple objects should be used
* if independent calls to {@linkplain #waitForChange} are required.
*
* <p>Applications can obtain instances of this class by calling
* {@linkplain TerminalFactory#terminals}.
*
* @see TerminalFactory
* @see CardTerminal
*
* @since 1.6
* @author Andreas Sterbenz
* @author JSR 268 Expert Group
*/
public abstract class CardTerminals {
/**
* Constructs a new CardTerminals object.
*
* <p>This constructor is called by subclasses only. Application should
* call {@linkplain TerminalFactory#terminals}
* to obtain a CardTerminals object.
*/
protected CardTerminals() {
// empty
}
/**
* Returns an unmodifiable list of all available terminals.
*
* @return an unmodifiable list of all available terminals.
*
* @throws CardException if the card operation failed
*/
public List<CardTerminal> list() throws CardException {
return list(State.ALL);
}
/**
* Returns an unmodifiable list of all terminals matching the specified
* state.
*
* <p>If state is {@link State#ALL State.ALL}, this method returns
* all CardTerminals encapsulated by this object.
* If state is {@link State#CARD_PRESENT State.CARD_PRESENT} or
* {@link State#CARD_ABSENT State.CARD_ABSENT}, it returns all
* CardTerminals where a card is currently present or absent, respectively.
*
* <p>If state is {@link State#CARD_INSERTION State.CARD_INSERTION} or
* {@link State#CARD_REMOVAL State.CARD_REMOVAL}, it returns all
* CardTerminals for which an insertion (or removal, respectively)
* was detected during the last call to {@linkplain #waitForChange}.
* If <code>waitForChange()</code> has not been called on this object,
* <code>CARD_INSERTION</code> is equivalent to <code>CARD_PRESENT</code>
* and <code>CARD_REMOVAL</code> is equivalent to <code>CARD_ABSENT</code>.
* For an example of the use of <code>CARD_INSERTION</code>,
* see {@link #waitForChange}.
*
* @param state the State
* @return an unmodifiable list of all terminals matching the specified
* attribute.
*
* @throws NullPointerException if attr is null
* @throws CardException if the card operation failed
*/
public abstract List<CardTerminal> list(State state) throws CardException;
/**
* Returns the terminal with the specified name or null if no such
* terminal exists.
*
* @return the terminal with the specified name or null if no such
* terminal exists.
*
* @throws NullPointerException if name is null
*/
public CardTerminal getTerminal(String name) {
if (name == null) {
throw new NullPointerException();
}
try {
for (CardTerminal terminal : list()) {
if (terminal.getName().equals(name)) {
return terminal;
}
}
return null;
} catch (CardException e) {
return null;
}
}
/**
* Waits for card insertion or removal in any of the terminals of this
* object.
*
* <p>This call is equivalent to calling
* {@linkplain #waitForChange(long) waitForChange(0)}.
*
* @throws IllegalStateException if this <code>CardTerminals</code>
* object does not contain any terminals
* @throws CardException if the card operation failed
*/
public void waitForChange() throws CardException {
waitForChange(0);
}
/**
* Waits for card insertion or removal in any of the terminals of this
* object or until the timeout expires.
*
* <p>This method examines each CardTerminal of this object.
* If a card was inserted into or removed from a CardTerminal since the
* previous call to <code>waitForChange()</code>, it returns
* immediately.
* Otherwise, or if this is the first call to <code>waitForChange()</code>
* on this object, it blocks until a card is inserted into or removed from
* a CardTerminal.
*
* <p>If <code>timeout</code> is greater than 0, the method returns after
* <code>timeout</code> milliseconds even if there is no change in state.
* In that case, this method returns <code>false</code>; otherwise it
* returns <code>true</code>.
*
* <p>This method is often used in a loop in combination with
* {@link #list(CardTerminals.State) list(State.CARD_INSERTION)},
* for example:
* <pre>
* TerminalFactory factory = ...;
* CardTerminals terminals = factory.terminals();
* while (true) {
* for (CardTerminal terminal : terminals.list(CARD_INSERTION)) {
* // examine Card in terminal, return if it matches
* }
* terminals.waitForChange();
* }</pre>
*
* @param timeout if positive, block for up to <code>timeout</code>
* milliseconds; if zero, block indefinitely; must not be negative
* @return false if the method returns due to an expired timeout,
* true otherwise.
*
* @throws IllegalStateException if this <code>CardTerminals</code>
* object does not contain any terminals
* @throws IllegalArgumentException if timeout is negative
* @throws CardException if the card operation failed
*/
public abstract boolean waitForChange(long timeout) throws CardException;
/**
* Enumeration of attributes of a CardTerminal.
* It is used as a parameter to the {@linkplain CardTerminals#list} method.
*
* @since 1.6
*/
public static enum State {
/**
* All CardTerminals.
*/
ALL,
/**
* CardTerminals in which a card is present.
*/
CARD_PRESENT,
/**
* CardTerminals in which a card is not present.
*/
CARD_ABSENT,
/**
* CardTerminals for which a card insertion was detected during the
* latest call to {@linkplain State#waitForChange waitForChange()}
* call.
*/
CARD_INSERTION,
/**
* CardTerminals for which a card removal was detected during the
* latest call to {@linkplain State#waitForChange waitForChange()}
* call.
*/
CARD_REMOVAL,
}
}