Programming to the Java Card RMI Client-Side API

C H A P T E R 14

Starting the Java Card Runtime Environment

This chapter describes how to use the Java Card RMI client-side API. Support for the Java Card RMI client-side API is optional according to the Java Card specifcations, but it has been implemented in the Classic RI available in the Classic development kit. Note that it has not been implemented in the Connected RI available in the Connected development kit.

A Java Card RMI client application runs on a Card Acceptance Device (CAD) terminal that supports a Java SE or Java ME platform. The client application requires a portable and platform-independent mechanism to access the Java Card RMI server applet executing on the smart card.

The basic client-side framework is implemented in the package com.sun.javacard.javacard.rmiclientlib and com.sun.javacard.javacard.clientlib .

The library is located in the file lib/tools.jar .

The reference implementation of the Java Card RMI client-side API is based on APDU I/O for its card access mechanisms. For more information on APDU I/O, see Chapter 15.

Remote Stub Object

The Java Card RMI API supports two formats for passing remote references. The format for remote references containing the class name requires stubs for remote objects available to the client application.

The standard Java RMIC compiler tool can be used as the stub compilation tool to produce stub classes required for the client application. To produce these stub classes, the RMIC compiler tool must have access to all the non-abstract classes defined in the applet package which directly or indirectly implement remote interfaces. In addition, it needs to access the .class files of all the remote interfaces implemented by them.

If you want the stub class to be Java Card RMI-specific when it is instantiated on the client, it must be customized with a Java Card platform-specific implementation of the CardObjectFactory interface.

The standard Java RMIC compiler is used to generate the remote stub objects. JCRemoteRefImpl, a Java Card platform-specific implementation of the java.rmi.server.RemoteRef interface, allows these stub objects to work with the Java Card RMI API. The stub object delegates all method invocations to its configured RemoteRef instance.

The com.sun.javacard.rmiclientlib.JCRemoteRefImpl class is an example of a RemoteRef object customized for the Java Card platform.

For examples of how to use these interfaces and classes, see Application Programming Notes, Java Card Platform, Version 3.0.1, Classic Edition .

Note - Since the remote object is configured as a Java Card platform-specific object with a local connection to the smart card via the CardAccessor object, the object is inherently not portable. A bridge class must be used if it is to be accessed from outside of this client application.

Note - Some versions of the RMIC do not treat Throwable as a superclass of RemoteException . The workaround is to declare remote methods to throw Exception instead.

Java Card RMI Client-Side API

The two packages in the Java Card RMI client-side reference implementation demonstrate remote stub customization using the RMIC compiler generated stubs and card access for Java Card applets.

The package com.sun.javacard.javacard.rmiclientlib implements Java Card RMI-specific functionality.

The package com.sun.javacard.javacard.clientlib implements basic functionality to exchange APDUs with a smart card or a smart card simulator. This implementation of clientlib requires that the ApduIO library is included in the CLASSPATH.

In the release bundles, the Javadoc tool files for this API are located at:


JC_CLASSIC_HOME\docs\rmijavadocs

Package `rmiclientlib`

This package includes several classes.

class JCRMIConnect -- The main class of the RMI framework that provides methods to select a card applet and to get an initial reference.
class JCCardObjectFactory -- An implementation of the CardObjectFactory that processes the data returned from the card in the format defined in the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Classic Edition . Any object references must contain class names.
class JCCardProxyFactory -- The JCCardProxyFactory class is similar to JCCardObjectFactory , but processes references containing lists of names. JCCardProxyFactory uses the JDK 1.4.+ proxy mechanism to generate proxies dynamically.
class JCRemoteRefImpl -- An implementation of interface java.rmi.server.RemoteRef . These remote references can work with stubs generated by the RMIC compiler with the -v1.2 option.

The main method is:
public Object invoke(Remote remote, Method method, Object[] params, long unused) throws IOException, RemoteException, Exception

This method prepares the outgoing APDU, passes it to CardAccessor , and then uses CardObjectFactory to parse the returned APDU and instantiate the returned object or throw an exception.

Package `clientlib`

This package includes an interface and a class.

interface CardAccessor -- An interface defining methods to exchange APDUs with a card and to close connection to a card.
class ApduIOCardAccessor -- A simple implementation of the CardAccessor interface that passes the APDUs to a card or a card simulator using the ApduIO library. This class takes parameters to start the ApduIO from the file jcclient.properties , which must be included in CLASSPATH.

Remote Stub Object

Java Card RMI Client-Side API

Package rmiclientlib

Package clientlib

Package `rmiclientlib`

Package `clientlib`