Package ch.swisscom.mid.client

Interface MIDClient

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
MIDClientImpl
public interface MIDClient extends AutoCloseable
Main interface for the Mobile ID client library. This provides access to the main Mobile ID services, as documented in the Mobile ID Reference Guide (go to Mobile ID documentation, then open the Client Reference Guide).

Operations implemented:

  • MSS Signature (sync mode)
  • MSS Signature (async mode) with status polling
  • MSS Receipt (for a finished MSS Signature)
  • MSS Profile Query

Technically wise, this MID Client library provides the following:

  • Access to the Additional Services per MSS Signature
  • Easy access to Status Codes, Trial Numbers
  • Configurable validation of received signatures
  • REST and SOAP implementation (depends on what you include in the classpath and select in the client configuration)
  • Simple access and handling for network issues (connection timeout, response timeout, TLS handshake)
  • Pluggable model, easy to swap out components and add your own
  • Interfaces everywhere, easy to test and mock
  • Thread-safe and connection-pooled default configuration; you can create one of these clients and use it for all you connections

  • Method Details

    • requestSyncSignature

      SignatureResponse requestSyncSignature(SignatureRequest request)
      Requests a MSS Signature to the connected Mobile ID service, using synchronous communication (the client's thread is blocked until the final response is received; this could take a while, e.g. 80 seconds, so make sure that the HTTP response timeout is properly set in the client configuration otherwise a timeout will occur). The response is returned to the caller or, if something breaks during the communication, a MIDClientException is thrown.
      Parameters:
      request - the MSS Signature request to send
      Returns:
      the response, as received from the Mobile ID service.
      Throws:
      ConfigurationException - if something is missing from the client configuration, or is badly configuration
      MIDFlowException - if something fails during the communication with the backend services

    • requestAsyncSignature

      SignatureResponse requestAsyncSignature(SignatureRequest request)
      Requests a MSS Signature to the connected Mobile ID service, using asynchronous communication (the method terminates immediately, returning a signature object that is mostly empty, with a inner signature tracking object; the caller is expected to poll for the status of this MSS Signature flow by repeatedly calling pollForSignatureStatus(SignatureTracking) with the aforementioned signature tracking object). The method returns either with a response object and a tracking object to use in subsequent polls or by throwing an exception is something is misaligned.
      Parameters:
      request - the MSS Signature request to send
      Returns:
      a signature response object, containing the tracking element to use in subsequent polls.
      Throws:
      ConfigurationException - if something is missing from the client configuration, or is badly configuration
      MIDFlowException - if something fails during the communication with the backend services

    • pollForSignatureStatus

      SignatureResponse pollForSignatureStatus(SignatureTracking signatureTracking)
      Poll for the status of a previously requested asynchronous MSS Signature. The caller is expected to check the Status object from the returned response in order to learn about the current status of the signature flow. If the signature is not finished, the caller needs to poll again, with the same input tracking object.
      Parameters:
      signatureTracking - the signature tracking object received from the call to requestAsyncSignature(SignatureRequest)
      Returns:
      a response object that contains only the Status populated with an intermediary status value or the final signature response
      Throws:
      MIDFlowException - if something fails during the communication with the backend services

    • requestSyncReceipt

      ReceiptResponse requestSyncReceipt(SignatureTracking signatureTracking, ReceiptRequest request)
      A receipt can be sent to the mobile user that has just finished a digital signature. The call is synchronous and optional. Making such a call allows the AP to send a confirmation message to the mobile user (e.g. "Access granted").
      Parameters:
      signatureTracking - the signature tracking object received from the call to requestAsyncSignature(SignatureRequest) or requestSyncSignature(SignatureRequest)
      request - the request data additional to what the signatureTracking already provides
      Returns:
      a response object containing the status of the operation.

    • requestProfile

      ProfileResponse requestProfile(ProfileRequest request)
      The profile of a mobile user can be queried using this method. No interaction with the mobile user is performed. The backend just returns whatever data is available for the designated mobile user. This operation is synchronous.
      Parameters:
      request - the profile request data
      Returns:
      a response object containing the status outcome of the operation and the requested profile data.

    • close

      void close()
      Disposes any internal resources allocated by this instance of the MID Client. This method should be used ONLY when the MID Client cannot be used anymore (e.g. it is really not needed and needs to go away). The implementation of MID Client should be thread-safe and resource pooled, so that it can be reused in as many threads and for as long as possible. Call this method only when your app is shutting down or you really don't need the client anymore.
      Specified by:
      close in interface AutoCloseable