Back to index...

	/*
	* 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,
	}

	}

Back to index...