220 lines
7.9 KiB
Java
220 lines
7.9 KiB
Java
/*
|
|
* 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,
|
|
}
|
|
|
|
}
|