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 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.

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

Modifier and Type	Class and Description
private static class	TerminalFactory.NoneCardTerminals
private static class	TerminalFactory.NoneFactorySpi
private static class	TerminalFactory.NoneProvider

Modifier and Type	Field and Description
private static final TerminalFactory	defaultFactory
private static final String	defaultType
private static final String	PROP_NAME
private final Provider	provider
private final TerminalFactorySpi	spi
private final String	type

Access	Constructor and Description
private	TerminalFactory(TerminalFactorySpi spi, Provider provider, String type)

Method Summary

Modifier and Type	Method and Description
public static TerminalFactory	Returns: the default TerminalFactory getDefault() Returns the default TerminalFactory instance.
public static String	Returns: the default TerminalFactory type getDefaultType() Get the default TerminalFactory type.
public static TerminalFactory	Returns: a TerminalFactory of the specified type getInstance(String the type of the requested TerminalFactory type, Object the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed params) Returns a TerminalFactory of the specified type that is initialized with the specified parameters.
public static TerminalFactory	Returns: a TerminalFactory of the specified type getInstance(String the type of the requested TerminalFactory type, Object the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed params, String the name of the provider provider) Returns a TerminalFactory of the specified type that is initialized with the specified parameters.
public static TerminalFactory	Returns: a TerminalFactory of the specified type getInstance(String the type of the requested TerminalFactory type, Object the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed params, Provider the provider provider) Returns a TerminalFactory of the specified type that is initialized with the specified parameters.
public Provider	Returns: the provider of this TerminalFactory. getProvider() Returns the provider of this TerminalFactory.
public String	Returns: the type of this TerminalFactory getType() Returns the type of this TerminalFactory.
public CardTerminals	Returns: a new CardTerminals object encapsulating the terminals supported by this factory. terminals() Returns a new CardTerminals object encapsulating the terminals supported by this factory.
public String	Returns: a string representation of this TerminalFactory. toString() Overrides java.lang.Object.toString. Returns a string representation of this TerminalFactory.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

defaultFactory	back to summary
private static final TerminalFactory defaultFactory

defaultType	back to summary
private static final String defaultType

PROP_NAME	back to summary
private static final String PROP_NAME

provider	back to summary
private final Provider provider

spi	back to summary
private final TerminalFactorySpi spi

type	back to summary
private final String type

Constructor Detail

TerminalFactory	back to summary
private TerminalFactory(TerminalFactorySpi spi, Provider provider, String type)

Method Detail

getDefault	back to summary
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:TerminalFactory the default TerminalFactory

getDefault

back to summary

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:TerminalFactory: the default TerminalFactory

getDefaultType back to summary

getDefaultType	back to summary
public static 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:String the default TerminalFactory type

public static 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:String: the default TerminalFactory type

getInstance back to summary

getInstance	back to summary
public static TerminalFactory getInstance(String type, Object params) throws 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 `TerminalFactory`s. Implementation Note The JDK Reference Implementation additionally uses the `jdk.security.provider.preferred` `Security` property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by `Security.getProviders()`. Parameters type:String the type of the requested TerminalFactory params:Object the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed Returns:TerminalFactory a TerminalFactory of the specified type Exceptions NoSuchAlgorithmException: if no Provider supports a TerminalFactorySpi of the specified type NullPointerException: if type is null

public static TerminalFactory getInstance(String type, Object params) throws 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.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by Security.getProviders().

Parameters

type:String: the type of the requested TerminalFactory
params:Object: the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed

Returns:TerminalFactory

a TerminalFactory of the specified type

Exceptions

NoSuchAlgorithmException:: if no Provider supports a TerminalFactorySpi of the specified type
NullPointerException:: if type is null

getInstance back to summary

getInstance	back to summary
public static TerminalFactory getInstance(String type, Object params, String provider) throws NoSuchAlgorithmException, 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 `TerminalFactory`s. Parameters type:String the type of the requested TerminalFactory params:Object the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed provider:String the name of the provider Returns:TerminalFactory a TerminalFactory of the specified type Exceptions NoSuchAlgorithmException: if a TerminalFactorySpi implementation of the specified type is not available from the specified provider if no TerminalFactory of the specified type could be found NoSuchProviderException: if the specified provider could not be found NullPointerException: if type is null IllegalArgumentException: if provider is null or the empty String

public static TerminalFactory getInstance(String type, Object params, String provider) throws NoSuchAlgorithmException, 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:String: the type of the requested TerminalFactory
params:Object: the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed
provider:String: the name of the provider

Returns:TerminalFactory

a TerminalFactory of the specified type

Exceptions

NoSuchAlgorithmException:

if a TerminalFactorySpi implementation of the specified type is not available from the specified provider
if no TerminalFactory of the specified type could be found

NoSuchProviderException:

if the specified provider could not be found

NullPointerException:

if type is null

IllegalArgumentException:

if provider is null or the empty String

getInstance back to summary

getInstance	back to summary
public static TerminalFactory getInstance(String type, Object params, Provider provider) throws 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 `TerminalFactory`s. Parameters type:String the type of the requested TerminalFactory params:Object the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed provider:Provider the provider Returns:TerminalFactory a TerminalFactory of the specified type Exceptions NoSuchAlgorithmException: if a TerminalFactorySpi implementation of the specified type is not available from the specified Provider NullPointerException: if type is null IllegalArgumentException: if provider is null

public static TerminalFactory getInstance(String type, Object params, Provider provider) throws 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:String: the type of the requested TerminalFactory
params:Object: the parameters to pass to the TerminalFactorySpi implementation, or null if no parameters are needed
provider:Provider: the provider

Returns:TerminalFactory

a TerminalFactory of the specified type

Exceptions

NoSuchAlgorithmException:: if a TerminalFactorySpi implementation of the specified type is not available from the specified Provider
NullPointerException:: if type is null
IllegalArgumentException:: if provider is null

getProvider	back to summary
public Provider getProvider() Returns the provider of this TerminalFactory. Returns:Provider the provider of this TerminalFactory.

getProvider

back to summary

public Provider getProvider()

Returns the provider of this TerminalFactory.

Returns:Provider: the provider of this TerminalFactory.

getType	back to summary
public String getType() Returns the type of this TerminalFactory. This is the value that was specified in the getInstance() method that returned this object. Returns:String the type of this TerminalFactory

getType

back to summary

public String getType()

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

Returns:String: the type of this TerminalFactory

terminals	back to summary
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:CardTerminals a new CardTerminals object encapsulating the terminals supported by this factory.

terminals

back to summary

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:CardTerminals: a new CardTerminals object encapsulating the terminals supported by this factory.

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Returns a string representation of this TerminalFactory. Returns:String a string representation of this TerminalFactory.

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Returns a string representation of this TerminalFactory.

Returns:String: a string representation of this TerminalFactory.

javax.smartcardio back to summary

private final Class TerminalFactory.NoneCardTerminals

Class Inheritance

extends CardTerminals

java.lang.Object
javax.smartcardio.CardTerminals
javax.smartcardio.TerminalFactory.NoneCardTerminals

Field Summary

Modifier and Type	Field and Description
pack-priv static final CardTerminals	INSTANCE

Constructor Summary

Access	Constructor and Description
private	NoneCardTerminals()

Method Summary

Modifier and Type	Method and Description
public List<CardTerminal>	list(CardTerminals.State state) Implements abstract javax.smartcardio.CardTerminals.list. Returns an unmodifiable list of all terminals matching the specified state.
public boolean	waitForChange(long timeout) Implements abstract javax.smartcardio.CardTerminals.waitForChange. Waits for card insertion or removal in any of the terminals of this object or until the timeout expires.

Inherited from javax.smartcardio.CardTerminals:: getTerminal list waitForChange

Field Detail

INSTANCE	back to summary
pack-priv static final CardTerminals INSTANCE

Constructor Detail

NoneCardTerminals	back to summary
private NoneCardTerminals()

Method Detail

list back to summary

list	back to summary
public List<CardTerminal> list(CardTerminals.State state) throws CardException Implements abstract javax.smartcardio.CardTerminals.list. Doc from javax.smartcardio.CardTerminals.list. Returns an unmodifiable list of all terminals matching the specified state. If state is `State.ALL`, this method returns all CardTerminals encapsulated by this object. If state is `State.CARD_PRESENT` or `State.CARD_ABSENT`, it returns all CardTerminals where a card is currently present or absent, respectively. If state is `State.CARD_INSERTION` or `State.CARD_REMOVAL`, it returns all CardTerminals for which an insertion (or removal, respectively) was detected during the last call to waitForChange. If `waitForChange()` has not been called on this object, `CARD_INSERTION` is equivalent to `CARD_PRESENT` and `CARD_REMOVAL` is equivalent to `CARD_ABSENT`. For an example of the use of `CARD_INSERTION`, see `waitForChange`. Exceptions CardException: if the card operation failed

public List<CardTerminal> list(CardTerminals.State state) throws CardException

Implements abstract javax.smartcardio.CardTerminals.list.

Doc from javax.smartcardio.CardTerminals.list.

Returns an unmodifiable list of all terminals matching the specified state.

If state is State.ALL, this method returns all CardTerminals encapsulated by this object. If state is State.CARD_PRESENT or State.CARD_ABSENT, it returns all CardTerminals where a card is currently present or absent, respectively.

If state is State.CARD_INSERTION or State.CARD_REMOVAL, it returns all CardTerminals for which an insertion (or removal, respectively) was detected during the last call to waitForChange. If waitForChange() has not been called on this object, CARD_INSERTION is equivalent to CARD_PRESENT and CARD_REMOVAL is equivalent to CARD_ABSENT. For an example of the use of CARD_INSERTION, see waitForChange.

Exceptions

CardException:: if the card operation failed

waitForChange back to summary

waitForChange	back to summary
public boolean waitForChange(long timeout) throws CardException Implements abstract javax.smartcardio.CardTerminals.waitForChange. Doc from javax.smartcardio.CardTerminals.waitForChange. Waits for card insertion or removal in any of the terminals of this object or until the timeout expires. This method examines each CardTerminal of this object. If a card was inserted into or removed from a CardTerminal since the previous call to `waitForChange()`, it returns immediately. Otherwise, or if this is the first call to `waitForChange()` on this object, it blocks until a card is inserted into or removed from a CardTerminal. If `timeout` is greater than 0, the method returns after `timeout` milliseconds even if there is no change in state. In that case, this method returns `false`; otherwise it returns `true`. This method is often used in a loop in combination with `list(State.CARD_INSERTION)`, for example: 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(); } Exceptions CardException: if the card operation failed

public boolean waitForChange(long timeout) throws CardException

Implements abstract javax.smartcardio.CardTerminals.waitForChange.

Doc from javax.smartcardio.CardTerminals.waitForChange.

Waits for card insertion or removal in any of the terminals of this object or until the timeout expires.

This method examines each CardTerminal of this object. If a card was inserted into or removed from a CardTerminal since the previous call to waitForChange(), it returns immediately. Otherwise, or if this is the first call to waitForChange() on this object, it blocks until a card is inserted into or removed from a CardTerminal.

If timeout is greater than 0, the method returns after timeout milliseconds even if there is no change in state. In that case, this method returns false; otherwise it returns true.

This method is often used in a loop in combination with list(State.CARD_INSERTION), for example:

 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();
 }

Exceptions

CardException:: if the card operation failed

public final Class TerminalFactory

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class TerminalFactory.NoneCardTerminals

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class TerminalFactory.NoneFactorySpi

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class TerminalFactory.NoneProvider

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Modifier and Type	Field and Description
pack-priv static final Provider	INSTANCE
private static final long	serialVersionUID Hides java.security.Provider.serialVersionUID.