public abstract class Applet extends Object
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 ...
}
}
}
}
SystemException
,
JCSystem
Modifier | Constructor and Description |
---|---|
protected |
Applet()
Only this class's
install() method should create the
applet object. |
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.
|
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. |
protected static boolean |
reSelectingApplet()
This method is used by the applet's
process() method or
the select() method or applet's deselect() 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 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. |
protected Applet()
install()
method should create the
applet object.public static void install(byte[] bArray, short bOffset, byte bLength) throws ISOException
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 dataIn 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, Classic Edition,
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:
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.ISOException
- if the install method failedpublic abstract void process(APDU apdu) throws ISOException
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.setIncomingAndReceive()
method if incoming data is expected. Altering
the APDU buffer[5..] could corrupt incoming data.
apdu
- the incoming APDU
objectISOException
- with the response bytes per ISO 7816-4APDU
public boolean select()
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 its
process()
method. If this method returns false, it
indicates to the Java Card runtime environment that this Applet declines
to be selected.
Note:
javacard.framework.MultiSelectable.select(
) method is not
called if this method is invoked.
The implementation of this method provided by Applet
class
returns true
.
true
to indicate success, false
otherwisepublic void deselect()
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:
javacard.framework.MultiSelectable.deselect(
) method is not
called if this method is invoked.
JCSystem.CLEAR_ON_DESELECT
clear event type
are cleared to their default value by the Java Card runtime environment after this method.
public Shareable getShareableInterfaceObject(AID clientAID, byte parameter)
this
applet instance. The client applet initiated this
request by calling the
JCSystem.getAppletShareableInterfaceObject()
method. See
Runtime Environment Specification, Java Card Platform, Classic Edition,
section 6.2.4 for details.
Note:
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.
clientAID
- the AID
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.null
JCSystem.getAppletShareableInterfaceObject(AID, byte)
protected final void register() throws SystemException
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,
section 3.1 for details.
Note:
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.
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.
protected final void register(byte[] bArray, short bOffset, byte bLength) throws SystemException
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,
section 3.1 for details.
Note:
bArray
- the byte array containing the AID bytesbOffset
- the start of AID bytes in bArraybLength
- the length of the AID bytes in bArraySystemException
- 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.
install(byte[],short,byte)
protected final boolean selectingApplet()
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.true
if this
applet is being
selectedprotected static boolean reSelectingApplet()
process()
method or
the select()
method or applet's deselect()
method
to determine if it itself is being re-selected on this logical channel.
This method returns true
if and only if the currently selected applet was deselected on this
logical channel just prior to the current selection.true
if this
applet is being
re-selectedCopyright © 1998, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms