javacard.framework
Class Applet

java.lang.Object
  javacard.framework.Applet

public abstract class Applet

extends Object

This abstract class defines an Java Card technology-based applet.

The Applet class must be extended by any applet that is intended to be loaded onto, installed into and executed on a Java Card technology-compliant smart card.

Example usage of Applet

 
  public class MyApplet extends javacard.framework.Applet{
  static byte someByteArray[];
 
  public static void install( byte[] bArray, short bOffset, byte bLength  ) throws ISOException {
    // make all my allocations here, so I do not run
    // out of memory later
    MyApplet theApplet = new MyApplet();
 
    // check incoming parameter data
    byte iLen = bArray[bOffset]; // aid length
    bOffset = (short) (bOffset+iLen+1);
    byte cLen = bArray[bOffset]; // info length
    bOffset = (short) (bOffset+cLen+1);
    byte aLen = bArray[bOffset]; // applet data length
    // read first applet data byte
    byte bLen = bArray[(short)(bOffset+1)];
    if ( bLen!=0 ) { someByteArray = new byte[bLen]; theApplet.register(); return; }
    else ISOException.throwIt(ISO7816.SW_FUNC_NOT_SUPPORTED);
    }
 
  public boolean select(){
    // selection initialization
    someByteArray[17] = 42; // set selection state
    return true;
    }
 
  public void process(APDU apdu) throws ISOException{
   byte[] buffer = apdu.getBuffer();
   // .. process the incoming data and reply
   if ( buffer[ISO7816.OFFSET_CLA] == (byte)0 ) {
      switch ( buffer[ISO7816.OFFSET_INS] ) {
          case ISO.INS_SELECT:
              ...
              // send response data to select command
              short Le =  apdu.setOutgoing();
              // assume data containing response bytes in replyData[] array.
              if ( Le < ..) ISOException.throwIt( ISO7816.SW_WRONG_LENGTH);
              apdu.setOutgoingLength( (short)replyData.length );
              apdu.sendBytesLong(replyData, (short) 0, (short)replyData.length);
              break;
          case ...
          }
       }
    }
 
  }
  
 

See Also:

SystemException

Constructor Summary

protected

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

Method Summary

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.
Shareable	getShareableInterfaceObject(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.
abstract void	process(APDU apdu) Called by the Java Card runtime environment to process an incoming APDU command.
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

equals

Constructor Detail

Applet

protected Applet()

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

Method Detail

getShareableInterfaceObject

public Shareable getShareableInterfaceObject(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

See Also:

JCSystem.getAppletShareableInterfaceObject(javacard.framework.AID, byte)

register

protected final void register()
                       throws 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:

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.

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.

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

process

public abstract void process(APDU apdu)
                      throws ISOException

Called by the Java Card runtime environment to process an incoming APDU command. An applet is expected to perform the action requested and return response data if any to the terminal.

Upon normal return from this method the Java Card runtime environment sends the ISO 7816-4 defined success status (90 00) in APDU response. If this method throws an ISOException the Java Card runtime environment sends the associated reason code as the response status instead.

The Java Card runtime environment zeroes out the APDU buffer before receiving a new APDU command from the CAD. The five header bytes of the APDU command are available in APDU buffer[0..4] at the time this method is called.

The APDU object parameter is a temporary Java Card runtime environment Entry Point Object. A temporary Java Card runtime environment Entry Point Object can be accessed from any applet context. References to these temporary objects cannot be stored in class variables or instance variables or array components.

Notes:

• APDU buffer[5..] is undefined and should not be read or written prior to invoking the APDU.setIncomingAndReceive() method if incoming data is expected. Altering the APDU buffer[5..] could corrupt incoming data.

Parameters:

apdu - the incoming APDU object

Throws:

ISOException - with the response bytes per ISO 7816-4

See Also:

APDU

install

public static void install(byte[] bArray,
                           short bOffset,
                           byte bLength)
                    throws 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:

ISOException - if the install method failed

register

protected final void register(byte[] bArray,
                              short bOffset,
                              byte bLength)
                       throws 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:

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.

See Also:

install(byte[], short, byte)

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