javacard.framework.service
Class BasicService

java.lang.Object
  javacard.framework.service.BasicService

All Implemented Interfaces:

Service

Direct Known Subclasses:

RMIService

public class BasicService

extends Object

implements Service

This class should be used as the base class for implementing services. It provides a default implementation for the methods defined in the Service interface, and defines a set of helper methods that manage the APDU buffer to enable co-operation among different Services.

The BasicService class uses the state of APDU processing to enforce the validity of the various helper operations. It expects and maintains the following Common Service Format (CSF) of data in the APDU Buffer corresponding to the various APDU processing states (See APDU ):

 
  Init State format of APDU Buffer. This format corresponds to the
  APDU processing state - STATE_INITIAL :
   0     1    2    3    4    5  <- offset
  +------------------------------------------------------------+
  | CLA | INS | P1 | P2 | P3 | ... Implementation dependent ...|
  +------------------------------------------------------------+
 
 
  Input Ready format of APDU Buffer. This format corresponds
  to the APDU processing state - STATE_FULL_INCOMING.
   0     1    2    3    4    5  <- offset
  +------------------------------------------------------------+
  | CLA | INS | P1 | P2 | Lc | Incoming Data( Lc bytes )       |
  +------------------------------------------------------------+
 
 
  Output Ready format of APDU Buffer. This format corresponds
  to the APDU processing status - STATE_OUTGOING .. STATE_FULL_OUTGOING
   0     1    2     3     4    5  <- offset
  +------------------------------------------------------------+
  | CLA | INS | SW1 | SW2 | La | Outgoing Data( La bytes )     |
  +------------------------------------------------------------+
 
 
  
 

When the APDU buffer is in the Init and Input Ready formats, the helper methods allow input access methods but flag errors if output access is attempted. Conversely, when the APDU buffer is in the Output format, input access methods result in exceptions.

If the header areas maintained by the BasicService helper methods are modified directly in the APDU buffer and the format of the APDU buffer described above is not maintained, unexpected behavior might result.

In addition, both La=0 and La=256 are represented in the CSF format as La=0. The distinction is implementation dependent. The getOutputLength method must be used to avoid ambiguity.

Many of the helper methods also throw exceptions if the APDU object is in an error state ( processing status code < 0 ).

Version:

1.0

See Also:

APDU

Constructor Summary

BasicService()
Creates new BasicService.

Method Summary

boolean	fail(APDU apdu, short sw) Sets the processing state for the command in the APDU object to processed, and indicates that the processing has failed.
byte	getCLA(APDU apdu) Returns the class byte for the command in the APDU object.
byte	getINS(APDU apdu) Returns the instruction byte for the command in the APDU object.
short	getOutputLength(APDU apdu) Returns the output length for the command in the APDU object.
byte	getP1(APDU apdu) Returns the first parameter byte for the command in the APDU object.
byte	getP2(APDU apdu) Returns the second parameter byte for the command in the APDU object.
short	getStatusWord(APDU apdu) Returns the response status word for the command in the APDU object.
boolean	isProcessed(APDU apdu) Checks if the command in the APDU object has already been processed.
boolean	processCommand(APDU apdu) This BasicService method is a default implementation and simply returns false without performing any processing.
boolean	processDataIn(APDU apdu) This BasicService method is a default implementation and simply returns false without performing any processing.
boolean	processDataOut(APDU apdu) This BasicService method is a default implementation and simply returns false without performing any processing.
short	receiveInData(APDU apdu) Receives the input data for the command in the APDU object if the input has not already been received.
boolean	selectingApplet() This method is used to determine if the command in the APDU object is the applet SELECT FILE command which selected the currently selected applet.
void	setOutputLength(APDU apdu, short length) Sets the output length of the outgoing response for the command in the APDU object.
void	setProcessed(APDU apdu) Sets the processing state of the command in the APDU object to processed.
void	setStatusWord(APDU apdu, short sw) Sets the response status word for the command in the APDU object.
boolean	succeed(APDU apdu) Sets the processing state for the command in the APDU object to processed, and indicates that the processing has succeeded.
boolean	succeedWithStatusWord(APDU apdu, short sw) Sets the processing state for the command in the APDU object to processed, and indicates that the processing has partially succeeded.

Methods inherited from class java.lang.Object

equals

Constructor Detail

BasicService

public BasicService()

Creates new BasicService.

Method Detail

processDataOut

public boolean processDataOut(APDU apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:

processDataOut in interface Service

Parameters:

apdu - the APDU object containing the command being processed

Returns:

true if output processing is finished, false otherwise

getP1

public byte getP1(APDU apdu)
           throws ServiceException

Returns the first parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING.

Throws:

ServiceException

getINS

public byte getINS(APDU apdu)

Returns the instruction byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.

processDataIn

public boolean processDataIn(APDU apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:

processDataIn in interface Service

Parameters:

apdu - the APDU object containing the command being processed

Returns:

true if input processing is finished, false otherwise

setStatusWord

public void setStatusWord(APDU apdu,
                          short sw)

Sets the response status word for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.

fail

public boolean fail(APDU apdu,
                    short sw)
             throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has failed. Sets the output length to 0 and the status word of the response to the specified value.

Throws:

ServiceException

setOutputLength

public void setOutputLength(APDU apdu,
                            short length)
                     throws ServiceException

Sets the output length of the outgoing response for the command in the APDU object. This method can be called regardless of the current state of the APDU processing.

Throws:

ServiceException

processCommand

public boolean processCommand(APDU apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:

processCommand in interface Service

Parameters:

apdu - the APDU object containing the command being processed

Returns:

true if the command has been processed, false otherwise

succeedWithStatusWord

public boolean succeedWithStatusWord(APDU apdu,
                                     short sw)
                              throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has partially succeeded. Sets the the status word of the response to the specified value. The output length of the response must be set separately.

Throws:

ServiceException

getCLA

public byte getCLA(APDU apdu)

Returns the class byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.

getP2

public byte getP2(APDU apdu)
           throws ServiceException

Returns the second parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING.

Throws:

ServiceException

isProcessed

public boolean isProcessed(APDU apdu)

Checks if the command in the APDU object has already been processed. This is done by checking whether or not the APDU object has been set in outgoing mode via a previous invocation of the APDU.setOutgoing method.

Note:

• This method returns true if the APDU object is not accessible (APDU object in STATE_ERROR_.. ).

setProcessed

public void setProcessed(APDU apdu)
                  throws ServiceException

Sets the processing state of the command in the APDU object to processed. This is done by setting the APDU object in outgoing mode by invoking the APDU.setOutgoing method. If the APDU is already in outgoing mode, this method does nothing (allowing the method to be called several times).

Throws:

ServiceException

succeed

public boolean succeed(APDU apdu)
                throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has succeeded. Sets the status word of the response to 0x9000. The output length of the response must be set separately.

Throws:

ServiceException

receiveInData

public short receiveInData(APDU apdu)
                    throws ServiceException

Receives the input data for the command in the APDU object if the input has not already been received. The entire input data must fit in the APDU buffer starting at offset 5. When invoked, the APDU object must either be in STATE_INITIAL with the APDU buffer in the Init format or in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format

Throws:

ServiceException

getOutputLength

public short getOutputLength(APDU apdu)
                      throws ServiceException

Returns the output length for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been processed.

Throws:

ServiceException

selectingApplet

public boolean selectingApplet()

This method is used to determine if the command in the APDU object is the applet SELECT FILE command which selected the currently selected applet.

getStatusWord

public short getStatusWord(APDU apdu)
                    throws ServiceException

Returns the response status word for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been processed.

Throws:

ServiceException