Applet (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.framework
Class Applet

    java.lang.Object
      javacard.framework.Applet

    @TransactionType(value=NOT_SUPPORTED)
    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.

A compliant Java Card platform may optionally support the ISO7816-4 defined extended length APDU protocol. The applet subclass must implement the `javacardx.apdu.ExtendedLength` interface to access this extended length APDU protocol capability of the `javacard.framework.APDU` object.

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`, `JCSystem`

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 application group 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 application group 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 SELECT APDU commands which may relate to file or internal applet state selection.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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 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[bOffset] = length(Li) of instance AID, bArray[bOffset+1..bOffset+Li] = instance AID bytes,
       bArray[bOffset+Li+1]= length(Lc) of control info, bArray[bOffset+Li+2..bOffset+Li+Lc+1] = control info,
       bArray[bOffset+Li+Lc+2] = length(La) of applet data, bArray[bOffset+Li+Lc+3..bOffset+Li+Lc+La+2] = 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, Java Card Platform, Connected Edition, chapter 6 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

### 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 (or optionally the 7 extended header bytes) of the APDU command are available in APDU buffer 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..] should not be 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`

### 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 application group 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, Java Card Platform, Classic Edition, chapter 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 application group 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 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, Java Card Platform, Classic Edition, chapter 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(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, Java Card Platform, Classic Edition, chapter 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, Java Card Platform, Classic Edition.

  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.

### 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, Java Card Platform, Classic Edition, chapter 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 SELECT APDU commands which may relate to file or internal applet state selection.

  Returns:
    `true` if `this` applet is being selected

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.