Package javacard.framework.service

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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Constructor Description
      Dispatcher​(short maxServices)
      Creates a Dispatcher with a designated maximum number of services.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.

    • 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