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