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.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 thejavacard.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
Constructors Modifier Constructor Description protected
Applet()
Only this class'sinstall()
method should create the applet object.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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.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 theApplet
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 registerthis
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 registerthis
applet instance with the Java Card runtime environment and assign the specified AID bytes as its instance AID bytes.protected static boolean
reSelectingApplet()
This method is used by the applet'sprocess()
method or theselect()
method or applet'sdeselect()
method to determine if it itself is being re-selected on this logical channel.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 appletprocess()
method to distinguish the SELECT APDU command which selectedthis
applet, from all other SELECT APDU commands which may relate to file or internal applet state selection.
-
-
-
Method Detail
-
install
public static void install(byte[] bArray, short bOffset, byte bLength) throws ISOException
To create an instance of theApplet
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 toregister()
completes without an exception. The installation is deemed unsuccessful if theinstall
method does not call aregister()
method, or if an exception is thrown from within theinstall
method prior to the call to aregister()
method, or if every call to theregister()
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 theinstall()
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, Classic Edition, section 6.2.2 for details.The implementation of this method provided by
Applet
class throws anISOException
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 parametersbOffset
- the starting offset in bArraybLength
- 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 incomingAPDU
object- Throws:
ISOException
- with the response bytes per ISO 7816-4- See Also:
APDU
- APDU buffer[5..] should not be written prior to invoking the
-
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, Java Card Platform, Classic Edition, 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 itsprocess()
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 returnstrue
.- Returns:
true
to indicate success,false
otherwise
- The
-
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'sselect()
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.
- The
-
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 ofthis
applet instance. The client applet initiated this request by calling theJCSystem.getAppletShareableInterfaceObject()
method. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.4 for details.Note:
- The
clientAID
parameter is a Java Card runtime environment-ownedAID
instance. Java Card runtime environment-owned instances ofAID
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
- theAID
object of the client appletparameter
- 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)
- The
-
register
protected final void register() throws SystemException
This method is used by the applet to registerthis
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 theregister()
methods must be called from withininstall()
to be registered with the Java Card runtime environment. See Runtime Environment Specification, Java Card Platform, Classic Edition, 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 theapplets[]
item of theapplet_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 theApplet
subclass AID bytes are in use or if the applet instance has previously successfully registered with the Java Card runtime environment via one of theregister()
methods or if a Java Card runtime environment initiatedinstall()
method execution is not in progress.
- The phrase "Java Card platform name of the applet" is a reference to the
-
register
protected final void register(byte[] bArray, short bOffset, byte bLength) throws SystemException
This method is used by the applet to registerthis
applet instance with the Java Card runtime environment and assign the specified AID bytes as its instance AID bytes. One of theregister()
methods must be called from withininstall()
to be registered with the Java Card runtime environment. See Runtime Environment Specification, Java Card Platform, Classic Edition, 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 bytesbOffset
- the start of AID bytes in bArraybLength
- the length of the AID bytes in bArray- Throws:
SystemException
- with the following reason code:SystemException.ILLEGAL_VALUE
if thebLength
parameter is less than5
or greater than16
.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 theregister()
methods or if a Java Card runtime environment-initiatedinstall()
method execution is not in progress.
- See Also:
install(byte[],short,byte)
-
selectingApplet
protected final boolean selectingApplet()
This method is used by the appletprocess()
method to distinguish the SELECT APDU command which selectedthis
applet, from all other SELECT APDU commands which may relate to file or internal applet state selection.- Returns:
true
ifthis
applet is being selected
-
reSelectingApplet
protected static boolean reSelectingApplet()
This method is used by the applet'sprocess()
method or theselect()
method or applet'sdeselect()
method to determine if it itself is being re-selected on this logical channel. This method returnstrue
if and only if the currently selected applet was deselected on this logical channel just prior to the current selection.- Returns:
true
ifthis
applet is being re-selected- Since:
- 3.0.4
-
-