com.licel.jcardsim.framework

Class AppletProxy

java.lang.Object

com.licel.jcardsim.framework.AppletProxy

public class AppletProxy
extends Object

ProxyClass for AppletProxy

See Also:

Applet

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AppletProxy() Only this class's install() method should create the applet object.

Method Summary

Modifier and Type	Method and Description
void	deselect() Called by the Java Card runtime environment to inform that this currently selected applet is being deselected on this logical channel and no applet from the same package is still active on any other logical channel.
javacard.framework.Shareable	getShareableInterfaceObject(javacard.framework.AID clientAID, byte parameter) Called by the Java Card runtime environment to obtain a shareable interface object from this server applet, on behalf of a request from a client applet.
static void	install(byte[] bArray, short bOffset, byte bLength) To create an instance of the Applet subclass, the Java Card runtime environment will call this static method first.
protected void	register() This method is used by the applet to register this applet instance with the Java Card runtime environment and to assign the Java Card platform name of the applet as its instance AID bytes.
protected void	register(byte[] bArray, short bOffset, byte bLength) This method is used by the applet to register this applet instance with the Java Card runtime environment and assign the specified AID bytes as its instance AID bytes.
boolean	select() Called by the Java Card runtime environment to inform this applet that it has been selected when no applet from the same package is active on any other logical channel.
protected boolean	selectingApplet() This method is used by the applet process() method to distinguish the SELECT APDU command which selected this applet, from all other other SELECT APDU commands which may relate to file or internal applet state selection.

Methods inherited from class java.lang.Object

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

Constructor Detail

AppletProxy

protected AppletProxy()

Only this class's install() method should create the applet object.

Method Detail

install

public static void install(byte[] bArray,
                           short bOffset,
                           byte bLength)
                    throws javacard.framework.ISOException

To create an instance of the Applet subclass, the Java Card runtime environment will call this static method first.

The applet should perform any necessary initializations and must call one of the register() methods. Only one Applet instance can be successfully registered from within this install. The installation is considered successful when the call to register() completes without an exception. The installation is deemed unsuccessful if the install method does not call a register() method, or if an exception is thrown from within the install method prior to the call to a register() method, or if every call to the register() method results in an exception. If the installation is unsuccessful, the Java Card runtime environment must perform all the necessary clean up when it receives control. Successful installation makes the applet instance capable of being selected via a SELECT APDU command.

Installation parameters are supplied in the byte array parameter and must be in a format using length-value (LV) pairs as defined below:

 bArray[0] = length(Li) of instance AID, bArray[1..Li] = instance AID bytes,
 bArray[Li+1]= length(Lc) of control info, bArray[Li+2..Li+Lc+1] = control info,
 bArray[Li+Lc+2] = length(La) of applet data, bArray[Li+Lc+2..Li+Lc+La+1] = applet data
 

In the above format, any of the lengths: Li, Lc or La may be zero. The control information is implementation dependent.

The bArray object is a global array. If the applet desires to preserve any of this data, it should copy the data into its own object.

bArray is zeroed by the Java Card runtime environment after the return from the install() method.

References to the bArray object cannot be stored in class variables or instance variables or array components. See Runtime Environment Specification for the Java Card Platform, section 6.2.2 for details.

The implementation of this method provided by Applet class throws an ISOException with reason code = ISO7816.SW_FUNC_NOT_SUPPORTED.

Note:

• Exceptions thrown by this method after successful installation are caught by the Java Card runtime environment and processed by the Installer.

Parameters:

bArray - the array containing installation parameters

bOffset - the starting offset in bArray

bLength - the length in bytes of the parameter data in bArray The maximum value of bLength is 127.

Throws:

javacard.framework.ISOException - if the install method failed

select

public boolean select()

Called by the Java Card runtime environment to inform this applet that it has been selected when no applet from the same package is active on any other logical channel.

It is called when a SELECT APDU command or MANAGE CHANNEL OPEN APDU command is received and before the applet is selected. SELECT APDU commands use instance AID bytes for applet selection. See Runtime Environment Specification for the Java Card Platform, section 4.5 for details.

A subclass of Applet should override this method if it should perform any initialization that may be required to process APDU commands that may follow. This method returns a boolean to indicate that it is ready to accept incoming APDU commands via its process() method. If this method returns false, it indicates to the Java Card runtime environment that this Applet declines to be selected.

Note:

• The javacard.framework.MultiSelectable.select() method is not called if this method is invoked.

The implementation of this method provided by Applet class returns true.

Returns:

true to indicate success, false otherwise

deselect

public void deselect()

Called by the Java Card runtime environment to inform that this currently selected applet is being deselected on this logical channel and no applet from the same package is still active on any other logical channel. After deselection, this logical channel will be closed or another applet (or the same applet) will be selected on this logical channel. It is called when a SELECT APDU command or a MANAGE CHANNEL CLOSE APDU command is received by the Java Card runtime environment. This method is invoked prior to another applet's or this very applet's select() method being invoked.

A subclass of Applet should override this method if it has any cleanup or bookkeeping work to be performed before another applet is selected.

The default implementation of this method provided by Applet class does nothing.

Notes:

• The javacard.framework.MultiSelectable.deselect() method is not called if this method is invoked.
• Unchecked exceptions thrown by this method are caught by the Java Card runtime environment but the applet is deselected.
• Transient objects of JCSystem.CLEAR_ON_DESELECT clear event type are cleared to their default value by the Java Card runtime environment after this method.
• This method is NOT called on reset or power loss.

getShareableInterfaceObject

public javacard.framework.Shareable getShareableInterfaceObject(javacard.framework.AID clientAID,
                                                                byte parameter)

Called by the Java Card runtime environment to obtain a shareable interface object from this server applet, on behalf of a request from a client applet. This method executes in the applet context of this applet instance. The client applet initiated this request by calling the JCSystem.getAppletShareableInterfaceObject() method. See Runtime Environment Specification for the Java Card Platform, section 6.2.4 for details.

Note:

• The clientAID parameter is a Java Card runtime environment-owned AID instance. Java Card runtime environment-owned instances of AID are permanent Java Card runtime environment Entry Point Objects and can be accessed from any applet context. References to these permanent objects can be stored and re-used.

Parameters:

clientAID - the AID object of the client applet

parameter - optional parameter byte. The parameter byte may be used by the client to specify which shareable interface object is being requested.

Returns:

the shareable interface object or null

register

protected final void register()
                       throws javacard.framework.SystemException

This method is used by the applet to register this applet instance with the Java Card runtime environment and to assign the Java Card platform name of the applet as its instance AID bytes. One of the register() methods must be called from within install() to be registered with the Java Card runtime environment. See Runtime Environment Specification for the Java Card Platform, section 3.1 for details.

Note:

• The phrase "Java Card platform name of the applet" is a reference to the AID[AID_length] item in the applets[] item of the applet_component, as documented in Section 6.5 Applet Component in the Virtual Machine Specification for the Java Card Platform.

Throws:

javacard.framework.SystemException - with the following reason codes:

• SystemException.ILLEGAL_AID if the Applet subclass AID bytes are in use or if the applet instance has previously successfully registered with the Java Card runtime environment via one of the register() methods or if a Java Card runtime environment initiated install() method execution is not in progress.

register

protected final void register(byte[] bArray,
                              short bOffset,
                              byte bLength)
                       throws javacard.framework.SystemException

This method is used by the applet to register this applet instance with the Java Card runtime environment and assign the specified AID bytes as its instance AID bytes. One of the register() methods must be called from within install() to be registered with the Java Card runtime environment. See Runtime Environment Specification for the Java Card Platform, section 3.1 for details.

Note:

• The implementation may require that the instance AID bytes specified are the same as that supplied in the install parameter data. An ILLEGAL_AID exception may be thrown otherwise.

Parameters:

bArray - the byte array containing the AID bytes

bOffset - the start of AID bytes in bArray

bLength - the length of the AID bytes in bArray

Throws:

javacard.framework.SystemException - with the following reason code:

• SystemException.ILLEGAL_VALUE if the bLength parameter is less than 5 or greater than 16.
• SystemException.ILLEGAL_AID if the specified instance AID bytes are in use or if the applet instance has previously successfully registered with the Java Card runtime environment via one of the register() methods or if a Java Card runtime environment-initiated install() method execution is not in progress.

selectingApplet

protected final boolean selectingApplet()

This method is used by the applet process() method to distinguish the SELECT APDU command which selected this applet, from all other other SELECT APDU commands which may relate to file or internal applet state selection.

Returns:

true if this applet is being selected