|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javacard.framework.Applet
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 ...
}
}
}
}
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 |
protected Applet()
install()
method should create the applet object.
Method Detail |
public static void install(byte[] bArray, short bOffset, byte bLength) throws ISOException
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:
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.
ISOException
public abstract void process(APDU apdu) throws ISOException
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:
APDU.setIncomingAndReceive()
method if incoming data is expected. Altering
the APDU buffer[5..] could corrupt incoming data.
apdu
- the incoming APDU
object
ISOException
- with the response bytes per ISO 7816-4APDU
public boolean select()
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
.
true
to indicate success, false
otherwise.public 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:
JCSystem.CLEAR_ON_DESELECT
clear event type
are cleared to their default value by the JCRE 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 Java Card Runtime Environment (JCRE) Specification, section 6.2.4 for details.
Note:
clientAID
parameter is a JCRE owned AID
instance. JCRE owned instances of AID
are permanent JCRE
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 applet.parameter
- 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 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:
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.
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.
protected final void register(byte[] bArray, short bOffset, byte bLength) throws SystemException
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.
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.
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:
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.
protected final boolean selectingApplet()
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.
true
if this
applet is being selected.
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |