**javacard.framework.service** ====Class Dispatcher ==== *[[javacard:java-card-api:object|java.lang.Object]] \\ ---- public class **Dispatcher**extends [[javacard:java-card-api:Object|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 outputdata. 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** | **[[javacard:java-card-api:Dispatcher#PROCESS_COMMAND|PROCESS_COMMAND]] **          Identifies the main command processing phase. | | **static byte** | **[[javacard:java-card-api:Dispatcher#PROCESS_INPUT_DATA|PROCESS_INPUT_DATA]] **          Identifies the input data processing phase. | | **static byte** | **[[javacard:java-card-api:Dispatcher#PROCESS_NONE|PROCESS_NONE]] **          Identifies the null processing phase. | | **static byte** | **[[javacard:java-card-api:Dispatcher#PROCESS_OUTPUT_DATA|PROCESS_OUTPUT_DATA]] **          Identifies the output data processing phase. |   ^ Constructor Summary ^^ | **[[javacard:java-card-api:Dispatcher#Dispatcher(short)|Dispatcher]] **(short maxServices)          Creates a Dispatcher with a designated maximum number of services. |   ^ Method Summary ^^ | ** void** | **[[javacard:java-card-api:Dispatcher#addService(javacard.framework.service.Service, byte)|addService]] **([[javacard:java-card-api:Service|Service]]  service,byte phase)          Atomically adds the specified service to the dispatcher registry for the specified processing phase. | | ** [[javacard:java-card-api:Exception|Exception]] ** | **[[javacard:java-card-api:Dispatcher#dispatch(javacard.framework.APDU, byte)|dispatch]] **([[javacard:java-card-api:APDU|APDU]]  command,byte phase)          Manages the processing of the command in the APDU object. | | ** void** | **[[javacard:java-card-api:Dispatcher#process(javacard.framework.APDU)|process]] **([[javacard:java-card-api:APDU|APDU]]  command)          Manages the entire processing of the command in the APDU object input parameter. | | ** void** | **[[javacard:java-card-api:Dispatcher#removeService(javacard.framework.service.Service, byte)|removeService]] **([[javacard:java-card-api:Service|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 ^ | [[javacard:java-card-api:Object#equals(java.lang.Object)|equals]] |   ^ Field Detail ^ === PROCESS_NONE === public static final byte **PROCESS_NONE** Identifies the null processing phase. **See Also:**[[javacard:java-card-api:constant-values#javacard.framework.service.Dispatcher.PROCESS_NONE|Constant Field Values]] ---- === PROCESS_INPUT_DATA === public static final byte **PROCESS_INPUT_DATA** Identifies the input data processing phase. **See Also:**[[javacard:java-card-api:constant-values#javacard.framework.service.Dispatcher.PROCESS_INPUT_DATA|Constant Field Values]] ---- === PROCESS_COMMAND === public static final byte **PROCESS_COMMAND** Identifies the main command processing phase. **See Also:**[[javacard:java-card-api:constant-values#javacard.framework.service.Dispatcher.PROCESS_COMMAND|Constant Field Values]] ---- === PROCESS_OUTPUT_DATA === public static final byte **PROCESS_OUTPUT_DATA** Identifies the output data processing phase. **See Also:**[[javacard:java-card-api:constant-values#javacard.framework.service.Dispatcher.PROCESS_OUTPUT_DATA|Constant Field Values]] ^ Constructor Detail ^ === Dispatcher === public **Dispatcher**(short maxServices) throws [[javacard:java-card-api:ServiceException|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:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.ILLEGAL_PARAM if the maxServices parameteris negative. \\ ^ Method Detail ^ === addService === public void **addService**([[javacard:java-card-api:Service|Service]]  service, byte phase) throws [[javacard:java-card-api:ServiceException|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:** [[javacard:java-card-api:ServiceException|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**([[javacard:java-card-api:Service|Service]]  service, byte phase) throws [[javacard:java-card-api:ServiceException|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:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.ILLEGAL_PARAM if the phase parameter is unknown or if the service parameter is null. \\ ---- === dispatch === public [[javacard:java-card-api:Exception|Exception]] **dispatch**([[javacard:java-card-api:APDU|APDU]]  command, byte phase) throws [[javacard:java-card-api:ServiceException|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:** [[javacard:java-card-api:ServiceException|ServiceException]] - with the following reason code: \\ *ServiceException.ILLEGAL_PARAM if the phase parameter is PROCESS_NONE or an undefined value. \\ **See Also:**[[javacard:java-card-api:BasicService|BasicService]] ---- === process === public void **process**([[javacard:java-card-api:APDU|APDU]]  command) throws [[javacard:java-card-api:ISOException|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 [[javacard:java-card-api:Dispatcher#dispatch(javacard.framework.APDU, byte)|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:** [[javacard:java-card-api:ISOException|ISOException]] - with the response bytes per ISO 7816-4