javax.smartcardio

Class TerminalFactory

java.lang.Object

javax.smartcardio.TerminalFactory

public final class TerminalFactory
extends java.lang.Object

A factory for CardTerminal objects. It allows an application to

• obtain a TerminalFactory by calling one of the static factory methods in this class (getDefault() or getInstance()).
• use this TerminalFactory object to access the CardTerminals by calling the terminals() method.

Each TerminalFactory has a type indicating how it was implemented. It must be specified when the implementation is obtained using a getInstance() method and can be retrieved via the getType() method.

The following standard type names have been defined:

PC/SC

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.

None

an implementation that does not supply any CardTerminals. On platforms that do not support other implementations, getDefaultType() returns None and getDefault() returns an instance of a None TerminalFactory. Factories of this type cannot be obtained by calling the getInstance() methods.

Additional standard types may be defined in the future.

Note: Provider implementations that accept initialization parameters via the getInstance() methods are strongly encouraged to use a 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.

TerminalFactory utilizes an extensible service provider framework. Service providers that wish to add a new implementation should see the TerminalFactorySpi class for more information.

Since:

1.6

Author:

Andreas Sterbenz, JSR 268 Expert Group

See Also:

CardTerminals, Provider

Method Summary

Methods

Modifier and Type	Method and Description
static TerminalFactory	getDefault() Returns the default TerminalFactory instance.
static java.lang.String	getDefaultType() Get the default TerminalFactory type.
static TerminalFactory	getInstance(java.lang.String type, java.lang.Object params) Returns a TerminalFactory of the specified type that is initialized with the specified parameters.
static TerminalFactory	getInstance(java.lang.String type, java.lang.Object params, java.security.Provider provider) Returns a TerminalFactory of the specified type that is initialized with the specified parameters.
static TerminalFactory	getInstance(java.lang.String type, java.lang.Object params, java.lang.String provider) Returns a TerminalFactory of the specified type that is initialized with the specified parameters.
java.security.Provider	getProvider() Returns the provider of this TerminalFactory.
java.lang.String	getType() Returns the type of this TerminalFactory.
CardTerminals	terminals() Returns a new CardTerminals object encapsulating the terminals supported by this factory.
java.lang.String	toString() Returns a string representation of this TerminalFactory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getDefaultType

public static java.lang.String getDefaultType()

Get the default TerminalFactory type.

It is determined as follows: when this class is initialized, the system property javax.smartcardio.TerminalFactory.DefaultType is examined. If it is set, a TerminalFactory of this type is instantiated by calling the getInstance(String,Object) method passing null as the value for params. If the call succeeds, the type becomes the default type and the factory becomes the default factory.

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.

Returns:

the default TerminalFactory type

getDefault

public static TerminalFactory getDefault()

Returns the default TerminalFactory instance. See getDefaultType() for more information.

A default TerminalFactory is always available. However, depending on the implementation, it may not offer any terminals.

Returns:

the default TerminalFactory

getInstance

public static TerminalFactory getInstance(java.lang.String type,
                          java.lang.Object params)
                                   throws java.security.NoSuchAlgorithmException

Returns a TerminalFactory of the specified type that is initialized with the specified parameters.

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.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

The TerminalFactory is initialized with the specified parameters Object. The type of parameters needed may vary between different types of TerminalFactorys.

Parameters:

type - the type of the requested TerminalFactory

params - the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed

Returns:

a TerminalFactory of the specified type

Throws:

java.lang.NullPointerException - if type is null

java.security.NoSuchAlgorithmException - if no Provider supports a TerminalFactorySpi of the specified type

getInstance

public static TerminalFactory getInstance(java.lang.String type,
                          java.lang.Object params,
                          java.lang.String provider)
                                   throws java.security.NoSuchAlgorithmException,
                                          java.security.NoSuchProviderException

Returns a TerminalFactory of the specified type that is initialized with the specified parameters.

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.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

The TerminalFactory is initialized with the specified parameters Object. The type of parameters needed may vary between different types of TerminalFactorys.

Parameters:

type - the type of the requested TerminalFactory

params - the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed

provider - the name of the provider

Returns:

a TerminalFactory of the specified type

Throws:

java.lang.NullPointerException - if type is null

java.lang.IllegalArgumentException - if provider is null or the empty String

java.security.NoSuchAlgorithmException - if a TerminalFactorySpi implementation of the specified type is not available from the specified provider

java.security.NoSuchAlgorithmException - if no TerminalFactory of the specified type could be found

java.security.NoSuchProviderException - if the specified provider could not be found

getInstance

public static TerminalFactory getInstance(java.lang.String type,
                          java.lang.Object params,
                          java.security.Provider provider)
                                   throws java.security.NoSuchAlgorithmException

Returns a TerminalFactory of the specified type that is initialized with the specified parameters.

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.

The TerminalFactory is initialized with the specified parameters Object. The type of parameters needed may vary between different types of TerminalFactorys.

Parameters:

type - the type of the requested TerminalFactory

params - the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed

provider - the provider

Returns:

a TerminalFactory of the specified type

Throws:

java.lang.NullPointerException - if type is null

java.lang.IllegalArgumentException - if provider is null

java.security.NoSuchAlgorithmException - if a TerminalFactorySpi implementation of the specified type is not available from the specified Provider

getProvider

public java.security.Provider getProvider()

Returns the provider of this TerminalFactory.

Returns:

the provider of this TerminalFactory.

getType

public java.lang.String getType()

Returns the type of this TerminalFactory. This is the value that was specified in the getInstance() method that returned this object.

Returns:

the type of this TerminalFactory

terminals

public CardTerminals terminals()

Returns a new CardTerminals object encapsulating the terminals supported by this factory. See the class comment of the CardTerminals class regarding how the returned objects can be shared and reused.

Returns:

a new CardTerminals object encapsulating the terminals supported by this factory.

toString

public java.lang.String toString()

Returns a string representation of this TerminalFactory.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this TerminalFactory.