javacard.framework.service
Class Dispatcher

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

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.

Version:

1.0

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

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