|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectjavacard.framework.Applet
public abstract class Applet
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.
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 ...
}
}
}
}
JCSystem,
SystemException| 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 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. |
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
other SELECT APDU commands which may relate to file or internal applet state selection. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| 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 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[0] = length(Li) of instance AID, bArray[1..Li] = instance AID bytes, bArray[Li+1]= length(Lc) of control info, bArray[Li+2..Li+Lc+1] = control info, bArray[Li+Lc+2] = length(La) of applet data, bArray[Li+Lc+2..Li+Lc+La+1] = 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 for the Java Card Platform, 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 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 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 object
ISOException - with the response bytes per ISO 7816-4APDUpublic 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 for the Java Card Platform, 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 for the Java Card Platform, 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
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 for the Java Card Platform, 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 for the Java Card Platform.
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 for the Java Card Platform, 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 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 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 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 | |||||||||