BasicService (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.framework.service
Class BasicService

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

All Implemented Interfaces:
  Service

Direct Known Subclasses:
  RMIService

    @TransactionType(value=SUPPORTS)
    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.

The Common Service Format (CSF) of the APDU Buffer is only defined for APDUs using the short length (normal semantics) of the ISO7816 protocol. When an implementation supports extended length APDU format (see `ExtendedLength`) and an APDU with more than 255 input or output data bytes is being processed, the behavior of `BasicService` class is undefined.

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 ).

See Also:
  `APDU`, `javacardx.apdu.ExtendedLength`

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, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### BasicService

    public BasicService()

  Creates new `BasicService`.

Method Detail

### 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:
    `false`

### 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:
    `false`

### 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:
    `false`

### 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

  Parameters:
    `apdu` - the `APDU` object containing the apdu being processed
  Returns:
    the length of input data received and present in the APDU Buffer
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_IN_COMMAND` if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING or,
    - `ServiceException.COMMAND_DATA_TOO_LONG` if the input data does not fit in the APDU buffer starting at offset 5.

### 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).

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_OUT_COMMAND` if the APDU object is not accessible (APDU object in STATE_ERROR_.. )
  See Also:
    `javacard.framework.APDU.getCurrentState()`

### 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_.. ).

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
  Returns:
    `true` if the command has been processed, `false` otherwise

### 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.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
    `length` - the number of bytes in the response to the command
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.ILLEGAL_PARAM` if the `length` parameter is greater than 256 or if the outgoing response will not fit within the APDU Buffer.

### 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.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
  Returns:
    a value in the range: 0 to 256(inclusive), that represents the number of bytes to be returned for this command
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_OUT_COMMAND` if the command is not processed or if the APDU object is not accessible (APDU object in STATE_ERROR_.. )
  See Also:
    `javacard.framework.APDU.getCurrentState()`

### 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.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
    `sw` - the status word response for this command

### 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.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
  Returns:
    the status word response for this command
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_OUT_COMMAND` if the command is not processed or if the APDU object is not accessible (APDU object in STATE_ERROR_.. )
  See Also:
    `javacard.framework.APDU.getCurrentState()`

### 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.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
    `sw` - the status word response for this command
  Returns:
    `true`
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_OUT_COMMAND` if the APDU object is not accessible (APDU object in STATE_ERROR_.. )
  See Also:
    `javacard.framework.APDU.getCurrentState()`

### 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.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed.
  Returns:
    `true`
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_OUT_COMMAND` if the APDU object is not accessible (APDU object in STATE_ERROR_.. )
  See Also:
    `javacard.framework.APDU.getCurrentState()`

### 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 status word of the response to the specified value. The output length of the response must be set separately.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
    `sw` - the status word to be returned for this command
  Returns:
    `true`
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_OUT_COMMAND` if the APDU object is not accessible (APDU object in STATE_ERROR_.. )
  See Also:
    `javacard.framework.APDU.getCurrentState()`

### 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.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
  Returns:
    the value of the CLA byte

### 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.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
  Returns:
    the value of the INS byte

### 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`.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
  Returns:
    the value of the P1 byte
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_IN_COMMAND` if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING.

### 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`.

  Parameters:
    `apdu` - the `APDU` object containing the command being processed
  Returns:
    the value of the P2 byte
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.CANNOT_ACCESS_IN_COMMAND` if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING.

### 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.

  Returns:
    `true` if applet SELECT FILE command is being processed

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.