|
Java Card 2.1 Platform Final Revision 1.0 |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | 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 Applet subclass AID bytes 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.
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 the register()
method throws 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) 2.1 Specification 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.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
objectAPDU
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) 2.1 Specification 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) 2.1 Specification for details.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
.
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.
JCSystem.getAppletShareableInterfaceObject(AID, byte)
protected final void register() throws SystemException
this
applet instance with
the JCRE and to
assign the Applet
subclass 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) 2.1 Specification for details.SystemException.ILLEGAL_AID
if the Applet
subclass AID bytes are in use or
if the applet instance has previously called one of the register()
methods.
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) 2.1 Specification 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.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 Applet
subclass AID bytes or
if the applet instance has previously called one of the register()
methods.
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.
|
Submit a bug or feature Java and Java Card are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |