javacard.framework
Class Applet

java.lang.Object
  extended byjavacard.framework.Applet

public abstract class Applet
extends Object

This abstract class defines an applet in Java Card.

The Applet class should be extended by any applet that is intended to be loaded onto, installed into and executed on a Java Card 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
   byte bLen = bArray[bOffset];
   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, JCSystem

Constructor Summary
protected Applet()
          Only this class's install() method should create the applet object.
 
Method Summary
 void deselect()
          Called by the JCRE to inform this currently selected applet that another (or the same) applet will be selected.
 Shareable getShareableInterfaceObject(AID clientAID, byte parameter)
          Called by the JCRE 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 JCRE will call this static method first.
abstract  void process(APDU apdu)
          Called by the JCRE to process an incoming APDU command.
protected  void register()
          This method is used by the applet to register this applet instance with the JCRE and to assign the Java Card 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 JCRE and assign the specified AID bytes as its instance AID bytes.
 boolean select()
          Called by the JCRE to inform this applet that it has been selected.
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

install

public static void install(byte[] bArray,
                           short bOffset,
                           byte bLength)
                    throws ISOException
To create an instance of the Applet subclass, the JCRE 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 JCRE 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 defined by the applet. 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 JCRE 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 Java Card Runtime Environment (JCRE) Specification, 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:

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 32.
Throws:
ISOException

process

public abstract void process(APDU apdu)
                      throws ISOException
Called by the JCRE 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 JCRE sends the ISO 7816-4 defined success status (90 00) in APDU response. If this method throws an ISOException the JCRE sends the associated reason code as the response status instead.

The JCRE 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 JCRE Entry Point Object. A temporary JCRE 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:

Parameters:
apdu - the incoming APDU object
Throws:
ISOException - with the response bytes per ISO 7816-4
See Also:
APDU

select

public boolean select()
Called by the JCRE to inform this applet that it has been selected.

It is called when a SELECT APDU command is received and before the applet is selected. SELECT APDU commands use instance AID bytes for applet selection. See Java Card Runtime Environment (JCRE) Specification, section 4.2 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 JCRE that this Applet declines to be selected.

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 JCRE to inform this currently selected applet that another (or the same) applet will be selected. It is called when a SELECT APDU command is received by the JCRE. This method is invoked prior to another applets or this very applets 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:


getShareableInterfaceObject

public Shareable getShareableInterfaceObject(AID clientAID,
                                             byte parameter)
Called by the JCRE 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 Java Card Runtime Environment (JCRE) Specification, section 6.2.4 for details.

Note:

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(AID, byte)

register

protected final void register()
                       throws SystemException
This method is used by the applet to register this applet instance with the JCRE and to assign the Java Card 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 JCRE. See Java Card Runtime Environment (JCRE) Specification, section 3.1 for details.

Note:

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 JCRE via one of the register() methods or if a JCRE initiated install() method execution is not in progress.

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 JCRE 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 JCRE. See Java Card Runtime Environment (JCRE) Specification, section 3.1 for details.

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 RID portion of the AID bytes in the bArray parameter does not match the RID portion of the Java Card name of the applet or if the applet instance has previously successfully registered with the JCRE via one of the register() methods or if a JCRE initiated install() method execution is not in progress.

Note:

  • The phrase "Java card 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 Java Card Virtual Machine Specification.

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.


Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.