Migration guides are provided for the following transitions:

Others will be added when there are any API changes which deprecate or break compatibility with earlier releases.

v2.0.0-alpha-9 to v2.0.0-alpha-10

Addition of MRZ Parsing and Validation Support

New APIs have been added to support MRZ parsing and validation. These take the form of new methods in MRZ_Data, a new class ValidatedMRZ for MRZ data which has been parsed and validated, and a pair of new events in com.grabba.driver.mrz.MRZ_Listener MRZ_Listener which trigger when scanned MRZ data either passes or fails validation against the ICAO 9303 standard.

Existing code which uses the MRZ_Listener class (either via a handler or events) must be updated to receive the new events. For many applications this may supersede the existing handler for dataEvent. Code using the MRZ_Data class should also be updated to use the new per-line access methods and constructor rather than the now-deprecated all-in-one equivalents.

The MRTD APIs have also been updated to match the changed MRZ APIs; for most users, passing the ValidatedMRZ object received upon a successful MRZ read will suffice to start an MRTD read, replacing the old approach of passing the raw MRZ text. The new approach reduces the range of error conditions which may prevent the MRTD read from occurring successfully, since the MRZ data is guaranteed to already be valid.

Improved Smart Card Power Down Operation

The 2.0.0-alpha-10 release adds an extra parameter to SmartcardAPI.powerDown. A deprecated overload of this function is provided to allow it to be called using the older signature; this sets new parameter waitIfCardBusy to false. Code using this function should be able to build using the deprecated overload without any changes.

To migrate away from the now-deprecated form of the function, calling code should be modified to include the extra parameter - setting it to false retains the existing behaviour; setting it to true will ensure that the power-down operation takes place even if the card is presently busy with another operation.

1.0 series to 2.0 series

The 2.0 series is built atop Grabba's Unified %Driver Architecture, which involves significant changes to the APIs from the 1.0 series or earlier driver releases, but brings greater similarities between the Grabba driver releases on different platforms.

Driver API calls will need to be adjusted to account for the following changes:

Packages are provided for each technology - e.g. barcode functionality in com.grabba.driver.barcode - with only base types and core functions (e.g. connection handling) provided in top-level package com.grabba.driver.
Grabba prefixes have been removed - e.g. GrabbaBarcodeListener is now BarcodeListener
API classes which don't store data or provide callbacks now have an API suffix for clarity
The Grabba class has been replaced by CoreAPI
The Passport technology name has been renamed to MRZ, to avoid confusion vs MRTD
Singletons have been replaced by static methods, so it is no longer necessary to call e.g. getInstance()
Event callbacks are now managed by thread-safe listener classes (e.g. BarcodeListener):
- The recommended approach is to subclass the desired listener class, then make an object of that subclass
- Registration for callbacks is automatic when the listener-class/listener-subclass object is initialised
- Delegation is supported as an alternative to subclassing, for cases where your target class needs a different concrete (i.e. non-interface) parent class
Exceptions are only used sparingly; for common failure modes such as loss of connection, sentinel return values or error code parameters (see ErrorCode for details) are used instead.
API and listener classes are now all fully thread-safe (data classes are not though)
Some features (e.g. preferences) are not supported yet, so any code which uses them may need to be disabled

There have also been changes to methods and identifiers in various classes, so it will be necessary to refer to the documentation for each class to see how to interact with it.