Back to index...

	/*
	* Copyright (c) 2005, 2011, 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.*;

	import java.security.*;

	import sun.security.jca.*;
	import sun.security.jca.GetInstance.*;

	import sun.security.action.GetPropertyAction;

	/**
	* A factory for CardTerminal objects.
	*
	* It allows an application to
	* <ul>
	* <li>obtain a TerminalFactory by calling
	* one of the static factory methods in this class
	* ({@linkplain #getDefault} or {@linkplain #getInstance getInstance()}).
	* <li>use this TerminalFactory object to access the CardTerminals by
	* calling the {@linkplain #terminals} method.
	* </ul>
	*
	* <p>Each TerminalFactory has a <code>type</code> indicating how it
	* was implemented. It must be specified when the implementation is obtained
	* using a {@linkplain #getInstance getInstance()} method and can be retrieved
	* via the {@linkplain #getType} method.
	*
	* <P>The following standard type names have been defined:
	* <dl>
	* <dt><code>PC/SC</code>
	* <dd>an implementation that calls into the PC/SC Smart Card stack
	* of the host platform.
	* Implementations do not require parameters and accept "null" as argument
	* in the getInstance() calls.
	* <dt><code>None</code>
	* <dd>an implementation that does not supply any CardTerminals. On platforms
	* that do not support other implementations,
	* {@linkplain #getDefaultType} returns <code>None</code> and
	* {@linkplain #getDefault} returns an instance of a <code>None</code>
	* TerminalFactory. Factories of this type cannot be obtained by calling the
	* <code>getInstance()</code> methods.
	* </dl>
	* Additional standard types may be defined in the future.
	*
	* <p><strong>Note:</strong>
	* Provider implementations that accept initialization parameters via the
	* <code>getInstance()</code> methods are strongly
	* encouraged to use a {@linkplain java.util.Properties} object as the
	* representation for String name-value pair based parameters whenever
	* possible. This allows applications to more easily interoperate with
	* multiple providers than if each provider used different provider
	* specific class as parameters.
	*
	* <P>TerminalFactory utilizes an extensible service provider framework.
	* Service providers that wish to add a new implementation should see the
	* {@linkplain TerminalFactorySpi} class for more information.
	*
	* @see CardTerminals
	* @see Provider
	*
	* @since 1.6
	* @author Andreas Sterbenz
	* @author JSR 268 Expert Group
	*/
	public final class TerminalFactory {

	private final static String PROP_NAME =
	"javax.smartcardio.TerminalFactory.DefaultType";

	private final static String defaultType;

	private final static TerminalFactory defaultFactory;

	static {
	// lookup up the user specified type, default to PC/SC
	String type = AccessController.doPrivileged
	(new GetPropertyAction(PROP_NAME, "PC/SC")).trim();
	TerminalFactory factory = null;
	try {
	factory = TerminalFactory.getInstance(type, null);
	} catch (Exception e) {
	// ignore
	}
	if (factory == null) {
	// if that did not work, try the Sun PC/SC factory
	try {
	type = "PC/SC";
	Provider sun = Security.getProvider("SunPCSC");
	if (sun == null) {
	Class<?> clazz = Class.forName("sun.security.smartcardio.SunPCSC");
	sun = (Provider)clazz.newInstance();
	}
	factory = TerminalFactory.getInstance(type, null, sun);
	} catch (Exception e) {
	// ignore
	}
	}
	if (factory == null) {
	type = "None";
	factory = new TerminalFactory
	(NoneFactorySpi.INSTANCE, NoneProvider.INSTANCE, "None");
	}
	defaultType = type;
	defaultFactory = factory;
	}

	private static final class NoneProvider extends Provider {

	private static final long serialVersionUID = 2745808869881593918L;
	final static Provider INSTANCE = new NoneProvider();
	private NoneProvider() {
	super("None", 1.0d, "none");
	}
	}

	private static final class NoneFactorySpi extends TerminalFactorySpi {
	final static TerminalFactorySpi INSTANCE = new NoneFactorySpi();
	private NoneFactorySpi() {
	// empty
	}
	protected CardTerminals engineTerminals() {
	return NoneCardTerminals.INSTANCE;
	}
	}

	private static final class NoneCardTerminals extends CardTerminals {
	final static CardTerminals INSTANCE = new NoneCardTerminals();
	private NoneCardTerminals() {
	// empty
	}
	public List<CardTerminal> list(State state) throws CardException {
	if (state == null) {
	throw new NullPointerException();
	}
	return Collections.emptyList();
	}
	public boolean waitForChange(long timeout) throws CardException {
	throw new IllegalStateException("no terminals");
	}
	}

	private final TerminalFactorySpi spi;

	private final Provider provider;

	private final String type;

	private TerminalFactory(TerminalFactorySpi spi, Provider provider, String type) {
	this.spi = spi;
	this.provider = provider;
	this.type = type;
	}

	/**
	* Get the default TerminalFactory type.
	*
	* <p>It is determined as follows:
	*
	* when this class is initialized, the system property
	* <code>javax.smartcardio.TerminalFactory.DefaultType</code>
	* is examined. If it is set, a TerminalFactory of this type is
	* instantiated by calling the {@linkplain #getInstance
	* getInstance(String,Object)} method passing
	* <code>null</code> as the value for <code>params</code>. If the call
	* succeeds, the type becomes the default type and the factory becomes
	* the {@linkplain #getDefault default} factory.
	*
	* <p>If the system property is not set or the getInstance() call fails
	* for any reason, the system defaults to an implementation specific
	* default type and TerminalFactory.
	*
	* @return the default TerminalFactory type
	*/
	public static String getDefaultType() {
	return defaultType;
	}

	/**
	* Returns the default TerminalFactory instance. See
	* {@linkplain #getDefaultType} for more information.
	*
	* <p>A default TerminalFactory is always available. However, depending
	* on the implementation, it may not offer any terminals.
	*
	* @return the default TerminalFactory
	*/
	public static TerminalFactory getDefault() {
	return defaultFactory;
	}

	/**
	* Returns a TerminalFactory of the specified type that is initialized
	* with the specified parameters.
	*
	* <p> This method traverses the list of registered security Providers,
	* starting with the most preferred Provider.
	* A new TerminalFactory object encapsulating the
	* TerminalFactorySpi implementation from the first
	* Provider that supports the specified type is returned.
	*
	* <p> Note that the list of registered providers may be retrieved via
	* the {@linkplain Security#getProviders() Security.getProviders()} method.
	*
	* <p>The <code>TerminalFactory</code> is initialized with the
	* specified parameters Object. The type of parameters
	* needed may vary between different types of <code>TerminalFactory</code>s.
	*
	* @param type the type of the requested TerminalFactory
	* @param params the parameters to pass to the TerminalFactorySpi
	* implementation, or null if no parameters are needed
	* @return a TerminalFactory of the specified type
	*
	* @throws NullPointerException if type is null
	* @throws NoSuchAlgorithmException if no Provider supports a
	* TerminalFactorySpi of the specified type
	*/
	public static TerminalFactory getInstance(String type, Object params)
	throws NoSuchAlgorithmException {
	Instance instance = GetInstance.getInstance("TerminalFactory",
	TerminalFactorySpi.class, type, params);
	return new TerminalFactory((TerminalFactorySpi)instance.impl,
	instance.provider, type);
	}

	/**
	* Returns a TerminalFactory of the specified type that is initialized
	* with the specified parameters.
	*
	* <p> A new TerminalFactory object encapsulating the
	* TerminalFactorySpi implementation from the specified provider
	* is returned. The specified provider must be registered
	* in the security provider list.
	*
	* <p> Note that the list of registered providers may be retrieved via
	* the {@linkplain Security#getProviders() Security.getProviders()} method.
	*
	* <p>The <code>TerminalFactory</code> is initialized with the
	* specified parameters Object. The type of parameters
	* needed may vary between different types of <code>TerminalFactory</code>s.
	*
	* @param type the type of the requested TerminalFactory
	* @param params the parameters to pass to the TerminalFactorySpi
	* implementation, or null if no parameters are needed
	* @param provider the name of the provider
	* @return a TerminalFactory of the specified type
	*
	* @throws NullPointerException if type is null
	* @throws IllegalArgumentException if provider is null or the empty String
	* @throws NoSuchAlgorithmException if a TerminalFactorySpi implementation
	* of the specified type is not available from the specified provider
	* @throws NoSuchAlgorithmException if no TerminalFactory of the
	* specified type could be found
	* @throws NoSuchProviderException if the specified provider could not
	* be found
	*/
	public static TerminalFactory getInstance(String type, Object params,
	String provider) throws NoSuchAlgorithmException, NoSuchProviderException {
	Instance instance = GetInstance.getInstance("TerminalFactory",
	TerminalFactorySpi.class, type, params, provider);
	return new TerminalFactory((TerminalFactorySpi)instance.impl,
	instance.provider, type);
	}

	/**
	* Returns a TerminalFactory of the specified type that is initialized
	* with the specified parameters.
	*
	* <p> A new TerminalFactory object encapsulating the
	* TerminalFactorySpi implementation from the specified provider object
	* is returned. Note that the specified provider object does not have to be
	* registered in the provider list.
	*
	* <p>The <code>TerminalFactory</code> is initialized with the
	* specified parameters Object. The type of parameters
	* needed may vary between different types of <code>TerminalFactory</code>s.
	*
	* @param type the type of the requested TerminalFactory
	* @param params the parameters to pass to the TerminalFactorySpi
	* implementation, or null if no parameters are needed
	* @param provider the provider
	* @return a TerminalFactory of the specified type
	*
	* @throws NullPointerException if type is null
	* @throws IllegalArgumentException if provider is null
	* @throws NoSuchAlgorithmException if a TerminalFactorySpi implementation
	* of the specified type is not available from the specified Provider
	*/
	public static TerminalFactory getInstance(String type, Object params,
	Provider provider) throws NoSuchAlgorithmException {
	Instance instance = GetInstance.getInstance("TerminalFactory",
	TerminalFactorySpi.class, type, params, provider);
	return new TerminalFactory((TerminalFactorySpi)instance.impl,
	instance.provider, type);
	}

	/**
	* Returns the provider of this TerminalFactory.
	*
	* @return the provider of this TerminalFactory.
	*/
	public Provider getProvider() {
	return provider;
	}

	/**
	* Returns the type of this TerminalFactory. This is the value that was
	* specified in the getInstance() method that returned this object.
	*
	* @return the type of this TerminalFactory
	*/
	public String getType() {
	return type;
	}

	/**
	* Returns a new CardTerminals object encapsulating the terminals
	* supported by this factory.
	* See the class comment of the {@linkplain CardTerminals} class
	* regarding how the returned objects can be shared and reused.
	*
	* @return a new CardTerminals object encapsulating the terminals
	* supported by this factory.
	*/
	public CardTerminals terminals() {
	return spi.engineTerminals();
	}

	/**
	* Returns a string representation of this TerminalFactory.
	*
	* @return a string representation of this TerminalFactory.
	*/
	public String toString() {
	return "TerminalFactory for type " + type + " from provider "
	+ provider.getName();
	}

	}

Back to index...