Dispatcher (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 Dispatcher

    java.lang.Object
      javacard.framework.service.Dispatcher

    @TransactionType(value=SUPPORTS)
    public class Dispatcher

extends Object

A `Dispatcher` is used to build an application by aggregating several services.

The dispatcher maintains a registry of `Service` objects. A `Service` is categorized by the type of processing it performs:

- A pre-processing service pre-processes input data for the command being processed. It is associated with the `PROCESS_INPUT_DATA` phase.
- A command processing service processes the input data and generates output data. It is associated with the `PROCESS_COMMAND` phase.
- A post-processing service post-processes the generated output data. It is associated with the `PROCESS_OUTPUT_DATA` phase.

The dispatcher simply dispatches incoming `APDU` object containing the command being processed to the registered services.

Field Summary
`static byte` | `PROCESS_COMMAND` Identifies the main command processing phase.
`static byte` | `PROCESS_INPUT_DATA` Identifies the input data processing phase.
`static byte` | `PROCESS_NONE` Identifies the null processing phase.
`static byte` | `PROCESS_OUTPUT_DATA` Identifies the output data processing phase.

Constructor Summary
`Dispatcher(short maxServices)` Creates a `Dispatcher` with a designated maximum number of services.

Method Summary
`void` | `addService(Service service, byte phase)` Atomically adds the specified service to the dispatcher registry for the specified processing phase.
`Exception` | `dispatch(APDU command, byte phase)` Manages the processing of the command in the `APDU` object.
`void` | `process(APDU command)` Manages the entire processing of the command in the APDU object input parameter.
`void` | `removeService(Service service, byte phase)` Atomically removes the specified service for the specified processing phase from the dispatcher registry.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### PROCESS_NONE

    public static final byte PROCESS_NONE

  Identifies the null processing phase.

  See Also:
    Constant Field Values

### PROCESS_INPUT_DATA

    public static final byte PROCESS_INPUT_DATA

  Identifies the input data processing phase.

  See Also:
    Constant Field Values

### PROCESS_COMMAND

    public static final byte PROCESS_COMMAND

  Identifies the main command processing phase.

  See Also:
    Constant Field Values

### PROCESS_OUTPUT_DATA

    public static final byte PROCESS_OUTPUT_DATA

  Identifies the output data processing phase.

  See Also:
    Constant Field Values

Constructor Detail

### Dispatcher

    public Dispatcher(short maxServices)
               throws ServiceException

  Creates a `Dispatcher` with a designated maximum number of services.

  Parameters:
    `maxServices` - the maximum number of services that can be registered to this dispatcher
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.ILLEGAL_PARAM` if the maxServices parameter is negative.

Method Detail

### addService

    public void addService(Service service,
                           byte phase)
                    throws ServiceException

  Atomically adds the specified service to the dispatcher registry for the specified processing phase. Services are invoked in the order in which they are added to the registry during the processing of that phase. If the requested service is already registered for the specified processing phase, this method does nothing.

  Parameters:
    `service` - the Service to be added to the dispatcher
    `phase` - the processing phase associated with this service
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.DISPATCH_TABLE_FULL` if the maximum number of registered services is exceeded.
    - `ServiceException.ILLEGAL_PARAM` if the phase parameter is undefined or if the service parameter is null.

### removeService

    public void removeService(Service service,
                              byte phase)
                       throws ServiceException

  Atomically removes the specified service for the specified processing phase from the dispatcher registry. Upon removal, the slot used by the specified service in the dispatcher registry is available for re-use. If the specified service is not registered for the specified processing phase, this method does nothing.

  Parameters:
    `service` - the `Service` to be deleted from the dispatcher
    `phase` - the processing phase associated with this service
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.ILLEGAL_PARAM` if the phase parameter is unknown or if the service parameter is null.

### dispatch

    public Exception dispatch(APDU command,
                              byte phase)
                       throws ServiceException

  Manages the processing of the command in the `APDU` object. This method is called when only partial processing using the registered services is required or when the APDU response following an error during the processing needs to be controlled.

  It sequences through the registered services by calling the appropriate processing methods. Processing starts with the phase indicated in the input parameter. Services registered for that processing phase are called in the sequence in which they were registered until all the services for the processing phase have been called or a service indicates that processing for that phase is complete by returning `true` from its processing method. The dispatcher then processes the next phases in a similar manner until all the phases have been processed. The `PROCESS_OUTPUT_DATA` processing phase is performed only if the command processing has completed normally (`APDU` object state is `APDU.STATE_OUTGOING`).

  The processing sequence is `PROCESS_INPUT_DATA` phase, followed by the `PROCESS_COMMAND` phase and lastly the `PROCESS_OUTPUT_DATA`. The processing is performed as follows:

  - `PROCESS_INPUT_DATA` phase invokes the `Service.processDataIn(APDU)` method
  - `PROCESS_COMMAND` phase invokes the `Service.processCommand(APDU)` method
  - `PROCESS_OUTPUT_DATA` phase invokes the `Service.processDataOut(APDU)` method
  If the command processing completes normally, the output data, assumed to be in the APDU buffer in the Common Service Format (CSF) defined in `BasicService`, is sent using `APDU.sendBytes` and the response status is generated by throwing an `ISOException` exception. If the command could not be processed, `null` is returned. If any exception is thrown by a Service during the processing, that exception is returned.

  Parameters:
    `command` - the APDU object containing the command to be processed
    `phase` - the processing phase to perform first
  Returns:
    an exception that occurred during the processing of the command, or `null` if the command could not be processed
  Throws:
    `ServiceException` - with the following reason code:
    - `ServiceException.ILLEGAL_PARAM` if the phase parameter is PROCESS_NONE or an undefined value.
  See Also:
    `BasicService`

### process

    public void process(APDU command)
                 throws ISOException

  Manages the entire processing of the command in the APDU object input parameter. This method is called to delegate the complete processing of the incoming APDU command to the configured services.

  This method uses the `dispatch(APDU,byte)` method with `PROCESS_INPUT_DATA` as the input phase parameter to sequence through the services registered for all three phases : `PROCESS_INPUT_DATA` followed by `PROCESS_COMMAND` and lastly `PROCESS_OUTPUT_DATA`.

  If the command processing completes normally, the output data is sent using `APDU.sendBytes` and the response status is generated by throwing an `ISOException` exception or by simply returning (for status = 0x9000). If an exception is thrown by any Service during the processing, `ISO7816.SW_UNKNOWN` response status code is generated by throwing an `ISOException`. If the command could not be processed `ISO7816.SW_INS_NOT_SUPPORTED` response status is generated by throwing an `ISOException`.

  Note:

  - If additional command processing is required following a call to this method, the caller should catch and process exceptions thrown by this method.

  Parameters:
    `command` - the APDU object containing command to be processed
  Throws:
    `ISOException` - with the response bytes per ISO 7816-4

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.